Temporal AI Agent

https://github.com/steveandroulakis/temporal-ai-agent
Admin
A Temporal-based AI agent that conducts multi-turn conversations to achieve goals by executing...
Tokens:9,731
Snippets:87
Trust Score:8.5
License:MIT
Update:1 year ago
Show doc for...
Tokens:
Raw
### Quick Start with Makefile Commands for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This section provides a comprehensive list of Makefile commands to simplify the setup, installation, and running of various components of the Temporal AI Agent. It includes commands for environment setup, starting workers and API servers, and development utilities.

```bash
# Initial setup
make setup              # Creates virtual environment and installs dependencies
make setup-venv         # Creates virtual environment only
make install            # Installs all dependencies

# Running the application
make run-worker         # Starts the Temporal worker
make run-api            # Starts the API server
make run-frontend       # Starts the frontend development server

# Additional services
make run-train-api      # Starts the train API server
make run-legacy-worker  # Starts the legacy worker
make run-enterprise     # Builds and runs the enterprise .NET worker

# Development environment setup
make setup-temporal-mac # Installs and starts Temporal server on Mac

# View all available commands
make help
```

--------------------------------

### Start React UI Locally with Vite (JavaScript/Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

These commands navigate to the frontend directory, install Node.js dependencies using npm, and start the React UI development server using Vite. The UI provides the user interface for the application, accessible via a local URL.

```bash
cd frontend
npm install
npx vite
```

--------------------------------

### Install and Start Temporal Dev Server on Mac (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet provides commands to install and start a local Temporal development server on macOS using Homebrew. It's suitable for quick local development without Docker, providing a lightweight Temporal instance.

```bash
brew install temporal
temporal server start-dev
```

--------------------------------

### Install Prerequisites for Local Temporal AI Agent Development

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Install necessary tools like Poetry for Python dependency management and start the Temporal development server for local AI agent development on macOS.

```bash
# Install Poetry for Python dependency management
curl -sSL https://install.python-poetry.org | python3 -

# Start Temporal server (Mac)
brew install temporal
temporal server start-dev
```

--------------------------------

### Run Python Backend for Train Search API

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

Instructions to start the Python-based train search API server, which is essential for the "goal_match_train_invoice" agent to search and book train tickets. An example URL is provided to demonstrate API usage.

```Bash
poetry run python thirdparty/train_api.py

# example url
# http://localhost:8080/api/search?from=london&to=liverpool&outbound_time=2025-04-18T09:00:00&inbound_time=2025-04-20T09:00:00
```

--------------------------------

### Automated Setup Script for AI Agent Development Environments

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

A comprehensive script to set up the development environment, including Poetry installation, frontend dependencies, and pre-downloading the Temporal test server binary for faster test execution.

```bash
export SHELL=/bin/bash
curl -sSL https://install.python-poetry.org | python3 -
export PATH="$HOME/.local/bin:$PATH"
ls
poetry install --with dev
cd frontend
npm install
cd ..

# Pre-download the temporal test server binary
poetry run python3 -c "
import asyncio
import sys
from temporalio.testing import WorkflowEnvironment

async def predownload():
    try:
        print('Starting test server download...')
        env = await WorkflowEnvironment.start_time_skipping()
        print('Test server downloaded and started successfully')
        await env.shutdown()
        print('Test server shut down successfully')
    except Exception as e:
        print(f'Error during download: {e}')
        sys.exit(1)

asyncio.run(predownload())
"
```

--------------------------------

### Start API Server Locally with Uvicorn (Python/Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This command starts the API server locally using Uvicorn with hot-reloading enabled. The API provides endpoints for interacting with the application, and its documentation can be accessed at the /docs endpoint.

```bash
poetry run uvicorn api.main:app --reload
```

--------------------------------

### YAML: GitHub Actions CI/CD Workflow for Tests

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Example GitHub Actions workflow configuration for running tests on push and pull requests, including Python setup, dependency installation, and pytest execution.

```yaml
name: Test
on: [push, pull_request]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.10'
      - run: pip install poetry
      - run: poetry install --with dev
      - run: poetry run pytest --workflow-environment=time-skipping
```

--------------------------------

### Configure .env File for Temporal AI Agent Settings

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet shows how to initialize the application's configuration by copying the example environment file. It also highlights setting `SHOW_CONFIRM` to control UI confirmations, which can be useful for debugging or to reduce conversation clutter.

```bash
cp .env.example .env
```

--------------------------------

### Run Temporal AI Agent Components (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

These commands initiate the various components of the Temporal AI Agent, including the worker, the API server, and the frontend development server. Ensure all dependencies are installed before execution.

```bash
poetry run python scripts/run_worker.py
poetry run uvicorn api.main:app --reload
cd frontend
npm install
npx vite
```

--------------------------------

### Python: Testing Temporal Workflow Signals and Queries

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Example demonstrating how to start a Temporal workflow, send signals to it, query its state, and properly end it in a test.

