GTM Signal Crew

A three-agent go-to-market intelligence pipeline built on CrewAI. The agents share one retrieval tool: a remote MCP server that fronts a web-knowledge index with separate news and people scopes. A Streamlit UI shows each stage finishing and renders the ranked contact cards.

1. Signal Hunter queries the news scope for trigger events at a list of target companies inside a time window: leadership hires, funding rounds, product launches, expansions.
2. People Enricher takes every person named in those events and queries the people scope for their full career record (roles with dates, prior companies, education).
3. Outreach Strategist has no tools. It merges both outputs into a ranked contact list: the trigger event, the person's background and a first outreach line written around the signal.

Why

Outbound works when it is anchored on something that just happened. The three jobs above are separable: discovery is a news problem, enrichment is a people-data problem, and writing is a judgement problem. Splitting them into agents keeps each prompt short, lets the retrieval tool be swapped without touching the writing step, and makes the ranking deterministic: pipeline.py computes recency x seniority in plain Python so the list is reproducible and testable, and the LLM only contributes the prose.

Practical guidance that the prompts follow: use open web search for discovery and the single most senior exec; use the structured people scope for the director/regional layer and for depth. The news scope is where a hire or a round first shows up; the people scope is where you find the director who will actually own the project and the dates that make the opener credible.

Code map

gtm-signal-crew/
├── gtm_crew/
│   ├── __init__.py       re-exports the models
│   ├── models.py         Signal / Profile / Role / OutreachDraft / Contact (+ *List wrappers);
│   │                     event-type synonym normalisation
│   ├── mcp_config.py     builds the MCP connection for agents 1 and 2: native
│   │                     MCPServerHTTP config or the wrapper tool, chosen by GTM_MCP_MODE
│   ├── mcp_tool.py       MCPSearchTool(BaseTool): thin streamable-HTTP client for the
│   │                     server's `search` tool (fallback mechanism, see below)
│   ├── llm.py            LLM from env: OpenAI, OpenAI-compatible base URL, or OpenRouter
│   ├── agents.py         the three Agent definitions (+ AGENT_SUMMARY for the sidebar)
│   ├── tasks.py          three Tasks with output_pydantic schemas and context chaining
│   ├── crew.py           build_crew(companies, window_days, mcps) -> Crew (sequential);
│   │                     run_pipeline() kicks off and post-processes
│   ├── pipeline.py       pure Python: merge signals + profiles, recency x seniority
│   │                     ranking, outreach templates, JSON extraction (unit tested)
│   └── demo_data.py      fixture signals/profiles (fictional companies and people)
├── app.py                Streamlit UI; DEMO_MODE=1 uses fixtures without LLM/MCP
├── run.py                CLI: --demo prints the ranked list; otherwise runs the crew
├── tests/
│   ├── test_pipeline.py      scoring, merge, ranking, templates, JSON parsing
│   ├── test_mcp.py           env config + round trip against a local FastMCP server
│   ├── test_crew_offline.py  crew wiring and output post-processing, no LLM
│   └── test_app_smoke.py     headless Streamlit run in demo mode (AppTest)
├── .env.example          placeholder keys (copy to .env)
├── requirements.txt
└── pytest.ini

How the pieces fit: run.py / app.py call crew.run_pipeline(), which builds the retrieval config (mcp_config.build_retrieval), the LLM (llm.build_llm), the agents and tasks, and kicks off the crew. Task 1 returns a SignalList, task 2 a ProfileList (it receives task 1 as context), task 3 an OutreachDraftList (context: tasks 1 and 2). crew.finalize() then runs pipeline.build_contact_list on the signals and profiles for a deterministic ranking and overlays the strategist's lines with pipeline.apply_outreach_drafts. Demo mode skips the crew and feeds demo_data straight into the same pipeline functions.

flowchart LR
    U[run.py / app.py] --> C[build_crew<br/>Process.sequential]
    C --> A1[Signal Hunter]
    A1 -->|"search(scope=news, from_date=now-30d)"| M[(remote MCP server)]
    A1 -->|SignalList| A2[People Enricher]
    A2 -->|"search(scope=people)"| M
    A2 -->|ProfileList| A3[Outreach Strategist<br/>no tools]
    A3 -->|OutreachDraftList| P[pipeline.finalize<br/>merge, rank, overlay lines]
    P --> R[ranked ContactList]
    D[demo_data fixtures] -.DEMO_MODE.-> P
    R --> UI[terminal list / Streamlit cards]

Run

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env               # fill in keys for live runs

# offline: fixtures only, no keys
python run.py --demo
python run.py --demo --json --limit 3
DEMO_MODE=1 streamlit run app.py

# live: LLM + MCP retrieval
python run.py --companies "Northwind Robotics, Lumen Analytics" --window-days 30
streamlit run app.py               # untick "Demo mode" in the sidebar

# tests (no network, no keys)
pytest

The Streamlit sidebar lists the three agents with the scope each one calls; the main panel updates as each stage finishes ("Trigger events found: 6", "Profiles enriched: 6", "Outreach list ready: 7") and then renders one card per contact.

Environment variables

