# harsh-sharma-2002/agentic-harnesss architecture

> Architecture diagram of the GitHub repository harsh-sharma-2002/agentic-harnesss, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harsh-sharma-2002/agentic-harnesss
- Repository: https://github.com/harsh-sharma-2002/agentic-harnesss

## Overview

Agent Harness accepts natural-language requests through a Streamlit UI or HTTP API, routes them through a shared Base Agent, and returns a unified answer. Specialized execution stays in private graphs: Text2SQL checks cached schema, discovers missing metadata, validates and executes SQL, verifies results, then produces a grounded response; Web Search performs a single search and summarizes results. Shared LLM and event modules support reasoning and runtime visibility. The README documents the major SQL stages and UI-to-API flow; unsampled internals are represented at their source directories, and no unshown implementation details are assumed.

Main entry points: [`src/agents/text2sql/sql_agent/graph.py`](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/graph.py) (SQL execution graph), [`src/agents/core/call_llm.py`](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/core/call_llm.py) (Shared LLM), [`src/agents/base/base_agent/nodes/orchestrator_node.py`](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/orchestrator_node.py) (Intent router), [`src/agents/base/base_agent/nodes/handoff_node.py`](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/handoff_node.py) (Agent handoff)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interfaces"]
  node_ui["Streamlit UI<br/>[streamlit_app.py]"]
  node_api["FastAPI service<br/>[app.py]"]
  node_query_api["Query endpoint<br/>[query.py]"]
  node_contracts["HTTP contracts<br/>[models.py]"]
end

subgraph group_orchestration["Request orchestration"]
  node_base_graph["Base graph<br/>[graph.py]"]
  node_router["Intent router"]
  node_handoff["Agent handoff<br/>[handoff_node.py]"]
  node_global_state["Global request state<br/>[state.py]"]
end

subgraph group_sql["Text2SQL agent"]
  node_sql_graph["SQL execution graph<br/>[graph.py]"]
  node_sql_state["Private SQL state<br/>[state.py]"]
  node_context_check["Schema context check<br/>[context_check.py]"]
  node_registry[("Schema registry")]
  node_discovery["Schema discovery<br/>[discovery_node.py]"]
  node_registry_update["Registry update"]
  node_sql_reasoner["SQL reasoner"]
  node_sql_validator["SQL validator<br/>[validator_node.py]"]
  node_sql_executor["SQL executor<br/>[executor_node.py]"]
  node_sql_verifier["Result verifier<br/>[verifier_node.py]"]
  node_sql_response["Grounded response<br/>[response_node.py]"]
end

subgraph group_web["Web search agent"]
  node_web_graph["Web agent graph<br/>[graph.py]"]
  node_web_search["Search operation<br/>[search_node.py]"]
  node_web_response["Search response<br/>[response_node.py]"]
end

subgraph group_shared["Shared runtime"]
  node_llm["Shared LLM<br/>[call_llm.py]"]
  node_events["Execution events<br/>[events.py]"]
end

node_user(("User"))
node_database[("Application database")]
node_web_service["Web search service"]
node_model_service["Ollama model"]

node_user -->|"submits request"| node_ui
node_ui -->|"sends HTTP"| node_api
node_user -.->|"submits query"| node_api
node_api -->|"mounts router"| node_query_api
node_query_api -->|"uses contracts"| node_contracts
node_query_api -->|"invokes graph"| node_base_graph
node_base_graph -->|"runs routing node"| node_router
node_base_graph -->|"runs handoff node"| node_handoff
node_router -->|"classifies request"| node_llm
node_router -->|"updates routing state"| node_global_state
node_handoff -->|"dispatches SQL"| node_sql_graph
node_handoff -->|"dispatches search"| node_web_graph
node_handoff -->|"translates public result"| node_global_state
node_sql_graph -->|"checks schema context"| node_context_check
node_sql_graph -->|"loads and updates"| node_registry
node_sql_graph -->|"discovers missing schema"| node_discovery
node_sql_graph -->|"persists schema knowledge"| node_registry_update
node_sql_graph -->|"reasons over request"| node_sql_reasoner
node_sql_graph -->|"validates candidate SQL"| node_sql_validator
node_sql_graph -->|"executes validated SQL"| node_sql_executor
node_sql_graph -->|"verifies results"| node_sql_verifier
node_sql_graph -->|"generates final answer"| node_sql_response
node_sql_executor -->|"runs SQL"| node_database
node_context_check -->|"assesses sufficiency"| node_llm
node_discovery -->|"plans discovery"| node_llm
node_sql_reasoner -->|"proposes SQL"| node_llm
node_sql_response -->|"composes response"| node_llm
node_web_graph -->|"runs search node"| node_web_search
node_web_graph -->|"runs response node"| node_web_response
node_web_search -->|"forms search query"| node_llm
node_web_search -->|"searches web"| node_web_service
node_web_response -->|"summarizes results"| node_llm
node_llm -->|"invokes model"| node_model_service
node_api -->|"emits lifecycle events"| node_events
node_router -->|"emits routing events"| node_events
node_sql_executor -->|"emits execution events"| node_events
node_web_search -->|"emits search events"| node_events