```python
async def test_workflow_signal(self, client, sample_combined_input):
    # Start workflow
    handle = await client.start_workflow(
        AgentGoalWorkflow.run,
        sample_combined_input,
        id=str(uuid.uuid4()),
        task_queue=task_queue_name,
    )
    
    # Send signal
    await handle.signal(AgentGoalWorkflow.user_prompt, "test message")
    
    # Query state
    conversation = await handle.query(AgentGoalWorkflow.get_conversation_history)
    
    # End workflow
    await handle.signal(AgentGoalWorkflow.end_chat)
    result = await handle.result()
```

--------------------------------

### Set Up Python Backend Locally with Poetry (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

These commands set up the Python backend environment locally using Poetry for dependency management. It involves creating a virtual environment, activating it, and installing all project dependencies for local execution.

```bash
python -m venv venv
source venv/bin/activate
poetry install
```

--------------------------------

### Run Temporal AI Agent with Docker Compose

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Quickly start all Temporal AI Agent services, including hot-reload, using Docker Compose. Provides commands for initial setup and quick rebuilds without infrastructure.

```bash
# 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
```

--------------------------------

### Start Temporal AI Agent in Docker Development Mode (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This command starts the Temporal AI Agent services in development mode using Docker Compose, enabling hot-reloading and mounted code. It includes a quick rebuild option for specific services without re-provisioning the entire infrastructure.

```bash
docker compose up -d
# quick rebuild without infra:
docker compose up -d --no-deps --build api train-api worker frontend
```

--------------------------------

### Install Development Dependencies for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Installs project dependencies, including development tools, using Poetry. This step is crucial before running any tests or development tasks.

```bash
poetry install --with dev
```

--------------------------------

### Start Temporal AI Agent in Docker Production Mode (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This command starts the Temporal AI Agent services in production mode using Docker Compose, explicitly ignoring development overrides. It's suitable for deploying the application without hot-reloading features, ensuring a stable environment.

```bash
docker compose -f docker-compose.yml up -d
```

--------------------------------

### Start Temporal Worker Locally (Python/Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This command starts the Temporal worker process for the Python backend. The worker is responsible for executing Temporal workflows and activities, connecting to a local or remote Temporal server.

```bash
poetry run python scripts/run_worker.py
```

--------------------------------

### Configure Agent Goal: Flight and Event Invoice Generation

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This section outlines the setup for the "goal_event_flight_invoice" agent, which handles flight searches and invoice creation. It explains how to use mock functions by default or integrate with real APIs like RapidAPI for flights and Stripe for invoices, detailing required environment variables and their impact on behavior.

```APIDOC
Agent Goal: goal_event_flight_invoice

Description: Configures the agent to handle event and flight searches, and generate invoices.

Dependencies:
- RAPIDAPI_KEY (Optional, Environment Variable):
  - Type: String
  - Description: API key for live flight data from RapidAPI (sky-scrapper). If not set, mock flight data is generated.
  - Notes: May require increasing TOOL_ACTIVITY_START_TO_CLOSE_TIMEOUT for slow responses. Free signup at https://rapidapi.com/apiheya/api/sky-scrapper.
- STRIPE_API_KEY (Required, Environment Variable):
  - Type: String
  - Description: API key for Stripe to create real invoices. If not set, a dummy invoice is created (default for this goal).
  - Notes: Free signup at https://stripe.com/. Requires read-write permissions on Credit Notes, Invoices, Customers, Customer Sessions.

Tools:
- Mock Event Search Function: Zero configuration.
- Flight Search Tool:
  - Default: Generates realistic flight data with smart pricing.
  - Optional: Uses RapidAPI with RAPIDAPI_KEY.
- Create Invoice Tool:
  - Default: Creates a dummy invoice if STRIPE_API_KEY is missing.
  - Optional: Uses Stripe API with STRIPE_API_KEY.
```

--------------------------------

### Python: Using Temporal Test Fixtures

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Demonstrates how to leverage provided Temporal test client and data fixtures like `sample_agent_goal` and `sample_conversation_history` for consistent test setup.

```python
async def test_my_workflow(self, client, sample_agent_goal, sample_conversation_history):
    # client: Temporal test client
    # sample_agent_goal: Pre-configured AgentGoal
    # sample_conversation_history: Sample conversation data
    pass
```

--------------------------------

### Configure OpenAI LLM for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This example shows how to configure the Temporal AI Agent to use OpenAI's language models, specifically GPT-4o, by setting the `LLM_MODEL` and `LLM_KEY` environment variables. It is recommended for optimal performance.

```bash
LLM_MODEL=openai/gpt-4o
LLM_KEY=your-api-key-here
```

--------------------------------

### Python: Test Naming Convention Example

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Illustrates the recommended naming convention for test classes and methods in Python, including test file and class naming.

```python
class TestAgentGoalWorkflow:
    async def test_user_prompt_signal_valid_input(self, client, sample_combined_input):
        # Test implementation
        pass
```

--------------------------------

### Temporal AI Agent Customization File Structure (Python)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This section outlines the key files and directories for customizing the Temporal AI Agent's behavior. It details where tool definitions, goal descriptions, and tool implementations are located for extending agent capabilities.

