Agent Framework

A production-grade agentic workflow engine implementing ReAct agents, multi-agent orchestration, three-tier memory, and a dynamic tool registry.

Built to the same standards used in enterprise AI systems — agents reason transparently, use tools reliably, remember context across runs, and coordinate in multi-agent pipelines.

---

Architecture

┌─────────────────────────────────────────────────────────┐
│                    FastAPI Layer                          │
│         /agent/run   /agent/orchestrate   /tools         │
└───────────────────────────┬─────────────────────────────┘
                             │
          ┌──────────────────┼──────────────────┐
          ▼                  ▼                  ▼
┌──────────────────┐ ┌──────────────┐ ┌────────────────┐
│   Agent Layer    │ │ Orchestrator │ │  Tool Registry │
│                  │ │              │ │                │
│ ReActAgent       │ │ Sequential   │ │ web_search     │
│ PlannerAgent     │ │ Parallel     │ │ execute_python │
│                  │ │ Hierarchical │ │ calculator     │
│ ReAct Loop:      │ │ Router       │ │ summarize      │
│  Thought →       │ │              │ │ memory_read    │
│  Action →        │ └──────────────┘ │ memory_write   │
│  Observation →   │                  └────────────────┘
│  Repeat          │
└──────────────────┘
          │
          ▼
┌──────────────────────────────────┐
│         Memory System            │
│                                  │
│  Short-term:  conversation buffer│
│  Long-term:   persistent K-V     │
│  Episodic:    compressed history │
└──────────────────────────────────┘

---

Features

Agent Types

• ReActAgent — Reasoning + Acting loop with structured JSON responses. Best for most tasks.
• PlannerAgent — Creates a plan first, then executes step by step. Best for complex multi-step tasks.

Multi-Agent Orchestration

• Sequential — Agent A's output feeds Agent B. Use for research → analyze → format pipelines.
• Parallel — All agents run simultaneously with ThreadPoolExecutor. Use for independent sub-tasks.
• Hierarchical — Supervisor delegates to workers, then synthesizes results.
• Router — Routes tasks to the best-fit agent based on task content.

Three-Tier Memory

• Short-term — Rolling message buffer with configurable size
• Long-term — Persistent semantic memory with keyword retrieval
• Episodic — Compressed summaries of past task executions for learning

Tool Registry

• Dynamic registration — add tools at runtime without code changes
• Built-in: web_search, execute_python, calculator, summarize, memory_read, memory_write
• Easy to extend — implement BaseTool and register

---

Quickstart

git clone https://github.com/yourusername/agent-framework.git
cd agent-framework
pip install -r requirements.txt

cp .env.example .env
# Add your OPENAI_API_KEY

uvicorn api.main:app --reload

---

API Usage

Run a single agent

curl -X POST http://localhost:8000/agent/run \
  -H "Content-Type: application/json" \
  -d '{
    "task": "What is 15% of 847 and what is today'\''s date?",
    "agent_type": "react"
  }'

Response:

{
  "task": "What is 15% of 847 and what is today's date?",
  "answer": "15% of 847 is 127.05. Today is April 29, 2026.",
  "status": "completed",
  "steps": [
    {
      "step_number": 1,
      "thought": "I'll calculate 15% of 847 first",
      "action": "calculator",
      "action_input": "847 * 0.15",
      "observation": "127.05",
      "duration_ms": 12.3
    },
    {
      "step_number": 2,
      "thought": "Now I have both answers",
      "action": "final_answer",
      "action_input": "15% of 847 is 127.05. Today is April 29, 2026.",
      "observation": null,
      "duration_ms": 843.1
    }
  ],
  "step_count": 2,
  "total_duration_ms": 1203.4,
  "succeeded": true
}

Run multi-agent orchestration

curl -X POST http://localhost:8000/agent/orchestrate \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Research the latest developments in LLM inference optimization and summarize key findings",
    "pattern": "sequential"
  }'

List available tools

curl http://localhost:8000/tools

Check memory stats

curl http://localhost:8000/memory/stats

---

Running Tests

pytest tests/ -v

---

Project Structure

agent-framework/
├── agents/
│   ├── base_agent.py        # Abstract ReAct loop, AgentResult, AgentStep
│   └── react_agent.py       # ReActAgent + PlannerAgent implementations
├── tools/
│   └── registry.py          # ToolRegistry + all built-in tools
├── memory/
│   └── memory.py            # ShortTermMemory, LongTermMemory, EpisodicMemory
├── orchestration/
│   └── orchestrator.py      # Sequential, Parallel, Hierarchical, Router patterns
├── api/
│   └── main.py              # FastAPI endpoints
├── tests/
│   └── test_agent_framework.py  # 25+ tests
├── runtime.txt
├── Dockerfile
└── requirements.txt

---

Design Decisions

Why ReAct over simple function calling? ReAct forces the agent to articulate its reasoning before each action. This transparency makes debugging much easier and reduces errors — you can see exactly why an agent made each decision.

Why three-tier memory? Different memories serve different purposes. Short-term handles conversation context, long-term persists knowledge between sessions, and episodic memory lets agents learn from past successes and failures. Production systems like MemGPT use this same architecture.

Why thread-based parallel orchestration instead of async? Agent steps are I/O-bound (LLM calls) but each agent maintains state internally. ThreadPoolExecutor gives true parallelism without the complexity of coordinating async agent loops.

---

License

MIT