mirror/temporal-ai-agent
1
0
Fork 0
mirror of https://github.com/temporal-community/temporal-ai-agent.git synced 2026-03-15 22:18:09 +01:00
Code Issues Packages Projects Releases Wiki Activity
Files
4102f9aeca08c0f7a8c8243fc9bb092e6fd8083f
temporal-ai-agent/AGENTS.md
Dan Davison 4102f9aeca uv migration
2025-07-29 18:06:58 -04:00

7.3 KiB
Raw Blame History

Temporal AI Agent Contribution Guide

Repository Layout

  • workflows/ - Temporal workflows including the main AgentGoalWorkflow for multi-turn AI conversations
  • activities/ - Temporal activities for tool execution and LLM interactions
  • tools/ - Native AI agent tool implementations organized by category (finance, HR, ecommerce, travel, etc.)
  • goals/ - Agent goal definitions organized by category, supporting both native and MCP tools
  • shared/ - Shared configuration including MCP server definitions
  • models/ - Data types and tool definitions used throughout the system
  • prompts/ - Agent prompt generators and templates
  • api/ - FastAPI server that exposes REST endpoints to interact with workflows
  • frontend/ - React-based web UI for chatting with the AI agent
  • tests/ - Comprehensive test suite for workflows and activities using Temporal's testing framework
  • enterprise/ - .NET worker implementation for enterprise activities (train booking)
  • scripts/ - Utility scripts for running workers and testing tools

Running the Application

Quick Start with Docker

# Start all services with development hot-reload
docker compose up -d

# Quick rebuild without infrastructure
docker compose up -d --no-deps --build api worker frontend

Default URLs:

Local Development Setup

  1. Prerequisites:

    # Install uv and Temporal server (MacOS)
brew install uv
brew install temporal

temporal server start-dev

  2. Backend (Python):

    # Quick setup using Makefile
make setup              # Creates venv and installs dependencies
make run-worker         # Starts the Temporal worker
make run-api            # Starts the API server

# Or manually:
uv sync
uv run python scripts/run_worker.py    # In one terminal
uv run uvicorn api.main:app --reload   # In another terminal

  3. Frontend (React):

    make run-frontend       # Using Makefile

# Or manually:
cd frontend
npm install
npx vite

  4. Enterprise .NET Worker (optional):

    make run-enterprise     # Using Makefile

# Or manually:
cd enterprise
dotnet build
dotnet run

Environment Configuration

Copy .env.example to .env and configure:

# Required: LLM Configuration
LLM_MODEL=openai/gpt-4o
LLM_KEY=your-api-key-here
# LLM_MODEL=anthropic/claude-3-5-sonnet-20240620
# LLM_KEY=${ANTHROPIC_API_KEY}
# LLM_MODEL=gemini/gemini-2.5-flash-preview-04-17
# LLM_KEY=${GOOGLE_API_KEY}

# Optional: Agent Goals and Categories  
AGENT_GOAL=goal_choose_agent_type
GOAL_CATEGORIES=hr,travel-flights,travel-trains,fin,ecommerce,mcp-integrations,food

# Optional: Tool-specific APIs
STRIPE_API_KEY=sk_test_...       # For invoice creation
# `goal_event_flight_invoice` works without this key – it falls back to a mock invoice if unset
FOOTBALL_DATA_API_KEY=...        # For real football fixtures

Testing

The project includes comprehensive tests using Temporal's testing framework:

# Install test dependencies
uv sync

# Run all tests
uv run pytest

# Run with time-skipping for faster execution  
uv run pytest --workflow-environment=time-skipping

# Run specific test categories
uv run pytest tests/test_tool_activities.py -v     # Activity tests
uv run pytest tests/test_agent_goal_workflow.py -v # Workflow tests

# Run with coverage
uv run pytest --cov=workflows --cov=activities

Test Coverage:

  • ✅ Workflow Tests: AgentGoalWorkflow signals, queries, state management
  • ✅ Activity Tests: ToolActivities, LLM integration (mocked), environment configuration
  • ✅ Integration Tests: End-to-end workflow and activity execution

Documentation:

  • Quick Start: testing.md - Simple commands to run tests
  • Comprehensive Guide: tests/README.md - Detailed testing patterns and best practices

Linting and Code Quality

# Format code
uv run black .
uv run isort .

# Check code style and types
uv run black --check .
uv run isort --check-only .
uv run mypy --check-untyped-defs --namespace-packages .

# Run test suite
uv run pytest

Agent Customization

Adding New Goals and Tools

For Native Tools:

  1. Create tool implementation in tools/ directory
  2. Add tool function mapping in tools/__init__.py
  3. Register tool definition in tools/tool_registry.py
  4. Add tool names to static tools list in workflows/workflow_helpers.py
  5. Create or update goal definition in appropriate file in goals/ directory

For MCP Tools:

  1. Configure MCP server definition in shared/mcp_config.py (for reusable servers)
  2. Create or update goal definition in appropriate file in goals/ directory with mcp_server_definition
  3. Set required environment variables (API keys, etc.)

For Goals:

  1. Create goal file in goals/ directory (e.g., goals/my_category.py)
  2. Import and extend the goal list in goals/__init__.py

Configuring Goals

The agent supports multiple goal categories organized in goals/:

  • Financial: Money transfers, loan applications (goals/finance.py)
  • HR: PTO booking, payroll status (goals/hr.py)
  • Travel: Flight/train booking, event finding (goals/travel.py)
  • Ecommerce: Order tracking, package management (goals/ecommerce.py)
  • Food: Restaurant ordering and cart management (goals/food.py)
  • MCP Integrations: External service integrations like Stripe (goals/stripe_mcp.py)

Goals can use:

  • Native Tools: Custom implementations in /tools/ directory
  • MCP Tools: External tools via Model Context Protocol servers (configured in shared/mcp_config.py)

See adding-goals-and-tools.md for detailed customization guide.

Architecture

This system implements agentic AI—autonomous systems that pursue goals through iterative tool use and human feedback—with these key components:

  1. Goals - High-level objectives accomplished through tool sequences (organized in /goals/ by category)
  2. Native & MCP Tools - Custom implementations and external service integrations
  3. Agent Loops - LLM execution → tool calls → human input → repeat until goal completion
  4. Tool Approval - Human confirmation for sensitive operations
  5. Conversation Management - LLM-powered input validation and history summarization
  6. Durability - Temporal workflows ensure reliable execution across failures

For detailed architecture information, see architecture.md.

Commit Messages and Pull Requests

  • Use clear commit messages describing the change purpose
  • Reference specific files and line numbers when relevant (e.g., workflows/agent_goal_workflow.py:125)
  • Open PRs describing what changed and why
  • Ensure tests pass before submitting: uv run pytest --workflow-environment=time-skipping

Additional Resources