```Python
File: tool_registry.py
Description: Maps tool names to tool definitions, enabling AI understanding.

Directory: goals/
Description: Contains descriptions of agent goals and their required tools.

Directory: /tools
Description: Holds the actual implementations and definitions of agent tools.
```

--------------------------------

### Configure Agent Goal: Premier League Match and Train Invoice

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This documentation describes the configuration for the "goal_match_train_invoice" agent, designed for finding Premier League matches, booking train tickets, and generating invoices. It highlights the demo's built-in failure mechanism and specifies dependencies on Football Data API, a train API, and Stripe, along with their setup requirements.

```APIDOC
Agent Goal: goal_match_train_invoice

Description: Configures the agent for Premier League match attendance with train booking and invoice generation. This goal was part of Temporal's Replay 2025 conference keynote demo and includes built-in failure to demonstrate agent resilience.

Dependencies:
- FOOTBALL_DATA_API_KEY (Optional, Environment Variable):
  - Type: String
  - Description: API key for real Premier League fixtures from Football Data. If omitted, mock fixtures are returned.
  - Notes: Free account signup at https://www.football-data.org.
- Train API Server (Required):
  - Description: External API for searching and booking trains. Requires running `python thirdparty/train_api.py`.
  - Notes: The train activity is 'enterprise' (C#) and requires a .NET runtime.
- STRIPE_API_KEY (Required, Environment Variable):
  - Type: String
  - Description: API key for Stripe to create real invoices. If missing, this goal will NOT generate a real invoice (unlike goal_event_flight_invoice).
  - Notes: Free signup at https://stripe.com/ (test mode only). To use a mock invoice, replace `create_invoice` with `create_invoice_example` in `tools/create_invoice.py`.
```

--------------------------------

### Configure Temporal AI Agent for Food Ordering Goal (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This configuration sets the AI agent's primary goal to food ordering, integrating with Stripe for payment processing via the Model Context Protocol (MCP). It requires a `STRIPE_API_KEY` and specific products in Stripe with `use_case=food_ordering_demo` metadata.

```bash
AGENT_GOAL=goal_food_ordering
```

--------------------------------

### Set Up and Run Temporal AI Agent React Frontend

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Initialize and launch the React-based web UI for the Temporal AI Agent, enabling interaction with the AI agent through a chat interface.

```bash
make run-frontend       # Using Makefile
```

```javascript
# Or manually:
cd frontend
npm install
npx vite
```

--------------------------------

### Configure Temporal AI Agent for Loan Application Goal (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This configuration enables the AI agent to handle loan application scenarios. Similar to money movement, it can initiate a real Temporal workflow if `FIN_START_REAL_WORKFLOW` is `TRUE` and a separate worker is running. By default, it simulates the workflow.

```bash
FIN_START_REAL_WORKFLOW=FALSE #set this to true to start a real workflow
```

--------------------------------

### Build and Run .NET Enterprise Train Worker

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

Instructions for building and running the C# (.NET) enterprise worker, which contains activities for calling the train APIs. This worker is crucial for resolving failures introduced by the Python legacy worker and requires the Python train API server to be running.

```Bash
cd enterprise
dotnet build # ensure you brew install dotnet@8 first!
dotnet run
```

--------------------------------

### Install Python Dependencies for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command installs all necessary project dependencies, including development tools, using Poetry. It ensures the environment is set up correctly for running tests and development tasks.

```bash
poetry install --with dev
```

--------------------------------

### Set Up and Run Temporal AI Agent Python Backend

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Configure and run the Python backend for the Temporal AI Agent, including the Temporal worker and FastAPI server, using Makefile commands or manual Poetry execution.

```bash
# 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
```

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

--------------------------------

### Bash: Generating Test Coverage Reports

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Commands to install `pytest-cov` and generate HTML test coverage reports for specified modules, aiding in identifying untested code.

```bash
poetry add --group dev pytest-cov
poetry run pytest --cov=workflows --cov=activities --cov-report=html
```

--------------------------------

### Enable Multi-Agent Mode and Categories for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This configuration enables the experimental multi-agent mode, allowing users to select different agent types during a conversation. It also shows how to restrict available agent categories using `GOAL_CATEGORIES` for a more focused multi-agent experience.

```bash
AGENT_GOAL=goal_choose_agent_type
GOAL_CATEGORIES=hr,travel-flights,travel-trains,fin
```

--------------------------------

### Document Optional Native Tools in Python Goal Description

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

This example demonstrates how to indicate an optional tool within the LLM-facing goal description. This guides the agent to potentially skip the tool if not needed, improving flexibility.

```Python
description="Help the user gather args for these tools in order: "
    "1. CurrentPTO: Tell the user how much PTO they currently have "
    "2. FuturePTO: Tell the user how much PTO they will have as of the prospective date "
    "3. CalendarConflict: Tell the user what conflicts if any exist around the prospective date on a list of calendars. This step is optional and can be skipped by moving to the next tool. "
    "4. BookPTO: Book PTO "
```

--------------------------------

