# venkataramana2005/react-agent architecture

> Architecture diagram of the GitHub repository venkataramana2005/react-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venkataramana2005/react-agent
- Repository: https://github.com/venkataramana2005/react-agent

## Overview

#### Purpose and Runtime Entry Points
This repository implements a stateful, single-agent ReAct engine: it accepts chat requests, reasons with an LLM, invokes controlled tools, pauses risky actions for human review, and streams progress/results to clients. The service entry point is FastAPI in `api/main.py`; request/event contracts are in `api/schemas.py`. Container deployment is defined by `Dockerfile` and `compose.yaml`.

#### API and Streaming Boundary
The API exposes chat streaming and approval-resume flows. It validates inbound request models, starts or resumes an agent execution, and emits Server-Sent Events for reasoning/tool/final-response lifecycle events. This is the external boundary between clients and the internal graph.
- `api/main.py`
- `api/schemas.py`

#### Stateful Agent Graph
LangGraph coordinates the execution state machine. The agent node calls the configured Groq-hosted Llama model, incorporates messages and retrieved context, and produces either a final answer or tool calls. Routing selects the next graph stage—continued reasoning, tool execution, approval, or completion—and workflow construction owns graph assembly/checkpoint behavior.
- `agent_loop/workflow.py`
- `agent_loop/agent_node.py`
- `agent_loop/routing.py`

#### Guardrail Pipeline
Input validation is performed before model execution to reject or sanitize unsafe prompts, sensitive data, and abusive traffic. Output validation is a separate terminal boundary before results are delivered to the client. These stages protect both external-model calls and client-facing responses.
- `guardrails/input_guardrails.py`
- `guardrails/output_guardrails.py`

#### Tool Execution and Isolation
The dispatcher is the agent-to-capability boundary: it resolves tool names, validates arguments, executes calls, and converts results/errors into observations for another ReAct turn. Available capabilities include web search, retrieval-augmented knowledge lookup, sandboxed code execution, and workspace-constrained file operations.
- `tools/dispatcher.py`
- `tools/web_search.py`
- `tools/code_interpreter.py`
- `tools/rag_retriever.py`
- `tools/file_ops.py`

External dependencies include Tavily for web search, a vector-store-backed retrieval/memory implementation, and potentially an isolated execution environment for Python. File operations should remain bounded by `workspace/`.

#### Memory and Persistence Flow
Short-term memory retains active session turns and intermediate tool observations for graph execution. Long-term memory persists/retrieves user-scoped semantic context via a vector-store abstraction; retrieved memories feed future agent turns, while completed interactions can be consolidated back into persistent memory. Local persistent-data placeholders are under `data/memory_store/`.
- `memory_layer/short_term.py`
- `memory_layer/long_term.py`
- `data/memory_store/.gitkeep`

#### Human Approval Control Plane
High-risk tool calls—such as code execution or writes—are intercepted before dispatch. The approval layer creates an interrupt/pending task, and the API approval route resumes or rejects the paused graph using the task/session state. This separates autonomous low-risk reads/searches from operations requiring explicit authorization.
- `hitl/approval.py`
- `agent_loop/workflow.py`
- `api/main.py`

#### Configuration and Observability
Runtime settings centralize model and provider credentials/configuration, including Groq inference, Google embedding services, Tavily, and LangSmith tracing. LangSmith is the primary observability service for model/tool traces, latency, and audit-relevant execution events.
- `settings.py`
- `requirements.txt`

