venkataramana2005/react-agent

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