### Configure MCP Tools in Temporal Agent Goals (Python)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This Python snippet demonstrates how to configure Model Context Protocol (MCP) tools within Temporal Agent goal definitions. It shows how to use predefined MCP server definitions, specifying which tools to include for specific functionalities like Stripe integration.

```python
from shared.mcp_config import get_stripe_mcp_server_definition

mcp_server_definition=get_stripe_mcp_server_definition(
    included_tools=["list_products", "create_customer", "create_invoice"]
)
```

--------------------------------

### Configure Temporal AI Agent for Money Movement Goal (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This configuration enables the AI agent to handle money movement scenarios. It can initiate a real Temporal workflow if the `FIN_START_REAL_WORKFLOW` environment variable is set to `TRUE` and a separate Java worker is running and connected. By default, it simulates the workflow.

```bash
FIN_START_REAL_WORKFLOW=FALSE #set this to true to start a real workflow
```

--------------------------------

### Set MCP Environment Variables for API Keys (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet shows how to set environment variables, specifically API keys, required for MCP servers in your .env file. It's crucial for authenticating with external services like Stripe, ensuring secure access to their APIs.

```bash
# For Stripe MCP Server
STRIPE_API_KEY=sk_test_your_stripe_key_here
```

--------------------------------

### Configure Ollama LLM with Custom URL for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This configuration demonstrates how to integrate Ollama models with the Temporal AI Agent, particularly when using a custom base URL for the Ollama server. It requires setting `LLM_MODEL` and `LLM_BASE_URL` to point to your local Ollama instance.

```bash
LLM_MODEL=ollama/mistral
LLM_BASE_URL=http://localhost:11434
```

--------------------------------

### AGENT_GOAL Environment Variable API Reference (APIDOC)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

The `AGENT_GOAL` environment variable configures the primary objective for the Temporal AI Agent. Setting this variable activates specific scenarios, enabling the agent to interact with various external systems and mock data.

```APIDOC
Environment Variable: AGENT_GOAL
Type: string
Description: Defines the primary goal or scenario for the AI agent.

Possible Values:
- `goal_fin_move_money`: Handles money movement scenarios. Can initiate real Temporal workflows if configured.
- `goal_fin_loan_application`: Handles loan application scenarios. Can initiate real Temporal workflows if configured.
- `goal_hr_pto`: Manages HR/PTO related tasks, requiring `employee_pto_data.json`.
- `goal_ecommerce`: Manages e-commerce related tasks, requiring `customer_order_data.json`.
- `goal_food_ordering`: Demonstrates food ordering with Stripe payment processing via MCP. Requires `STRIPE_API_KEY` and specific Stripe product metadata.
```

--------------------------------

### Configure Environment Variables for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Set up essential environment variables for the Temporal AI Agent, including LLM API keys and optional agent goal categories and tool-specific API keys.

```bash
# 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
```

--------------------------------

### Configure Temporal AI Agent Tests for Continuous Integration

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command provides the recommended setup for running tests in a CI environment. It combines time-skipping for speed with a short traceback format for cleaner CI logs.

```bash
poetry run pytest --workflow-environment=time-skipping --tb=short
```

--------------------------------

### Configure Anthropic LLM for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet illustrates how to set up the Temporal AI Agent to utilize Anthropic's language models, such as Claude 3.5 Sonnet. It requires setting both the `LLM_MODEL` and `LLM_KEY` environment variables.

```bash
LLM_MODEL=anthropic/claude-3-sonnet
LLM_KEY=your-api-key-here
```

--------------------------------

### Install Python Test Dependencies for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/contributing.md

Before running tests, it's necessary to install the development dependencies. This command ensures that all required packages for testing, including `pytest` and Temporal's testing framework, are properly set up in your environment.

```Bash
poetry install --with dev
```

--------------------------------

### Run Temporal AI Agent Tests with Verbose Output

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Executes tests with detailed output, showing individual test names and results. Useful for debugging and understanding test execution flow.

```bash
poetry run pytest -v
```

--------------------------------

### Run Tests for Temporal AI Agent Workflows and Activities

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Execute comprehensive tests for the Temporal AI Agent, covering workflows, activities, and integration, using pytest with options for time-skipping and coverage reporting.

```bash
# Install test dependencies
poetry install --with dev

# Run all tests
poetry run pytest

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

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

# Run with coverage
poetry run pytest --cov=workflows --cov=activities
```

--------------------------------

### Configure Agent Goal for Event, Flight, and Invoice (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet shows how to set the AGENT_GOAL environment variable to activate a specific scenario for the Temporal AI Agent. This particular goal enables the agent to find events, book flights, and arrange train travel with invoice generation.

```bash
AGENT_GOAL=goal_event_flight_invoice
```

--------------------------------

### Python: Mocking External LLM Dependencies

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Shows how to mock external services, specifically LLM API calls, using `unittest.mock.patch` to control return values for isolated testing.

```python
@patch('activities.tool_activities.completion')
async def test_llm_integration(self, mock_completion):
    mock_completion.return_value.choices[0].message.content = '{"test": "response"}'
    # Test implementation
```

--------------------------------

