How the PR Multi-Agent System works

This is a small multi-agent system (MAS) that acts like a junior PR researcher. It searches the web for candidate partners or clients, researches them, judges how well they fit our company, and writes a sourced report for a human to review.

The big idea

Agents are stateless. They receive a brief, do one job, and return a result. All memory lives in the Knowledge Base (SQLite).
Company facts live in a Markdown file. docs/COMPANY_PROFILE.md defines our offers, ideal customer profile (ICP), and claim rules. Change the file, not the code.
Humans decide. The system proposes organizations and reports; a person labels them relevant, saved, or out of scope.
Everything is logged. Every agent call, tool call, and flow transition is stored in the audit log.

The agents

Agent	Type	Job	Input	Output
Prospector	Flow-specific	Turns the ICP into search queries, runs them, and extracts candidate organizations.	Company Profile + target segments	List of discovered organizations
Qualifier (quick)	Shared	Cheap first-pass fit screen using only search snippets.	Name, website, snippets, Company Profile	Segment + score + reason
Researcher	Shared	Gathers public facts about one organization using web search and page fetching. Every fact cites a source.	Organization name/website + Company Profile	Structured research report
Qualifier (full)	Shared	Judges fit after deep research and suggests an outreach angle.	Research report + Company Profile	Full fit assessment

How the agents interact

The Prospecting flow is a state machine. Plain code decides the next step; agents only provide judgment or facts.

graph LR A[Prospector] -->|generates queries| B[web_search] B -->|search results| A A -->|candidates| C[Dedupe] C -->|new org| D[Qualifier quick] D -->|score| E{Gate} E -->|below threshold| F[Skip] E -->|above threshold| G[Researcher] G -->|uses| H[web_search] G -->|uses| I[fetch_page] G -->|report| J[Qualifier full] J -->|fit assessment| K[Save report] K -->|next candidate| C

Discover: The Prospector reads the ICP and asks an LLM to generate search queries per segment.
Search: The web_search tool runs each query through DuckDuckGo.
Extract: The Prospector extracts real organizations from the search results.
Dedupe: Plain code checks the Knowledge Base by website or normalized name.
Quick screen: The Qualifier scores fit cheaply using only snippets.
Gate: If the score is below the threshold, the candidate is skipped.
Deep research: The Researcher searches and reads pages, returning cited facts.
Full qualification: The Qualifier writes fit reasons, an outreach angle, concerns, and how to reach them.
Save: The report is stored in the Knowledge Base.
Human review: A person opens the report in the web dashboard and labels it.

Tools

Tools are thin wrappers around external systems. They do not decide anything.

web_search — DuckDuckGo search, returns structured results.
fetch_page — downloads a URL and extracts readable text with BeautifulSoup.

Cost-control funnel

The quick Qualifier uses a cheap model and runs on many candidates. Only the high scorers get expensive deep research. This keeps the average cost per run low.

Human-in-the-loop

The system never contacts anyone by itself. It only writes reports. A person reviews each report and labels it:

Relevant — worth pursuing
Saved for later — interesting, but not now
Out of scope — not a fit, with a reason
Do not contact — permanent suppression

These labels become the historical record and, eventually, training examples for improving the Qualifier.