Main entry points: [`agent_loop/workflow.py`](https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/workflow.py) (LangGraph workflow), [`tools/dispatcher.py`](https://github.com/venkataramana2005/react-agent/blob/main/tools/dispatcher.py) (Tool dispatcher), [`api/main.py`](https://github.com/venkataramana2005/react-agent/blob/main/api/main.py) (FastAPI streaming API), [`agent_loop/agent_node.py`](https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/agent_node.py) (ReAct agent node)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API Boundary"]
  node_api["FastAPI streaming API<br/>service entry<br/>[main.py]"]
  node_contracts["Request/event contracts<br/>schemas<br/>[schemas.py]"]
end

subgraph group_agent["Agent Execution"]
  node_workflow{{"LangGraph workflow<br/>state machine<br/>[workflow.py]"}}
  node_agent_node["ReAct agent node<br/>reasoning stage<br/>[agent_node.py]"]
  node_routing["Graph routing<br/>transition policy<br/>[routing.py]"]
end

subgraph group_tools["Controlled Capabilities"]
  node_dispatcher{{"Tool dispatcher<br/>capability boundary<br/>[dispatcher.py]"}}
  node_web_search["Web search<br/>tool<br/>[web_search.py]"]
  node_rag["Knowledge retrieval<br/>tool<br/>[rag_retriever.py]"]
  node_code["Sandboxed Python<br/>tool"]
  node_file_ops["Workspace file operations<br/>tool<br/>[file_ops.py]"]
end

subgraph group_memory["Memory &amp; Persistence"]
  node_short_memory[("Short-term session memory<br/>execution state<br/>[short_term.py]")]
  node_long_memory[("Long-term semantic memory<br/>vector memory<br/>[long_term.py]")]
  node_memory_store[("Local memory store<br/>persistent data<br/>[.gitkeep]")]
end

subgraph group_control["Safety &amp; Operations"]
  node_input_guard["Input guardrails<br/>safety filter"]
  node_approval["Human approval<br/>interrupt control<br/>[approval.py]"]
  node_output_guard["Output guardrails<br/>safety filter"]
  node_langsmith(("LangSmith tracing<br/>observability"))
end

node_client(("Chat client<br/>external client"))
node_groq_llm(("Groq Llama inference<br/>external model"))

node_client -->|"chat / approval resume"| node_api
node_api -->|"validates and serializes"| node_contracts
node_api -->|"screens request"| node_input_guard
node_input_guard -->|"approved input"| node_workflow
node_api -->|"start or resume run"| node_workflow
node_workflow -->|"reasoning turn"| node_agent_node
node_agent_node -->|"inference"| node_groq_llm
node_short_memory -->|"session context"| node_agent_node
node_long_memory -->|"retrieved context"| node_agent_node
node_agent_node -->|"answer or tool calls"| node_routing
node_routing -->|"low-risk tool call"| node_dispatcher
node_routing -->|"high-risk tool call"| node_approval
node_approval -->|"approved or rejected resume"| node_workflow
node_dispatcher -->|"search"| node_web_search
node_dispatcher -->|"retrieve"| node_rag
node_dispatcher -->|"execute"| node_code
node_dispatcher -->|"read/write"| node_file_ops
node_dispatcher -->|"observation"| node_workflow
node_workflow -->|"checkpoints and observations"| node_short_memory
node_long_memory -->|"persists vectors"| node_memory_store
node_workflow -.->|"consolidates completed interaction"| node_long_memory
node_routing -->|"final response"| node_output_guard
node_output_guard -->|"safe SSE result"| node_api
node_api -->|"SSE lifecycle events"| node_client
node_workflow -.->|"execution traces"| node_langsmith
node_dispatcher -.->|"tool traces"| node_langsmith

click node_api "https://github.com/venkataramana2005/react-agent/blob/main/api/main.py"
click node_contracts "https://github.com/venkataramana2005/react-agent/blob/main/api/schemas.py"
click node_input_guard "https://github.com/venkataramana2005/react-agent/blob/main/guardrails/input_guardrails.py"
click node_workflow "https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/workflow.py"
click node_agent_node "https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/agent_node.py"
click node_routing "https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/routing.py"
click node_approval "https://github.com/venkataramana2005/react-agent/blob/main/hitl/approval.py"
click node_dispatcher "https://github.com/venkataramana2005/react-agent/blob/main/tools/dispatcher.py"
click node_web_search "https://github.com/venkataramana2005/react-agent/blob/main/tools/web_search.py"
click node_rag "https://github.com/venkataramana2005/react-agent/blob/main/tools/rag_retriever.py"
click node_code "https://github.com/venkataramana2005/react-agent/blob/main/tools/code_interpreter.py"
click node_file_ops "https://github.com/venkataramana2005/react-agent/blob/main/tools/file_ops.py"
click node_short_memory "https://github.com/venkataramana2005/react-agent/blob/main/memory_layer/short_term.py"
click node_long_memory "https://github.com/venkataramana2005/react-agent/blob/main/memory_layer/long_term.py"
click node_memory_store "https://github.com/venkataramana2005/react-agent/blob/main/data/memory_store/.gitkeep"
click node_output_guard "https://github.com/venkataramana2005/react-agent/blob/main/guardrails/output_guardrails.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_api,node_contracts toneBlue
class node_workflow,node_agent_node,node_routing toneAmber
class node_dispatcher,node_web_search,node_rag,node_code,node_file_ops toneMint
class node_short_memory,node_long_memory,node_memory_store toneRose
class node_input_guard,node_approval,node_output_guard,node_langsmith toneIndigo
class node_client,node_groq_llm toneNeutral
```

## Components

### API Boundary

- [FastAPI streaming API](https://github.com/venkataramana2005/react-agent/blob/main/api/main.py): service entry · Starts, resumes, and streams agent runs as SSE. · `api/main.py`
- [Request/event contracts](https://github.com/venkataramana2005/react-agent/blob/main/api/schemas.py): schemas · `api/schemas.py`

### Agent Execution

- [LangGraph workflow](https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/workflow.py): state machine · Assembles execution, routing, interrupts, and checkpoints. · `agent_loop/workflow.py`
- [ReAct agent node](https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/agent_node.py): reasoning stage · Calls the configured Groq-hosted Llama model. · `agent_loop/agent_node.py`
- [Graph routing](https://github.com/venkataramana2005/react-agent/blob/main/agent_loop/routing.py): transition policy · `agent_loop/routing.py`

### Controlled Capabilities

- [Tool dispatcher](https://github.com/venkataramana2005/react-agent/blob/main/tools/dispatcher.py): capability boundary · Validates, executes, and returns tool observations. · `tools/dispatcher.py`
- [Web search](https://github.com/venkataramana2005/react-agent/blob/main/tools/web_search.py): tool · `tools/web_search.py`
- [Knowledge retrieval](https://github.com/venkataramana2005/react-agent/blob/main/tools/rag_retriever.py): tool · `tools/rag_retriever.py`
- [Sandboxed Python](https://github.com/venkataramana2005/react-agent/blob/main/tools/code_interpreter.py): tool · `tools/code_interpreter.py`
- [Workspace file operations](https://github.com/venkataramana2005/react-agent/blob/main/tools/file_ops.py): tool · Operations remain bounded by workspace/. · `tools/file_ops.py`

### Memory & Persistence

- [Short-term session memory](https://github.com/venkataramana2005/react-agent/blob/main/memory_layer/short_term.py): execution state · Retains turns and tool observations during a run. · `memory_layer/short_term.py`
- [Long-term semantic memory](https://github.com/venkataramana2005/react-agent/blob/main/memory_layer/long_term.py): vector memory · Retrieves and consolidates user-scoped context. · `memory_layer/long_term.py`
- [Local memory store](https://github.com/venkataramana2005/react-agent/blob/main/data/memory_store/.gitkeep): persistent data · `data/memory_store/.gitkeep`

### Safety & Operations

- [Input guardrails](https://github.com/venkataramana2005/react-agent/blob/main/guardrails/input_guardrails.py): safety filter · `guardrails/input_guardrails.py`
- [Human approval](https://github.com/venkataramana2005/react-agent/blob/main/hitl/approval.py): interrupt control · Pauses high-risk tool calls pending a decision. · `hitl/approval.py`
- [Output guardrails](https://github.com/venkataramana2005/react-agent/blob/main/guardrails/output_guardrails.py): safety filter · `guardrails/output_guardrails.py`
- **LangSmith tracing**: observability · Captures model, tool, latency, and audit traces.

### Other components

- **Chat client**: external client
- **Groq Llama inference**: external model

## Connections

- Chat client → FastAPI streaming API: chat / approval resume
- FastAPI streaming API → Request/event contracts: validates and serializes
- FastAPI streaming API → Input guardrails: screens request
- Input guardrails → LangGraph workflow: approved input
- FastAPI streaming API → LangGraph workflow: start or resume run
- LangGraph workflow → ReAct agent node: reasoning turn
- ReAct agent node → Groq Llama inference: inference
- Short-term session memory → ReAct agent node: session context
- Long-term semantic memory → ReAct agent node: retrieved context
- ReAct agent node → Graph routing: answer or tool calls
- Graph routing → Tool dispatcher: low-risk tool call
- Graph routing → Human approval: high-risk tool call
- Human approval → LangGraph workflow: approved or rejected resume
- Tool dispatcher → Web search: search
- Tool dispatcher → Knowledge retrieval: retrieve
- Tool dispatcher → Sandboxed Python: execute
- Tool dispatcher → Workspace file operations: read/write
- Tool dispatcher → LangGraph workflow: observation
- LangGraph workflow → Short-term session memory: checkpoints and observations
- Long-term semantic memory → Local memory store: persists vectors
- LangGraph workflow → Long-term semantic memory: consolidates completed interaction
- Graph routing → Output guardrails: final response
- Output guardrails → FastAPI streaming API: safe SSE result
- FastAPI streaming API → Chat client: SSE lifecycle events
- LangGraph workflow → LangSmith tracing: execution traces
- Tool dispatcher → LangSmith tracing: tool traces