Creating New Agent

Creating a New Agent

This skill provides a comprehensive guide for creating a new specialized agent in the QuAIA™ framework. Agents are A2A-compliant (Agent-to-Agent protocol) services that handle specific QA-related tasks.

Overview

Each agent in QuAIA consists of:

1. Main module (main.py) - Agent class inheriting from AgentBase
2. Prompt module (prompt.py) - Prompt classes inheriting from PromptBase
3. System prompts (system_prompts/) - Text template files for LLM instructions
4. Dockerfile - Container configuration for deployment
5. Configuration - Class in config.py for agent-specific settings
6. Unit tests - Test file in tests/agents/

Step-by-Step Instructions

Step 1: Create the Agent Directory Structure

Create a new directory under agents/ with the following structure:

agents/<agent_name>/
├── __init__.py (empty file)
├── main.py
├── prompt.py
├── Dockerfile
└── system_prompts/
    └── main_prompt_template.txt

Example command:

mkdir -p agents/<agent_name>/system_prompts

Step 2: Define the Configuration Class

Add a configuration class in config.py using the template:

📄 Template: resources/config_template.py

Configuration field descriptions:

• THINKING_BUDGET: Token budget for chain-of-thought reasoning (0 disables it)
• OWN_NAME: Human-readable name displayed in the orchestrator dashboard
• PORT: Internal container port the agent listens on
• EXTERNAL_PORT: Externally accessible port (usually same as PORT)
• MODEL_NAME: The LLM model to use (format: provider:model-name)
• MAX_REQUESTS_PER_TASK: Limit on tool/MCP calls per task execution

Step 3: Define the Output Model

If the agent returns structured output, add a Pydantic model in common/models.py:

📄 Template: resources/output_model_template.py

Important: Inherit from BaseAgentResult to include the llm_comments field for debugging.

Step 4: Create the Prompt Classes

Create agents/<agent_name>/prompt.py:

📄 Template: resources/prompt_template.py

Step 5: Create the System Prompt Template

Create agents/<agent_name>/system_prompts/main_prompt_template.txt:

📄 Template: resources/system_prompt_template.txt

Best practices for prompts:

• Be specific about the expected workflow
• List tasks in numbered sequence
• Include error handling instructions
• Reference tools by describing their purpose, not implementation

Step 6: Create the Agent Class

Create agents/<agent_name>/main.py:

📄 Template: resources/agent_template.py

Key points:

• The agent class MUST inherit from AgentBase
• Implement get_thinking_budget() and get_max_requests_per_task()
• Custom tools are defined as methods with full docstrings (LLM uses these)
• The app variable exposes the A2A-compliant FastAPI application
• start_as_server() runs the agent standalone with uvicorn

Step 7: Create the Dockerfile

Create agents/<agent_name>/Dockerfile:

📄 Template: resources/dockerfile_template

Step 8: Update Cloud Build Configuration (Optional)

If deploying to Google Cloud Run, add build and deploy steps to cloudbuild.yaml:

1. Add a build step for the Docker image
2. Add a push step for the image
3. Add a deploy step for Cloud Run

Step 9: Create Unit Tests

Create tests/agents/test_<agent_name>.py:

📄 Example: examples/test_agent_example.py

Verification Checklist

After creating the agent, verify:

• Agent directory structure is complete
• Configuration class added to config.py
• Output model (if any) added to common/models.py
• Prompt class properly inherits from PromptBase
• System prompt template exists and is well-structured
• Agent class properly inherits from AgentBase
• Dockerfile follows the standard pattern
• Unit tests pass: pytest tests/agents/test_<agent_name>.py -v
• Agent starts successfully: python agents/<agent_name>/main.py
• Agent card is discoverable at http://localhost:<port>/.well-known/agent.json

Running the Agent Locally

# Activate virtual environment
.venv\Scripts\activate

# Run the agent
python agents/<agent_name>/main.py

The agent will start listening on the configured port and automatically expose:

• /.well-known/agent.json - Agent card for discovery
• A2A task endpoints for receiving and processing tasks

Converted and distributed by TomeVault — claim your Tome and manage your conversions.