click node_ui "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/ui/streamlit_app.py"
click node_api "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/app.py"
click node_query_api "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/routes/query.py"
click node_contracts "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/models.py"
click node_base_graph "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/graph.py"
click node_router "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/orchestrator_node.py"
click node_handoff "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/handoff_node.py"
click node_global_state "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/state.py"
click node_sql_graph "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/graph.py"
click node_sql_state "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/state.py"
click node_context_check "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/context_check.py"
click node_registry "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/load_registry_node.py"
click node_discovery "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/discovery_node.py"
click node_registry_update "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/update_registry_node.py"
click node_sql_reasoner "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/sql_reasoner_node.py"
click node_sql_validator "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/validator_node.py"
click node_sql_executor "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/executor_node.py"
click node_sql_verifier "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/verifier_node.py"
click node_sql_response "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/response_node.py"
click node_web_graph "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/graph.py"
click node_web_search "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/nodes/search_node.py"
click node_web_response "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/nodes/response_node.py"
click node_llm "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/core/call_llm.py"
click node_events "https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/core/events.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_ui,node_api,node_query_api,node_contracts,node_user toneBlue
class node_base_graph,node_router,node_handoff,node_global_state,node_database toneAmber
class node_sql_graph,node_sql_state,node_context_check,node_registry,node_discovery,node_registry_update,node_sql_reasoner,node_sql_validator,node_sql_executor,node_sql_verifier,node_sql_response toneMint
class node_web_graph,node_web_search,node_web_response toneRose
class node_llm,node_events,node_web_service,node_model_service toneIndigo
```

## Components

### User interfaces

- [Streamlit UI](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/ui/streamlit_app.py): `ui/streamlit_app.py`
- [FastAPI service](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/app.py): `src/api/app.py`
- [Query endpoint](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/routes/query.py): `src/api/routes/query.py`
- [HTTP contracts](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/api/models.py): `src/api/models.py`

### Request orchestration

- [Base graph](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/graph.py): `src/agents/base/base_agent/graph.py`
- [Intent router](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/orchestrator_node.py): `src/agents/base/base_agent/nodes/orchestrator_node.py`
- [Agent handoff](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/nodes/handoff_node.py): `src/agents/base/base_agent/nodes/handoff_node.py`
- [Global request state](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/base/base_agent/state.py): `src/agents/base/base_agent/state.py`

### Text2SQL agent

- [SQL execution graph](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/graph.py): `src/agents/text2sql/sql_agent/graph.py`
- [Private SQL state](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/state.py): `src/agents/text2sql/sql_agent/state.py`
- [Schema context check](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/context_check.py): `src/agents/text2sql/sql_agent/nodes/context_check.py`
- [Schema registry](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/load_registry_node.py): `src/agents/text2sql/sql_agent/nodes/load_registry_node.py`
- [Schema discovery](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/discovery_node.py): `src/agents/text2sql/sql_agent/nodes/discovery_node.py`
- [Registry update](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/update_registry_node.py): `src/agents/text2sql/sql_agent/nodes/update_registry_node.py`
- [SQL reasoner](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/sql_reasoner_node.py): `src/agents/text2sql/sql_agent/nodes/sql_reasoner_node.py`
- [SQL validator](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/validator_node.py): `src/agents/text2sql/sql_agent/nodes/validator_node.py`
- [SQL executor](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/executor_node.py): `src/agents/text2sql/sql_agent/nodes/executor_node.py`
- [Result verifier](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/verifier_node.py): `src/agents/text2sql/sql_agent/nodes/verifier_node.py`
- [Grounded response](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/text2sql/sql_agent/nodes/response_node.py): `src/agents/text2sql/sql_agent/nodes/response_node.py`

### Web search agent

- [Web agent graph](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/graph.py): `src/agents/web_search/web_agent/graph.py`
- [Search operation](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/nodes/search_node.py): `src/agents/web_search/web_agent/nodes/search_node.py`
- [Search response](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/web_search/web_agent/nodes/response_node.py): `src/agents/web_search/web_agent/nodes/response_node.py`

### Shared runtime

- [Shared LLM](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/agents/core/call_llm.py): `src/agents/core/call_llm.py`
- [Execution events](https://github.com/harsh-sharma-2002/agentic-harnesss/blob/main/src/core/events.py): `src/core/events.py`

### Other components

- **User**
- **Application database**
- **Web search service**
- **Ollama model**

## Connections

- User → Streamlit UI: submits request
- Streamlit UI → FastAPI service: sends HTTP
- User → FastAPI service: submits query
- FastAPI service → Query endpoint: mounts router (evidence: `src/api/app.py`)
- Query endpoint → HTTP contracts: uses contracts (evidence: `src/api/routes/query.py`)
- Query endpoint → Base graph: invokes graph (evidence: `src/api/routes/query.py`)
- Base graph → Intent router: runs routing node (evidence: `src/agents/base/base_agent/graph.py`)
- Base graph → Agent handoff: runs handoff node (evidence: `src/agents/base/base_agent/graph.py`)
- Intent router → Shared LLM: classifies request (evidence: `src/agents/base/base_agent/nodes/orchestrator_node.py`)
- Intent router → Global request state: updates routing state (evidence: `src/agents/base/base_agent/nodes/orchestrator_node.py`)
- Agent handoff → SQL execution graph: dispatches SQL (evidence: `src/agents/base/base_agent/nodes/handoff_node.py`)
- Agent handoff → Web agent graph: dispatches search (evidence: `src/agents/base/base_agent/nodes/handoff_node.py`)
- Agent handoff → Global request state: translates public result (evidence: `src/agents/base/base_agent/nodes/handoff_node.py`)
- SQL execution graph → Schema context check: checks schema context
- SQL execution graph → Schema registry: loads and updates (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL execution graph → Schema discovery: discovers missing schema (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL execution graph → Registry update: persists schema knowledge (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL execution graph → SQL reasoner: reasons over request (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL execution graph → SQL validator: validates candidate SQL
- SQL execution graph → SQL executor: executes validated SQL (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL execution graph → Result verifier: verifies results
- SQL execution graph → Grounded response: generates final answer (evidence: `src/agents/text2sql/sql_agent/graph.py`)
- SQL executor → Application database: runs SQL (evidence: `src/agents/text2sql/sql_agent/nodes/executor_node.py`)
- Schema context check → Shared LLM: assesses sufficiency (evidence: `src/agents/text2sql/sql_agent/nodes/context_check.py`)
- Schema discovery → Shared LLM: plans discovery (evidence: `src/agents/text2sql/sql_agent/nodes/discovery_node.py`)
- SQL reasoner → Shared LLM: proposes SQL (evidence: `src/agents/text2sql/sql_agent/nodes/sql_reasoner_node.py`)
- Grounded response → Shared LLM: composes response (evidence: `src/agents/text2sql/sql_agent/nodes/response_node.py`)
- Web agent graph → Search operation: runs search node (evidence: `src/agents/web_search/web_agent/graph.py`)
- Web agent graph → Search response: runs response node (evidence: `src/agents/web_search/web_agent/graph.py`)
- Search operation → Shared LLM: forms search query (evidence: `src/agents/web_search/web_agent/nodes/search_node.py`)
- Search operation → Web search service: searches web (evidence: `src/agents/web_search/web_agent/nodes/search_node.py`)
- Search response → Shared LLM: summarizes results (evidence: `src/agents/web_search/web_agent/nodes/response_node.py`)
- Shared LLM → Ollama model: invokes model (evidence: `src/agents/core/call_llm.py`)
- FastAPI service → Execution events: emits lifecycle events (evidence: `src/api/app.py`)
- Intent router → Execution events: emits routing events (evidence: `src/agents/base/base_agent/nodes/orchestrator_node.py`)
- SQL executor → Execution events: emits execution events (evidence: `src/agents/text2sql/sql_agent/nodes/executor_node.py`)
- Search operation → Execution events: emits search events (evidence: `src/agents/web_search/web_agent/nodes/search_node.py`)