### Execute All Temporal AI Agent Tests

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Runs the entire test suite for the Temporal AI Agent project using pytest. This command provides a comprehensive check of all components.

```bash
poetry run pytest
```

--------------------------------

### APIDOC: Steps to Add Native Tools to Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Detailed steps for integrating new native tools into the Temporal AI Agent, covering tool implementation, function mapping, registration, and goal definition updates.

```APIDOC
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
```

--------------------------------

### Configure Temporal Test Environment for AI Agent Tests

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Specifies the Temporal environment for test execution. Options include local, time-skipping, or connecting to an external server, optimizing for different testing needs.

```bash
poetry run pytest --workflow-environment=local
```

```bash
poetry run pytest --workflow-environment=time-skipping
```

```bash
poetry run pytest --workflow-environment=localhost:7233
```

--------------------------------

### Configure Single Agent Goal for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet demonstrates how to configure the agent to operate in single-agent mode by setting a specific goal. By default, if `AGENT_GOAL` is unset, the agent will use `goal_event_flight_invoice` as its primary objective.

```bash
AGENT_GOAL=goal_event_flight_invoice
```

--------------------------------

### Example of Successful Temporal AI Agent Test Output

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This snippet provides an example of the console output for a successful test run. It shows the pytest summary, including the number of collected items and passed tests, confirming successful execution.

```bash
============================== test session starts ==============================
platform darwin -- Python 3.11.3, pytest-8.3.5, pluggy-1.5.0
rootdir: /Users/steveandroulakis/Documents/Code/agentic/temporal-demo/temporal-ai-agent
configfile: pyproject.toml
plugins: anyio-4.5.2, asyncio-0.26.0
collected 21 items

tests/test_tool_activities.py::TestToolActivities::test_sanitize_json_response PASSED
tests/test_tool_activities.py::TestToolActivities::test_parse_json_response_success PASSED
tests/test_tool_activities.py::TestToolActivities::test_get_wf_env_vars_default_values PASSED
...

============================== 21 passed in 12.5s ==============================
```

--------------------------------

### Run Tests for Temporal AI Agent with Poetry (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/README.md

These commands demonstrate how to install development dependencies and execute the project's comprehensive test suite using Poetry. Tests cover workflows, activities, and integration, with an option for faster execution using time-skipping.

```Bash
poetry install --with dev

poetry run pytest

poetry run pytest --workflow-environment=time-skipping
```

--------------------------------

### Maintain Code Quality in Temporal AI Agent Project

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Ensure code quality and style consistency in the Temporal AI Agent project using Poetry tasks for formatting, linting, and type checking with tools like Black, Isort, and MyPy.

```bash
# Using Poetry tasks
poetry run poe format    # Format code with black and isort
poetry run poe lint      # Check code style and types
poetry run poe test      # Run test suite

# Manual commands  
poetry run black .
poetry run isort .
poetry run mypy --check-untyped-defs --namespace-packages .
```

--------------------------------

### Execute Specific Temporal AI Agent Test Files

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Targets and runs tests from specific files or directories. This allows focused testing on particular components like workflows, activities, or legacy tests.

```bash
poetry run pytest tests/test_agent_goal_workflow.py
```

```bash
poetry run pytest tests/test_tool_activities.py
```

```bash
poetry run pytest tests/workflowtests/
```

--------------------------------

### Bash: Enabling Verbose Pytest Logging

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Command to run pytest with detailed logging enabled, useful for debugging test execution and workflow behavior.

```bash
poetry run pytest --log-cli-level=DEBUG -s
```

--------------------------------

### Execute Python Legacy Worker for Train Activity Failure Demo

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/setup.md

This snippet details how to run a Python legacy worker designed to intentionally fail during train activity processing, showcasing Temporal's failure handling and retry mechanisms. It explains that the activity will retry infinitely until a different worker (like the .NET one) takes over.

```Bash
poetry run python scripts/run_legacy_worker.py
```

--------------------------------

### Temporal AI Agent Goal Structure and Tooling (APIDOC)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Documentation of the agent's goal organization, categorized by domain, and the two primary types of tools (Native and MCP) that goals can leverage for task execution.

```APIDOC
Goal Categories:
- 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)

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

--------------------------------

### Configure MCP Tools in Temporal AI Agent (Python)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Steps to integrate and configure Model Context Protocol (MCP) servers for external tool usage within the Temporal AI Agent. This involves defining reusable servers in `shared/mcp_config.py`, linking them to goal definitions, and setting necessary environment variables for API keys.

```Python
# 1. Configure MCP server definition in shared/mcp_config.py (for reusable servers)
# Example:
# mcp_server_definition = {
#     "name": "my_mcp_server",
#     "url": "http://localhost:8000/mcp",
#     "api_key_env_var": "MY_API_KEY"
# }

# 2. Create or update goal definition in appropriate file in goals/ directory with mcp_server_definition
# Example in goals/my_category.py:
# my_goal = {
#     "name": "PerformMCPAction",
#     "mcp_server_definition": "my_mcp_server", # Reference the defined server
#     "tool_name": "some_mcp_tool"
# }

