How temporal-community/temporal-ai-agent works
Major Components
a. Frontend (React UI):
• Located in the “frontend” directory.
• Built with React (using Vite) and Tailwind CSS.
• Handles user interactions, chat interfaces (e.g., ChatWindow.jsx, MessageBubble.jsx), and communicates with the backend API.
b. Backend API Server (Python):
• Found under the “api” directory (main.py) and supplemented by other scripts.
• Implemented with FastAPI/Uvicorn to expose endpoints (documented in /docs).
• Serves as an interfacing layer between the frontend and the Temporal workflow.
c. Temporal Workers & Workflows (Python):
• The scripts folder contains “run_worker.py” (and also “run_worker” style scripts) that start the Temporal worker to process workflows.
• Workflows are defined under the “workflows” directory and include “agent_goal_workflow.py” and helper modules.
• “activities” contains Python activities for tool operations.
• The Temporal configuration (e.g. connection details) is read from the environment variables and .env file.
d. Tools & Registries:
• “tools” directory includes tool modules (e.g., create_invoice.py, search_flights.py, search_trains.py) along with data and configuration files.
• “goal_registry.py” and “tool_registry.py” (under tools and workflows) map the agent’s capabilities and goals to the specific tools.
• “prompts” directory holds the prompt generation logic for the agent interactions.
e. Enterprise (.NET) Worker:
• The “enterprise” directory contains a C# (.NET) solution that implements specific activities (notably for train search/booking) as part of the “goal_match_train_invoice” scenario.
• This component interacts with external train APIs and serves as a fallback when Python activities are intentionally failing (to show Temporal’s retry behavior).
f. External Services:
• External LLM providers (OpenAI, Anthropic, Google Gemini, DeepSeek, or local LLM via Ollama) are configurable through environment variables.
• External APIs: Flight APIs (RapidAPI), Train API (started by running thirdparty/train_api.py), Stripe for invoice creation, and also a Football Data API for match search.
• Temporal Server itself (either local or cloud) as the workflow orchestration engine.
g. Supporting Scripts & Configurations:
• The “scripts” directory holds various helper scripts (for testing, managing invoices, chat history, etc.).
• Configuration files like .env.example, pyproject.toml, and the .gitignore files regulate deployment and environment setup.
Component Relationships and Data Flow
• The React frontend (user interface) communicates via HTTP with the Python API server.
• The API server triggers Temporal workflows (via the Temporal client) to start or interact with an ongoing agent conversation.
• Temporal workflows orchestrate multiple activities:
• They call Python-based tool activities (located in “activities” and “tools”).
• They may also delegate tasks to external services (e.g., contacting flight or event search APIs, or invoicing via Stripe).
• For the “goal_match_train_invoice” scenario, the workflow interacts with the .NET enterprise worker through inter-process communication (or via HTTP calls to the .NET service, depending on configuration).
• The tools and registries serve as the “brain” mapping out which actions to call next based on the current conversation context.
• External LLM providers are invoked (from within Python code) to generate responses and control the agent’s decision-making.
Architectural Patterns & Design Principles
• Separation of concerns: Distinct modules for frontend, backend API, Temporal orchestration, tools/activities, and enterprise-specific functionality.
• Modular extensibility: Goal and tool registries allow plugging in different behaviors based on the agent’s objective.
• Polyglot environment: Integration of Python and .NET components indicating a microservices-like approach.
• Resiliency: The indexing of retry/failure behavior in activities, especially the legacy worker and its resolution via the .NET worker.
• Configuration management via environment variables (with .env) ensures that credentials and settings are kept external to code.
• Every component is clearly labeled with its function.
• Incoming requests (e.g., from UI to API).
• Internal orchestration flows (between API server, Temporal workflow, and tools).
• Outgoing calls to external services.
• Incorporate notes on the technologies used for each component.