How tomefy5/scout-agent works
1. What this repo is
SCOUT is a Python 3.11+ autonomous sourcing/enrichment agent. The architecture is centered on a stateful orchestration loop rather than a traditional request/response app.
2. Primary runtime entry point
main.py is the user-facing CLI entry point. It collects the target sourcing request and hands control to the agent workflow defined under src/.
3. Core orchestration layer
src/graph.py is the main coordination boundary. It defines the LangGraph workflow: planner/search/analysis steps, transitions between them, and the looping behavior that lets the agent refine its search over multiple iterations.
4. Shared agent state
src/state.py holds the evolving AgentState passed between nodes. This is the main in-memory data structure for the workflow and likely contains the request, ICP, search results, scraped content, lead candidates, and run status.
5. LLM-driven planning
src/agents/planner.py is the reasoning layer that turns a vague user prompt into a structured search strategy. This is where the agent decides what to look for, how to search, and how to refine criteria during the graph cycle.
6. Typed domain models
src/models/schemas.py defines the Pydantic schemas for the project’s key business objects, especially ICP and lead/enrichment outputs. These schemas act as the contract between LLM output, tools, and the rest of the workflow.
7. External tool integrations
src/tools/search.py wraps Tavily search, providing candidate discovery from web search.
src/tools/scraper.py wraps Firecrawl, providing page-level content extraction/verification from real company websites.
These are the two main external data acquisition boundaries.
8. End-to-end data flow
The flow is: user prompt → planner → search → scrape/verify → qualification/enrichment → structured output. The graph is intended to revisit earlier steps when results are weak or incomplete, which is why state and orchestration are central.
9. Quality and validation boundary
Pydantic schemas plus the test file test_icp.py suggest the repo emphasizes validating structured extraction, especially the ICP conversion step. This reduces dependence on free-form LLM output.
10. Storage and persistence
data/ exists but is mostly empty, indicating persistence/export is not yet a primary subsystem. The current architecture is still agent-execution-first; storage appears planned for later phases.
11. Documentation and design intent
docs/ARCHITECTURE.md and docs/SETUP.md indicate the repo is organized around explicit architecture and operational setup guidance. The README roadmap also shows that orchestration is still evolving, with production export/UI not yet implemented.
12. Key external dependencies that shape the architecture
The system depends on LangGraph for workflow control, LangChain for LLM interfacing, Gemini for reasoning/extraction, Tavily for search, Firecrawl for scraping, and Pydantic for typed I/O. These are not incidental libraries; they define the boundaries between planning, retrieval, scraping, and validation.
13. How to diagram it
The cleanest diagram would show:
- a CLI entry point,
- a central LangGraph orchestration loop,
- a shared typed state object,
- a planning node,
- external search and scraping services,
- schema validation around outputs,
- and a final qualified lead/result stream back to the user.
Main entry points: graph.py Orchestrator · state.py Agent state · planner.py Planner · schemas.py Schemas
Components 11
Runtime
User-facing entry and final result flow.
- User request · Sourcing prompt and target criteria provided by the user.
- CLI · Command-line entry point that starts the agent run.
main.py - Qualified output · Structured sourcing result returned to the user.
Core workflow
Stateful orchestration and planning loop.
- Orchestrator · Central coordination loop for planning, retrieval, analysis, and refinement.
src/graph.py - Agent state · Mutable run state passed between workflow nodes.
src/state.py - Planner · Turns the prompt into a structured search and refinement strategy.
src/agents/planner.py - Qualify lead · Evaluates retrieved evidence and produces structured lead/enrichment output.
Integrations
External acquisition services used by the agent.
Connections 16
- User request → CLI: submit · The user supplies a sourcing request to the CLI.
- CLI → Orchestrator: start run · CLI hands control to the orchestration workflow.
- Orchestrator → Agent state: read/write · Workflow nodes share and update run state.
- Orchestrator → Planner: plan · Orchestrator invokes the LLM planning step.
- Planner → Schemas: shape intent · Planner uses typed structures for ICP and search strategy output.
- Planner → Agent state: store plan · Structured plan is persisted into agent state.
- Orchestrator → Search: retrieve candidates · Workflow sends search queries to external discovery tooling.
- Search → Agent state: add results · Search results are accumulated in state for downstream steps.
- Orchestrator → Scraper: verify pages · Workflow fetches and extracts website content for candidates.
- Scraper → Agent state: add evidence · Scraped content is stored for qualification and refinement.
- Agent state → Qualify lead: provide context · Qualification step consumes request, evidence, and prior iterations.
- Qualify lead → Schemas: validate output · Lead and enrichment objects are constrained by typed schemas.
- Qualify lead → Agent state: update status · Qualification updates confidence, completeness, and next actions.
- Orchestrator → Planner: refine loop · Weak or incomplete results can send the workflow back to planning.
- Qualify lead → Qualified output: emit · Structured output is returned once the run is complete.
- ICP test → Schemas: exercise · Tests verify schema-driven ICP extraction and structured validation.