Agent Builder

Agent Builder Guide

This skill provides guidelines and templates for building Pydantic AI agents that adhere to our standardized architecture using the agent-utilities package.

Architecture: Agent Pattern

When building a new agent, you must use the Agent Pattern. Agent will have access to all authorized capabilities via the mcp-client universal skill.

Implementation Workflow

Follow these steps when defining a new agent package:

1. Initialize the Package

1. Create a my_agent/agent_data directory within the package.
2. Ensure pyproject.toml depends on agent-utilities>=2.0.0 (and includes agent under optional dependencies).
3. Configure project.scripts in pyproject.toml to expose the agent entry point (e.g., my-agent = "my_package.agent_server:agent_server").

2. Configure Agent Workspace Files

The agent's behavior and state are controlled by several core files in the agent_data/ directory:

• main_agent.json (lives at {pkg_dir}/main_agent.json, golden-standard convention): the main-agent prompt definition — name, role, system prompt, tools, tone, and goal.
• USER.md: Information about the user (name, style, preferences).
• A2A_AGENTS.md: Registry of known A2A peer agents.
• Knowledge Graph (knowledge_graph.db): Long-term memory and topological intelligence (managed via knowledge_tools).
• CRON.md: Persistent scheduled tasks.
• CRON_LOG.md: History of execution for scheduled tasks.
• HEARTBEAT.md: Periodic self-check tasks and instructions.
• chats/: (Directory) Persistent storage for background job conversations.
• mcp_config.json: Configuration for MCP servers.
• icon.png: Visual representation of the agent.

Each file plays a critical role in how the agent operates and interacts within the workspace.

3. Implement the Agent Entry Point (agent_server.py)

Create agent_server.py in the package source directory (NOT in agent_data). Use load_identity() to fetch the [default] metadata. Capture the environmental default variables (including OTel, host, port, mcp config, and A2A configurations) and pass them to create_agent_server(). Ensure you extract the appropriate arguments from create_agent_parser to pass to create_agent_server, including:

• otel_endpoint, otel_headers, otel_public_key, otel_secret_key, otel_protocol
• a2a_broker, a2a_broker_url, a2a_storage, a2a_storage_url

4. System Prompt and Context

When initializing the Agent, ensure the system prompt is built dynamically. Using build_system_prompt_from_workspace() is the recommended approach to ensure core context files (e.g. {pkg_dir}/main_agent.json) are combined into a rich prompt. Historical context, logs, and cron data are injected dynamically during the execution graph's memory_selection_step via the Knowledge Graph.

4. Verification

After implementation:

• Verify the agent starts correctly by running python -m my_package.agent --help.
• Run run_pre_commits.sh (or pre-commit run --all-files) in the workspace to ensure styling and syntax compliance.

Identity API compatibility

The identity contract is owned by agent-utilities, not bundled with this skill. Before implementing the entry point, verify the installed version's load_identity() signature and returned fields; treat that installed API as the source of truth when it differs from this guide.