# 3. Set required environment variables (API keys, etc.)
# Example: export MY_API_KEY="your_api_key_here"
```

--------------------------------

### Run Optional Temporal AI Agent .NET Enterprise Worker

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Build and execute the optional .NET worker implementation for enterprise activities, such as train booking, within the Temporal AI Agent system.

```bash
make run-enterprise     # Using Makefile
```

```csharp
# Or manually:
cd enterprise
dotnet build
dotnet run
```

--------------------------------

### Define and Extend Goals in Temporal AI Agent (Python)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/AGENTS.md

Instructions for creating new goal files within the `goals/` directory and integrating them into the agent's overall goal list. This process ensures new high-level objectives are recognized and actionable by the agent.

```Python
# 1. Create goal file in goals/ directory (e.g., goals/my_category.py)
# Example:
# # goals/my_category.py
# from temporal_ai_agent.goals.base import Goal
#
# class MyNewGoal(Goal):
#     name = "MyNewGoal"
#     description = "A description of my new goal."
#     # ... define tools, steps, etc.

# 2. Import and extend the goal list in goals/__init__.py
# Example:
# # goals/__init__.py
# from .finance import finance_goals
# from .hr import hr_goals
# # ...
# from .my_category import my_category_goals # Import your new goals

# ALL_GOALS = finance_goals + hr_goals + my_category_goals # Extend the list
```

--------------------------------

### Python: Ensuring Test Isolation with Unique Task Queues

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Shows how to generate a unique task queue name for each test, preventing interference between concurrent test runs.

```python
task_queue_name = str(uuid.uuid4())
```

--------------------------------

### Configure MCP Server Definitions in Python

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

MCP server definitions can be configured using predefined configurations from `shared/mcp_config.py` or by defining custom `MCPServerDefinition` objects directly within your goal. This configuration specifies how the MCP server is launched and which tools it provides. Proper setup ensures the agent can discover and interact with external services.

```Python
# Using predefined configurations (e.g., in your goal definition):
from shared.mcp_config import get_stripe_mcp_server_definition

mcp_server_definition=get_stripe_mcp_server_definition(included_tools=["list_products", "create_customer"])

# Defining a custom MCP Server Definition (e.g., in your goal definition):
import os
from models.tool_definitions import MCPServerDefinition

mcp_server_definition=MCPServerDefinition(
    name="stripe-mcp",
    command="npx",
    args=[
        "-y",
        "@stripe/mcp",
        "--tools=all",
        f"--api-key={os.getenv('STRIPE_API_KEY')}"
    ],
    env=None,
    included_tools=[
        "list_products",
        "list_prices",
        "create_customer",
        "create_invoice",
        "create_payment_link"
    ]
)
```

--------------------------------

### Filter Temporal AI Agent Tests by Keyword or Marker

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Allows running a subset of tests based on keywords present in their names or custom markers applied to them. This is useful for targeted testing and skipping irrelevant tests.

```bash
poetry run pytest -k "validation"
```

```bash
poetry run pytest -k "workflow"
```

```bash
poetry run pytest -k "activity"
```

```bash
poetry run pytest -m integration
```

```bash
poetry run pytest -m "not slow"
```

--------------------------------

### Configure Pytest Test Discovery for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Defines Pytest configuration options, specifically excluding the 'vibe/' directory from test collection. This prevents conflicts with sample tests and streamlines the testing process.

```TOML
[tool.pytest.ini_options]
norecursedirs = ["vibe"]
```

--------------------------------

### Environment Variables for Temporal AI Agent Testing

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/tests/README.md

Documents key environment variables that influence test behavior, particularly for LLM integration and agent goal settings. These variables allow customization of test runs without modifying code.

```APIDOC
LLM_MODEL: string (default: "openai/gpt-4")
  - Description: Model to use for LLM testing.
LLM_KEY: string
  - Description: API key for LLM service.
LLM_BASE_URL: string
  - Description: Custom base URL for LLM service.
SHOW_CONFIRM: boolean
  - Description: Whether to show confirmation dialogs.
AGENT_GOAL: string
  - Description: Default agent goal setting.
```

--------------------------------

### Format Python Code with Black and Isort

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/contributing.md

This snippet demonstrates how to automatically format Python code using `black` for consistent styling and `isort` for sorting imports. It's crucial to run these commands before committing to maintain codebase consistency.

```Bash
poetry run poe format
```

```Bash
poetry run black .
poetry run isort .
```

--------------------------------

### Run All Python Tests with Pytest for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/contributing.md

This command executes the entire test suite for the project using `pytest`. It's a fundamental step to verify that all existing functionalities work as expected after making changes.

```Bash
poetry run pytest
```

--------------------------------

### Temporal AI Agent Test Architecture Overview

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This section describes the core components and frameworks used in the Temporal AI Agent's test suite. It highlights the use of Temporal's testing framework, pytest-asyncio, and mocking for robust and efficient testing.

```APIDOC
Components:
  - Temporal Testing Framework: For workflow and activity testing
  - pytest-asyncio: For async test support
  - unittest.mock: For mocking external dependencies
  - Test Fixtures: For consistent test data and setup
