Skip to content

Building AI agents, atomically

Add FastAPI integration example

KennyVaneetveldee8e772809b3f
diff --git a/atomic-examples/fastapi-memory/README.md b/atomic-examples/fastapi-memory/README.md
new file mode 100644
index 0000000..1651724
--- /dev/null
+++ b/atomic-examples/fastapi-memory/README.md
@@ -0,0 +1,92 @@
+# FastAPI with Atomic Agents
+
+A simple example demonstrating how to integrate Atomic Agents with FastAPI for building stateful conversational APIs.
+
+## Features
+
+- Session-based conversation management
+- RESTful API endpoints for chat interactions
+- Automatic session creation and cleanup
+- Environment-based configuration
+
+## Setup
+
+1. Install dependencies:
+```bash
+poetry install
+```
+
+2. Create a `.env` file with your OpenAI API key:
+```bash
+cp .env.example .env
+# Edit .env and add your OpenAI API key
+```
+
+## Running the Example
+
+Start the FastAPI server:
+```bash
+poetry run python fastapi_memory/main.py
+```
+
+The API will be available at `http://localhost:8000`.
+
+## API Documentation
+
+Once running, visit:
+- Interactive API docs: `http://localhost:8000/docs`
+- Alternative docs: `http://localhost:8000/redoc`
+
+## Usage Examples
+
+### Send a message (creates new session automatically):
+```bash
+curl -X POST "http://localhost:8000/chat" \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Hello, what can you help me with?"}'
+```
+
+### Continue a conversation with session ID:
+```bash
+curl -X POST "http://localhost:8000/chat" \
+ -H "Content-Type: application/json" \
+ -d '{"message": "Tell me more about that", "session_id": "user123"}'
+```
+
+### List active sessions:
+```bash
+curl "http://localhost:8000/sessions"
+```
+
+### Clear a specific session:
+```bash
+curl -X DELETE "http://localhost:8000/sessions/user123"
+```
+
+## How It Works
+
+The example demonstrates several key patterns:
+
+1. **Session Management**: Each session maintains its own agent instance with independent conversation history.
+
+2. **Lazy Initialization**: Agent instances are created on-demand when a session is first accessed.
+
+3. **Automatic Cleanup**: The lifespan context manager ensures proper cleanup when the application shuts down.
+
+4. **Type Safety**: Uses Pydantic schemas for request/response validation.
+
+## Project Structure
+
+```
+fastapi-memory/
+├── pyproject.toml # Project dependencies
+├── .env.example # Environment variable template
+├── README.md # This file
+└── fastapi_memory/
+ └── main.py # FastAPI application
+```
+
+## Related Examples
+
+For more advanced usage, check out:
+- `mcp-agent/example-client/example_client/main_fastapi.py` - Advanced example with MCP protocol integration
diff --git a/atomic-examples/fastapi-memory/fastapi_memory/main.py b/atomic-examples/fastapi-memory/fastapi_memory/main.py
new file mode 100644
index 0000000..e9eae79
--- /dev/null
+++ b/atomic-examples/fastapi-memory/fastapi_memory/main.py
@@ -0,0 +1,94 @@
+import os
+from contextlib import asynccontextmanager
+from typing import Optional
+
+import instructor
+import openai
+from atomic_agents.agents.atomic_agent import AtomicAgent
+from atomic_agents.lib.base.base_io_schema import BaseIOSchema
+from atomic_agents.lib.components.agent_config import AgentConfig
+from atomic_agents.lib.components.system_prompt_generator import SystemPromptGenerator
+from dotenv import load_dotenv
+from fastapi import FastAPI, HTTPException
+from pydantic import Field
+
+load_dotenv()
+
+
+class ChatRequest(BaseIOSchema):
+ message: str = Field(..., description="User message")
+ session_id: Optional[str] = Field(None, description="Session identifier for conversation continuity")
+
+
+class ChatResponse(BaseIOSchema):
+ response: str = Field(..., description="Agent response")
+ session_id: str = Field(..., description="Session identifier")
+
+
+sessions = {}
+
+
+def get_or_create_agent(session_id: str) -> AtomicAgent:
+ if session_id not in sessions:
+ client = instructor.from_openai(openai.OpenAI(api_key=os.getenv("OPENAI_API_KEY")))
+
+ system_prompt = SystemPromptGenerator(
+ background=["You are a helpful AI assistant that maintains conversation context."],
+ steps=["Understand the user's message", "Provide a clear and helpful response"],
+ output_instructions=["Be concise and friendly", "Reference previous context when relevant"],
+ )
+
+ config = AgentConfig(
+ client=client,
+ model="gpt-4o-mini",
+ system_prompt_generator=system_prompt,
+ )
+
+ sessions[session_id] = AtomicAgent(config=config)
+
+ return sessions[session_id]
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+ yield
+ sessions.clear()
+
+
+app = FastAPI(
+ title="Atomic Agents FastAPI Example",
+ description="Simple example showing FastAPI integration with Atomic Agents",
+ lifespan=lifespan,
+)
+
+
[email protected]("/chat", response_model=ChatResponse)
+async def chat(request: ChatRequest):
+ try:
+ session_id = request.session_id or "default"
+ agent = get_or_create_agent(session_id)
+
+ result = agent.run(ChatRequest(message=request.message))
+ return ChatResponse(response=result.response, session_id=session_id)
+
+ except Exception as e:
+ raise HTTPException(status_code=500, detail=str(e))
+
+
[email protected]("/sessions/{session_id}")
+async def clear_session(session_id: str):
+ if session_id in sessions:
+ del sessions[session_id]
+ return {"message": f"Session {session_id} cleared"}
+ raise HTTPException(status_code=404, detail="Session not found")
+
+
[email protected]("/sessions")
+async def list_sessions():
+ return {"active_sessions": list(sessions.keys())}
+
+
+if __name__ == "__main__":
+ import uvicorn
+
+ uvicorn.run(app, host="0.0.0.0", port=8000)
diff --git a/atomic-examples/fastapi-memory/pyproject.toml b/atomic-examples/fastapi-memory/pyproject.toml
new file mode 100644
index 0000000..4dbac06
--- /dev/null
+++ b/atomic-examples/fastapi-memory/pyproject.toml
@@ -0,0 +1,20 @@
+[tool.poetry]
+name = "fastapi-memory"
+version = "0.1.0"
+description = "Simple FastAPI integration example with Atomic Agents"
+authors = ["BrainBlend AI"]
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.12,<4.0"
+atomic-agents = {path = "../..", develop = true}
+fastapi = "^0.115.14"
+uvicorn = "^0.32.1"
+instructor = "==1.9.2"
+openai = ">=1.0.0"
+pydantic = ">=2.10.3,<3.0.0"
+python-dotenv = ">=1.0.1,<2.0.0"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"