| Variable | Purpose | |---|---| | OPENAI_API_KEY | LLM for all three agents (default model openai/gpt-4o-mini) | | OPENAI_API_BASE | optional: any OpenAI-compatible endpoint used with OPENAI_API_KEY | | OPENROUTER_API_KEY | alternative to OpenAI; default model openrouter/openai/gpt-4o-mini | | GTM_MODEL | override the model id, e.g. openai/gpt-4.1-mini or openrouter/anthropic/claude-3.5-haiku | | SELTZ_API_KEY | sent to the MCP server as Authorization: Bearer <key> | | SELTZ_MCP_URL | MCP endpoint, default https://mcp.seltz.ai/mcp | | SELTZ_MCP_TOOL | name of the search tool on the server, default search | | GTM_MCP_MODE | native or tool (see next section) | | DEMO_MODE | 1 forces fixture mode in run.py and pre-ticks the checkbox in the UI | | CREWAI_DISABLE_TELEMETRY | true keeps offline runs quiet |

OpenRouter. Set OPENROUTER_API_KEY and leave OPENAI_API_KEY empty; CrewAI routes openrouter/<vendor>/<model> ids natively. Any other OpenAI-compatible gateway works with OPENAI_API_KEY + OPENAI_API_BASE + GTM_MODEL=openai/<model id>.

MCP mechanism

CrewAI 1.15 exposes remote MCP servers directly on the agent:

from crewai import Agent
from crewai.mcp import MCPServerHTTP

Agent(..., mcps=[MCPServerHTTP(url=SELTZ_MCP_URL,
                               headers={"Authorization": f"Bearer {SELTZ_API_KEY}"})])

mcp_config.build_mcp_servers() builds exactly that config; at kickoff CrewAI lists the server's tools and wraps each one (the tool shows up to the agent as <host>_mcp_search). This is GTM_MCP_MODE=native.

The second option is mcp_config.build_mcp_tools(): MCPSearchTool, a crewai.tools.BaseTool that opens a streamable-HTTP session with the official mcp client for every call (connect, call_tool("search", ...), close). It reads the server's tool schema once and only forwards the arguments the tool declares, so scope / from_date degrade gracefully on servers that only accept query and max_results. This is GTM_MCP_MODE=tool.

Why keep both: on Python 3.10/3.11 CrewAI 1.15's native tool execution fails after a successful call (HTTPTransport.connect enters the streamable-HTTP context inside asyncio.wait_for, which on those interpreters runs in a separate task, so anyio's cancel scope is exited in a different task at disconnect and the result is lost). Discovery works everywhere. The default is therefore native on Python 3.12+ and tool below; tests/test_mcp.py exercises both against a local FastMCP server and marks the native call as an expected failure on old interpreters.

The remote server's search tool takes query and max_results; the underlying search API also supports scope (news, people, companies, wikipedia) and relative date filters such as from_date="now-30d". The task prompts ask for those and tell the agent to fall back to putting the scope words in the query if the tool rejects them.

Ranking

• recency = 1 - days_since / (window_days + 1), clamped at 0 outside the window (a signal on the last day of the window still scores above zero).
• seniority from the current title: C-level 1.0, EVP/SVP 0.85, VP 0.7, director/head 0.55, manager/lead 0.35, otherwise 0.2.
• score = recency x seniority; ties broken by newer signal, then name. A person named in several signals keeps the best-scoring one. When the people scope has no profile, the title is inferred from the headline ("... hires Jane Doe as Head of Partnerships") and the card says so.

Sample output

python run.py --demo --today 2026-09-06 (fixtures; fictional companies and people):

[1/3] trigger events found : 6
[2/3] profiles enriched    : 6
[3/3] outreach list ready  : 7

Ranked outreach list (7 contacts)

1. Priya Raman - Chief Revenue Officer, Northwind Robotics   score 0.90
   signal     : [leadership_hire] Northwind Robotics names Priya Raman Chief Revenue Officer (2026-09-03, 3d ago)
   background : Chief Revenue Officer, Northwind Robotics (2026-08-present); SVP Sales, Atlas Dynamics (2022-01-2026-07); VP Enterprise Sales, Cobalt Systems (2018-03-2021-12). Education: MBA, Wharton; BS Mechanical Engineering, Georgia Tech
   opener     : Priya, congrats on stepping into the Chief Revenue Officer role at Northwind Robotics after your time at Atlas Dynamics. Most leaders use the first 90 days to reset priorities - happy to share what peers in similar seats are changing first.
   source     : https://news.example.com/northwind-cro

2. Daniel Okafor - Co-founder and CEO, Lumen Analytics   score 0.71
   signal     : [funding] Lumen Analytics raises $42M Series B to expand its observability platform (2026-08-28, 9d ago)
   background : Co-founder and CEO, Lumen Analytics (2021-05-present); Director of Engineering, Brightpath (2016-09-2021-04). Education: MEng Computer Science, Imperial College London
   opener     : Daniel, congrats on Lumen Analytics' $42M Series B. Teams that just raised usually scale hiring and process at the same time - would it help to compare notes on what others did in the quarter after their round?
   source     : https://news.example.com/lumen-series-b

3. Mei Lin Chen - VP Sales, Lumen Analytics   score 0.50
   ...
4. Aisha Karim - Head of Partnerships, Lumen Analytics   score 0.34
   signal     : [leadership_hire] Lumen Analytics hires Aisha Karim as Head of Partnerships (2026-08-25, 12d ago)
   background : No profile found in the people scope.
   ...

In live mode the same list is printed after the crew finishes, with the strategist's openers replacing the template lines wherever it produced one.

Notes and caveats

• Live runs make one LLM call per agent step plus one MCP call per search; expect a few minutes for four companies. --verbose prints the agent traces.
• The fixtures are fictional. Nothing in demo mode touches the network.
• The strategist's JSON is validated against OutreachDraftList; if a model returns prose around the JSON, pipeline.parse_json_block extracts the object before validation. Event-type labels such as "hire" or "funding round" are normalised to the four canonical types.