Dependencies:
  - All external dependencies (LLM calls, file I/O) are mocked to ensure fast, reliable tests.
```

--------------------------------

### Configure Tool Definitions in Python Registry

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

This snippet demonstrates how to define a new tool within the `tool_registry.py` file. Each tool requires a unique name, a clear LLM-facing description, and a list of input arguments. Arguments are defined using the `ToolArgument` model, and even tools without inputs must declare an empty `arguments` list.

```Python
# In tools/tool_registry.py

from models.tool_definitions import ToolArgument, ToolDefinition

# Example of adding a new tool definition
current_pto_tool_definition = ToolDefinition(
    name="current_pto_tool",
    description="Retrieves the current PTO balance for a specified employee.",
    arguments=[
        ToolArgument(name="employee_id", type="string", description="The ID of the employee to query.")
    ]
)

tool_definitions = {
    "current_pto_tool": current_pto_tool_definition,
    # ... other tool definitions
}
```

--------------------------------

### Define a New Agent Goal in Python

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

This snippet illustrates how to define a new agent goal by creating a Python file in the /goals/ directory. It shows the structure for specifying native tools using tool_registry.

```Python
tools=[
    tool_registry.current_pto_tool,
    tool_registry.future_pto_calc_tool,
    tool_registry.book_pto_tool,
]
```

--------------------------------

### Register Native Tools in Python `__init__.py`

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

After implementing a native tool, it must be imported and registered in `tools/__init__.py` to be accessible by the system's `get_handler` function. This step ensures that the AI agent can correctly map a tool name from a goal description to its corresponding executable function. The tool name used in the `if` condition should match the name specified in the goal's description.

```Python
# In tools/__init__.py

from .current_pto import current_pto
# ... import other tools

def get_handler(tool_name: str):
    if tool_name == "CurrentPTO":
        return current_pto
    # ... other tool handlers
    return None
```

--------------------------------

### Configure Temporal AI Agent Tests for Local Environment

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command explicitly configures the test suite to run against a local Temporal environment. It's the default setting and suitable for standard local development and debugging.

```bash
poetry run pytest --workflow-environment=local
```

--------------------------------

### Run Temporal AI Agent Tests with Time-Skipping

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command executes the test suite using Temporal's time-skipping environment. This significantly speeds up workflow tests, making it ideal for CI/CD pipelines and rapid local development.

```bash
poetry run pytest --workflow-environment=time-skipping
```

--------------------------------

### Run Python Tests with Time-Skipping for Faster Execution

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/contributing.md

For quicker test execution, especially in continuous integration environments, this command runs tests using Temporal's time-skipping workflow environment. This optimizes the testing process by accelerating time-based operations.

```Bash
poetry run pytest --workflow-environment=time-skipping
```

--------------------------------

### Configure Temporal AI Agent Tests for External Temporal Server

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command directs the test suite to connect to an external Temporal server running at a specified address. This is useful for testing against a dedicated or remote Temporal instance.

```bash
poetry run pytest --workflow-environment=localhost:7233
```

--------------------------------

### Execute All Tests for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This command runs the entire test suite for the Temporal AI Agent project using pytest. It's a quick way to verify the overall health and functionality of the codebase.

```bash
poetry run pytest
```

--------------------------------

### Implement Native Tool Functions in Python

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

This section outlines the structure for implementing native tool logic in dedicated Python files within the `/tools` directory. The file and function names should align with the tool's identifier (e.g., `current_pto.py` for `current_pto_tool`). Each tool function must accept a `dict` for arguments and return a `dict` matching the expected output format, including validation for deterministic behavior.

```Python
# In tools/current_pto.py

def current_pto(args: dict) -> dict:
    """Retrieves the current PTO balance for an employee."""
    employee_id = args.get("employee_id")

    if not employee_id:
        return {"error": "employee_id is required"}

    # Simulate fetching PTO from a database or external system
    pto_data = {
        "EMP123": {"balance": 40, "unit": "hours"},
        "EMP456": {"balance": 80, "unit": "hours"}
    }

    balance_info = pto_data.get(employee_id)
    if balance_info:
        return {"employee_id": employee_id, "pto_balance": balance_info["balance"], "unit": balance_info["unit"]}
    else:
        return {"error": f"No PTO data found for employee ID: {employee_id}"}
```

--------------------------------

### Run Specific Test Files or Cases for Temporal AI Agent

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

These commands allow selective execution of tests, targeting specific files, classes, methods, or patterns. This is useful for focused debugging and development, reducing overall test execution time.

```bash
# Run only activity tests
poetry run pytest tests/test_tool_activities.py -v

# Run only workflow tests  
poetry run pytest tests/test_agent_goal_workflow.py -v

# Run a specific test
poetry run pytest tests/test_tool_activities.py::TestToolActivities::test_sanitize_json_response -v

