How steveandroulakis/temporal-ai-agent works
Project type and purpose
• This is a full-stack “AI Agent” demo application built on Temporal.
• Purpose: Drive a multi-turn conversation with an LLM inside a durable workflow; support native and MCP (Model Context Protocol) tool calls; expose a web UI and an HTTP API; ship example enterprise (.NET) worker.
File structure
• Top-level components:
• frontend/ – React + Vite + Tailwind UI
• api/ – FastAPI (or similar) HTTP server entrypoint
• workflows/ & activities/ – Python Temporal workflows and Activities that implement the agent loop
• tools/ – Native tool implementations (python scripts) organized by domain + registration logic
• shared/ – Config, MCP client manager, common code
• goals/ – Goal definitions driving which tools and prompts to use
• enterprise/ – C# sample worker & activities for “Train” domain
• docker-compose.yml, Dockerfile, Makefile, .devcontainer – dev and deployment tooling
• Supporting artifacts:
• docs/ – architecture decisions, setup, testing guidelines
• tests/ – pytest-based workflow & activity tests
• .github/workflows/ci.yml – CI pipeline
README
• Describes the core architecture: Temporal workflows for durability, Activities for tool calls, LLM orchestration, multi-agent vs single-agent modes.
• Highlights two kinds of tools: native (in tools/) and MCP (configured via shared/mcp_config.py).
• The UI (frontend/) communicates with api/main.py which folds into Temporal workflows.
Main components
a. Frontend (React app)
• Components: ChatWindow, message bubble, NavBar
• Communicates via REST/WebSocket to API
b. API Server (api/main.py)
• Exposes HTTP endpoints: start chat, send user message, query chat state
• Translates requests into Temporal Workflow signals/queries
c. Temporal Server
• Orchestrates Workflow executions, stores history
• Persistence backend (PostgreSQL or Cassandra – optional)
d. Workflow Worker (Python process)
• Hosts Workflow definitions (workflows/agent_goal_workflow.py)
• Hosts Activity stubs for orchestration loops
e. Activity Worker (Python process)
• Activities in activities/tool_activities.py call into:
• Native tools (tools/… modules)
• MCP tools via shared/mcp_client_manager.py + shared/mcp_config.py
• Prompt generators (prompts/agent_prompt_generators.py)
f. Enterprise Worker (C# process)
• Example .NET Temporal Worker for TrainActivities
g. External Services
• LLM Providers (OpenAI, Anthropic, etc. via LiteLLM)
• MCP servers (Stripe, custom APIs)
h. Persistence & Observability
• Temporal’s own database
• (Optional) Check-claim pattern storage for large payloads
Relationships & interactions
1. User → Frontend → API
2. API → Temporal Workflow (Start/Signal)
3. Workflow → Activity Worker (LLM call, tool invocation)
4. Activity Worker → External LLM / MCP service
5. Activity Worker → returns output → Workflow
6. Workflow aggregates history, loops until goal complete
7. API queries Workflow for state → Frontend updates UI
8. Enterprise Worker runs in parallel for domain-specific workflows
Architectural patterns & principles
• Orchestrator-Worker pattern (Temporal)
• Separation of concerns:
• Workflow code handles control flow & state
• Activities handle side-effects (tool and LLM calls)
• API layer handles user communication
• Frontend handles presentation
• Plugin-style tool registry (tools/tool_registry.py)
• Domain-driven goal modules under goals/
• Durable, event-sourced workflow history
• Extensibility: add new goals in /goals/, new tools in /tools/