# Run tests matching a pattern
poetry run pytest -k "validation" -v
```

--------------------------------

### Run Python Linting and Type Checks with Poe and Mypy

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/contributing.md

This section outlines the commands to perform static analysis on the Python codebase. It uses `poe the poet` to orchestrate various linters and `mypy` for static type checking, ensuring code quality and catching potential errors early.

```Bash
poetry run poe lint
```

```Bash
poetry run mypy --check-untyped-defs --namespace-packages .
```

--------------------------------

### Configure LLM Model and API Key for Temporal AI Agent (Bash)

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/README.md

This snippet shows how to set essential environment variables for configuring the Large Language Model (LLM) and its API key. These variables are crucial for the agent to interact with various LLM providers supported by LiteLLM, enabling its core functionality.

```Bash
LLM_MODEL=openai/gpt-4o  # or any other model supported by LiteLLM
LLM_KEY=your-api-key-here
```

--------------------------------

### Update Workflow Helpers for Native Tools

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

To correctly identify new native tools and distinguish them from MCP tools, they must be added to the static tools list in `workflows/workflow_helpers.py`. This ensures proper routing and management within the workflow execution. This step is crucial for the system to recognize and utilize the newly added native functionality.

```Python
# In workflows/workflow_helpers.py

NATIVE_TOOLS = [
    "current_pto_tool",
    # Add the name of your new native tool here
    # ... existing native tools
]
```

--------------------------------

### Temporal AI Agent Test Coverage Overview

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This section outlines the key areas covered by the test suite, including workflows, activities, and integration aspects. It ensures comprehensive validation of the agent's core functionalities and interactions.

```APIDOC
Workflows:
  - AgentGoalWorkflow initialization and execution
  - Signal handling (user_prompt, confirm, end_chat)
  - Query methods (conversation history, agent goal, tool data)
  - State management and conversation flow
  - Validation and error handling
Activities:
  - ToolActivities class methods
  - LLM integration (mocked)
  - Environment variable handling
  - JSON response processing
  - Dynamic tool activity execution
Integration:
  - End-to-end workflow execution
  - Activity registration in workers
  - Temporal client interactions
```

--------------------------------

### Debug Temporal AI Agent Tests with Verbose Logging and Coverage

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

These commands provide options for debugging tests, including enabling verbose logging for detailed output and running tests with code coverage analysis. This helps in identifying issues and assessing code quality.

```bash
# Enable verbose logging
poetry run pytest --log-cli-level=DEBUG -s

# Run with coverage
poetry run pytest --cov=workflows --cov=activities
```

--------------------------------

### Integrate External MCP Tools

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

MCP (Model Context Protocol) tools facilitate integration with external services like Stripe or databases without custom code. They are dynamically loaded and converted to `ToolDefinition` objects, with the system automatically routing calls to the appropriate MCP server. This section covers configuring MCP server definitions and understanding their operational flow.

```APIDOC
class MCPServerDefinition:
    """Defines an external Model Context Protocol (MCP) server.

    MCP servers provide external tools that can be integrated into the agent's workflow.
    """
    name: string
        # Identifier for the MCP server (e.g., "stripe-mcp").
    command: string
        # The command used to start the MCP server process (e.g., "npx", "python").
    args: array<string>
        # A list of arguments to pass to the command when starting the MCP server.
    env: object | null
        # Optional. A dictionary of environment variables to set for the MCP server process.
    included_tools: array<string> | null
        # Optional. A list of specific tool names to include from this MCP server.
        # If omitted, all tools exposed by the MCP server will be included.
```

--------------------------------

### Python: Define Tool Argument for User Confirmation

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

This Python snippet defines a ToolArgument named 'userConfirmation' of type 'string'. It is used to explicitly capture a user's desire to confirm an action, providing a robust mechanism for hard confirmation within a Temporal AI agent workflow, independent of LLM prompts.

```Python
        ToolArgument(
            name="userConfirmation",
            type="string",
            description="Indication of user's desire to book PTO",
        ),
```

--------------------------------

### Temporal AI Agent Test Environment Variables Reference

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/testing.md

This section details the environment variables that can be used to configure the test suite's behavior. These variables control aspects like the LLM model used and API keys, though keys are typically mocked during tests.

```APIDOC
- LLM_MODEL:
    type: string
    description: Model for LLM testing.
    default: "openai/gpt-4"
- LLM_KEY:
    type: string
    description: API key for LLM service (mocked in tests).
- LLM_BASE_URL:
    type: string
    description: Custom LLM endpoint.
    optional: true
```

--------------------------------

### Integrate New Agent Goal into Goal List in Python

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

After defining a new agent goal, it must be imported and added to the main goal_list in goals/__init__.py to be discoverable by the agent system.

```Python
from goals.my_category import my_category_goals
goal_list.extend(my_category_goals)
```

--------------------------------

### Configure Goal Categories for Agent Organization

Source: https://github.com/steveandroulakis/temporal-ai-agent/blob/main/docs/adding-goals-and-tools.md

Goal categories help organize and discover goals, especially in multi-agent mode. This snippet shows how to set a unique category tag in your .env file and reference it in your goal definition.

```Shell
GOAL_CATEGORIES="hr,sales,finance"
```
Tokens:
Raw