AgentPool

https://phil65.github.io/agentpool/
Admin
AgentPool is a Python framework for unified agent orchestration that supports native agents, ACP...
Tokens:131,198
Snippets:1,622
Trust Score:9.7
Update:6 months ago
Show doc for...
Tokens:
Raw
### Basic Storage Setup

Source: https://phil65.github.io/agentpool/core-concepts/storage

A minimal configuration example using a single SQL provider.

```yaml
storage:
  providers:
    - type: sql              # Single provider
```

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

### Continuous Monitoring Setup

Source: https://phil65.github.io/agentpool/programmatic%20-usage/injection

Example of setting up an agent for continuous operation using `run_in_background` and connecting agents with `connect_to`.

```python
@node_function
async def monitor_system(
    watcher: Agent[None],
    alerter: Agent[None],
):
    await watcher.run_in_background(
        "Check system status",
        interval=300,  # every 5 minutes
        max_count=None,  # run indefinitely
    )
    watcher.connect_to(alerter)
```

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

### Execute Monitored Pipeline

Source: https://phil65.github.io/agentpool/programmatic%20-usage/task-monitoring

Full example demonstrating agent setup, background execution, real-time monitoring, and final statistics reporting.

```python
from agentpool import AgentPool

async def main():
    async with AgentPool() as pool:
        # Create three agents with different roles
        analyzer = Agent(model="xy", name="analyzer", system_prompt="You analyze text and find key points.")
        await pool.add_agent(analyzer)
        summarizer = ClaudeCodeAgent(name="summarizer", system_prompt="You create concise summaries.")
        await pool.add_agent(summarizer)
        critic = CodexAgent(name="critic", system_prompt="You evaluate and critique summaries.")
        await pool.add_agent(critic)
        # Create execution pipeline
        run = agent1 | agent2 | agent3

        # Start run and get stats object
        stats = await run.run_in_background("Process this text...")

        # Monitor progress
        while run.is_running:
            print("\nCurrent status:")
            print(f"Processed messages: {stats.message_count}")
            print(f"Active connections: {len(stats)}")
            print(f"Errors: {len(stats.error_log)}")
            await anyio.sleep(0.5)

        # Wait for completion
        result = await run.wait()

        # Final statistics
        print(f"\nExecution complete:")
        print(f"Total cost: ${stats.total_cost:.4f}")
        print(f"Total tokens: {stats.token_count}")
```

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

### Advanced Multiple Provider Setup

Source: https://phil65.github.io/agentpool/core-concepts/storage

Example of configuring multiple providers, including a PostgreSQL database and a file-based backup.

```yaml
storage:
  providers:
    - type: sql             # Main storage
      url: postgresql://...
    - type: file           # Backup
      path: backup.yml
```

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

### Start OpenCode Server

Source: https://phil65.github.io/agentpool/servers/opencode-server

Use this command to start the OpenCode server with a specified configuration file and port.

```bash
# Start the OpenCode server
agentpool serve-opencode config.yml --port 4096

```

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

### Run Round-Robin Example with AgentPool

Source: https://phil65.github.io/agentpool/examples/round_robin

This script initiates a round-robin communication example using AgentPool. It sets up the OpenAI API key and starts a command for 'player1' with an initial prompt. Ensure the 'agentpool' dependency is installed.

```python
# /// script
# dependencies = ["agentpool"]
# ///
"""Run round-robin example demonstrating cyclic communication pattern."""
from __future__ import annotations
import os
from agentpool_cli.run import run_command
from agentpool.docs.utils import get_config_path, is_pyodide
# set your OpenAI API key here
os.environ["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "your_api_key_here")
if __name__ == "__main__":
# Use utils to get config path that works in both environments
config_path = get_config_path(None if is_pyodide() else __file__)
run_command(
node_name="player1",
prompts=["Start the word chain with: tree"],
config_path=str(config_path),
show_messages=True,
detail_level="simple",
show_metadata=False,
show_costs=False,
verbose=False,
)
```

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

### Complete Agent Configuration Example

Source: https://phil65.github.io/agentpool/configuration/prompts

A comprehensive example showing multiple prompt types and categories applied to a single agent.

```yaml
prompts:
  system_prompt:
    # Role definitions
    technical_expert:
      category: role
      content: |
        You are a technical expert specializing in:
        - Software development best practices
        - System architecture and design
        - Code review and quality assurance

    # Methodology definitions
    systematic:
      category: methodology
      content: |
        Follow this systematic approach:
        1. Understand requirements fully
        2. Break down complex problems
        3. Apply best practices consistently
        4. Validate results thoroughly

    # Tone definitions
    professional:
      category: tone
      content: |
        Maintain professional communication:
        - Use formal, precise language
        - Be respectful and constructive
        - Provide clear explanations

agents:
  senior_dev:
    model: gpt-4
    system_prompt:
      - "Specialize in Python and TypeScript development."
      - type: library
        reference: technical_expert
      - type: library
        reference: systematic
      - type: library
        reference: professional
      - type: file
        path: "prompts/coding_style.j2"
```

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

### Complete Agent Configuration Example

Source: https://phil65.github.io/agentpool/configuration/node-types/agent

An example showcasing a fully configured agent, including its name, description, model, tools, and system prompt.

```APIDOC
## Agents Section - Complete Example

### Description
This section provides a complete example of an agent configuration, demonstrating how to define an agent named 'web_assistant' with specific tools and system prompts.

### Method
Not Applicable (Configuration Structure)

### Endpoint
Not Applicable (Configuration Structure)

### Parameters
#### Request Body (YAML Structure)
- **agents** (object) - Dictionary of agent configurations.
  - **web_assistant** (object) - Configuration for the 'web_assistant' agent.
    - **description** (string) - Optional description (e.g., "Helps with web tasks").
    - **model** (string) - Model to use (e.g., `openai:gpt-5`).
    - **tools** (object) - Tools available to the agent.
      - **open_browser** (object)
        - **import_path** (string) - Path to import the tool (e.g., `webbrowser.open`).
        - **description** (string) - Description of the tool (e.g., "Opens URLs in browser").
    - **system_prompt** (array of strings) - System prompts defining behavior (e.g., `["You are a web assistant.", "Use open_browser to open URLs."]`).
    - **retries** (integer) - Number of retries for failed operations (e.g., 2).

### Request Example
```yaml
agents:
  web_assistant:
    description: "Helps with web tasks"
    model: openai:gpt-5
    tools:
      open_browser:
        import_path: webbrowser.open
        description: "Opens URLs in browser"
    system_prompt:
      - "You are a web assistant."
      - "Use open_browser to open URLs."
    retries: 2
```

### Response
#### Success Response (200)
- **Agent Status** (object) - Confirmation of the agent's successful configuration.

#### Response Example
```json
{
  "agent_name": "web_assistant",
  "status": "configured",
  "message": "Web assistant agent is ready."
}
```
```

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

### System Prompt Tool Output Examples

Source: https://phil65.github.io/agentpool/advanced/system-prompts

Examples of how tool information is rendered in the system prompt based on usage style.

```text
You are log_analyzer. Analyze system logs for issues.

You have access to these tools:

- read_logs: Read system log files
- analyze_logs: Analyze logs for patterns
- report_issue: Create issue report

Use them when appropriate to complete your tasks.
```

```text
You MUST use these tools to complete your tasks:

- read_logs: Read system log files
- analyze_logs: Analyze logs for patterns
- report_issue: Create issue report

Do not attempt to perform tasks without using appropriate tools.
```

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

### Install OpenCode TUI with bun

Source: https://phil65.github.io/agentpool/servers/opencode-server

Install the OpenCode Terminal UI globally using bun.

```bash
# Or using bun
bun install -g opencode

```

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

### Set Global Preferences

Source: https://phil65.github.io/agentpool/cli/config

Example of initializing and defining global configuration settings.

```bash
agentpool config init global
```

```yaml
# Global preferences
model_variants:
  fast:
    type: string
    identifier: openai:gpt-4o-mini
  smart:
    type: anthropic
    identifier: claude-sonnet-4-5

storage:
  provider: sql
  database_url: sqlite:///~/.local/share/agentpool/history.db
```

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

### Agent Configuration Example

Source: https://phil65.github.io/agentpool/cli

Example YAML structure for defining agents, models, and tools.

```yaml
agents:
  analyzer:
    display_name: "Text Analyzer"
    model: openai:gpt-4o
    description: "Analyzes text and provides structured output"
    tools:
      - type: file_access
```

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

### Agent Configuration Example

Source: https://phil65.github.io/agentpool/programmatic%20-usage/injection

Example YAML configuration for defining agents with their models and system prompts.

```yaml
agents:
  analyzer:
    model: gpt-5
    system_prompt: "You are an expert code analyzer..."
  reviewer:
    model: gpt-5
    system_prompt: "You are an expert code reviewer..."
```

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

### Install AgentPool

Source: https://phil65.github.io/agentpool/advanced/agui-integration

Commands to install the agentpool package.

```bash
pip install agentpool
# or
uv add agentpool
```

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

### Install AgentPool with uv

Source: https://phil65.github.io/agentpool/getting-started

Use these commands to install the package globally or with specific feature sets.

```bash
uv tool install agentpool
```

```bash
uv tool install agentpool[default, coding]
```

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

### Initialize OpenAIAPIServer Programmatically

Source: https://phil65.github.io/agentpool/servers/openai-api-server

Setup and run the server within a Python application using anyio.

```python
import anyio
from agentpool import AgentPool
from agentpool_server.openai_api_server import OpenAIAPIServer


async def main():
    pool = AgentPool()
    await pool.add_agent(Agent("gpt-4-custom", model="openai:gpt-4"))

    server = OpenAIAPIServer(
        pool,
        host="0.0.0.0",
        port=8000,
        api_key="your-secret-key",  # Optional authentication
        cors=True,
        docs=True,
    )

    async with server, server.run_context():
        await anyio.sleep_forever()


anyio.run(main)
```

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

### Programmatic Usage of OpenCodeServer

Source: https://phil65.github.io/agentpool/servers/opencode-server

Example of how to programmatically run the OpenCode server using the agentpool_server library. It initializes an Agent and then starts the OpenCodeServer with specified host, port, working directory, and agent.

```python
from agentpool_server.opencode_server.server import OpenCodeServer
from agentpool import Agent

async def main():
    agent = Agent("assistant", model="openai:gpt-4o")

    async with agent:
        server = OpenCodeServer(
            host="127.0.0.1",
            port=4096,
            working_dir="/path/to/project",
            agent=agent,
        )
        await server.run()

```

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

### File Access Toolset Configuration

Source: https://phil65.github.io/agentpool/configuration/toolsets/file-access

Configuration examples for the File Access toolset, including basic setup, URI string usage, filesystem configuration, and composed filesystems.

```APIDOC
## File Access Toolset Configuration

### Basic Usage
```yaml
agents:
  my_agent:
    tools:
      - type: file_access
        fs: "file:///workspace"
```

### Filesystem Options
#### URI String
```yaml
tools:
  - type: file_access
    fs: "file:///home/user/project"
```

#### Filesystem Config
```yaml
tools:
  - type: file_access
    fs:
      type: github
      org: sveltejs
      repo: svelte
      sha: main
```

### Composed Filesystems
Mount multiple filesystems together using the `mounts` type:
```yaml
tools:
  - type: file_access
    fs:
      type: mounts
      mounts:
        docs: "github://sveltejs:svelte@main"
        src: "file:///workspace/src"
        data:
          type: s3
          bucket: my-bucket
```
```

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

### Run Two Agents to Explore Git History

Source: https://phil65.github.io/agentpool/examples/mcp_servers_yaml

This example demonstrates how to set up two agents, a picker and an analyzer, that communicate with each other to explore git commit history. It shows agent initialization, prompt configuration, and inter-agent communication setup.

```python
# /// script
# dependencies = ["agentpool"]
# ///
"""Example: Two agents working together to explore git commit history."""
from __future__ import annotations
from agentpool import Agent, Team
from agentpool.docs.utils import run
PICKER = """
You are a specialist in looking up git commits using your tools
from the current working directory."
"""
ANALYZER = """
You are an expert in retrieving and returning information
about a specific commit from the current working directoy."
"""
MODEL = "openai:gpt-5-nano"
SERVERS = ["uvx mcp-server-git"]
async def run_example() -> None:
 picker = Agent(model=MODEL, system_prompt=PICKER, mcp_servers=SERVERS)
 analyzer = Agent(model=MODEL, system_prompt=ANALYZER, mcp_servers=SERVERS)
 # Connect picker to analyzer
 picker >> analyzer
 # Register message handlers to see the messages
 picker.message_sent.connect(lambda msg: print(msg.format()))
 analyzer.message_sent.connect(lambda msg: print(msg.format()))
 # For MCP servers, we need async context.

```

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

### Initialize ConfigCreationTools

Source: https://phil65.github.io/agentpool/configuration/toolsets/config-creation

Example of initializing the toolset, noting that a schema_path argument is required.

```python
from agentpool_toolsets.config_creation import ConfigCreationTools
from agentpool.docs.utils import generate_tool_docs

toolset = ConfigCreationTools()
print(generate_tool_docs(toolset))
```

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

### Full Agent Hooks Example

Source: https://phil65.github.io/agentpool/configuration/hooks

A comprehensive example demonstrating the configuration of multiple hooks (callable, prompt, command) for different stages of agent execution (pre_run, pre_tool_use, post_tool_use, post_run).

```yaml
agents:
  secure_agent:
    model: openai:gpt-4o
    hooks:
      pre_run:
        - type: callable
          import_path: myproject.auth.check_allowed

      pre_tool_use:
        - type: prompt
          prompt: "Is this Bash command safe? $TOOL_INPUT"
          matcher: "Bash"
          model: openai:gpt-4o-mini

        - type: command
          command: python -m myproject.hooks.validate_paths
          matcher: "Write|Edit|Read"

      post_tool_use:
        - type: callable
          import_path: myproject.metrics.record_usage

      post_run:
        - type: command
          command: /scripts/notify-complete.sh

```

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

### Basic Usage Example

Source: https://phil65.github.io/agentpool/configuration/toolsets/code-mode

An example demonstrating the basic usage of the code mode toolset within an agent configuration.

```APIDOC
## Basic Usage

```yaml
agents:
  coder:
    tools:
      - type: code_mode
        tools:
          - type: file_access
            fs: "file:///workspace"
```
```

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

### Implement full agent connection workflow

Source: https://phil65.github.io/agentpool/advanced/connections

A complete example showing agent creation, team formation, connection configuration, and monitoring.

```python
# Create agents
analyzer = Agent(name="analyzer")
planner = Agent(name="planner")
executor = Agent(name="executor")

# Create team
planning_team = planner & executor

# Set up connection with control
talk = analyzer.connect_to(
    planning_team,
    connection_type="run",
    transform=lambda ctx: preprocess_message(ctx.message),
    stop_condition=lambda ctx: ctx.message.metadata.get("complete", False),
    exit_condition=lambda ctx: ctx.message.metadata.get("error", False)
)

talk.when(lambda ctx: ctx.message.metadata.get("priority") == "high")

# Monitor
print(f"Processed {talk.stats.message_count} messages")
```

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

### Run Simple Text Agent Programmatically

Source: https://phil65.github.io/agentpool/getting-started/example-configurations

Use the AgentPool library in Python to load an agent configuration and interact with it. This example shows how to instantiate the pool, get an agent, and run a task.

```python
from agentpool import AgentPool

async with AgentPool("agents.yml") as pool:
    agent = pool.get_agent("url_opener")
    result = await agent.run("Open the Python website")
    print(result.data)

```

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

### Node Connection Example

Source: https://phil65.github.io/agentpool/configuration/connections

Example of configuring a node connection to forward messages to another agent named 'summarizer'.

```yaml
agents:
  analyzer:
    connections:
      - type: node
        name: "summarizer"
        connection_type: "run"
        wait_for_completion: true
```

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

### Define Project-Specific Agents

Source: https://phil65.github.io/agentpool/cli/config

Example of initializing a project config and defining agent-specific settings.

```bash
agentpool config init
```

```yaml
agents:
  coder:
    model: smart  # Uses global model_variant
    system_prompt: "You are an expert in this codebase."
    tools:
      - type: file_access
      - type: bash
```

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

### Install OpenCode TUI with npm

Source: https://phil65.github.io/agentpool/servers/opencode-server

Install the OpenCode Terminal UI globally using npm.

```bash
# Using npm
npm install -g opencode

```

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

### AG-UI Agent with Managed Server

Source: https://phil65.github.io/agentpool/advanced/agui-integration

Configure an AG-UI agent to automatically start and manage a server for testing. Specify the startup command and a delay after starting.

```yaml
agents:
  test_agent:
    type: agui
    endpoint: http://localhost:8765/agent/run
    startup_command: "uv run ag-ui-server config.yml"
    startup_delay: 2.0  # Wait 2 seconds after starting
```

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

### Start Server Modes

Source: https://phil65.github.io/agentpool/cli

Launch various server types for IDE integration, TUI, MCP, or API compatibility.

```bash
# ACP server for IDE integration (Zed, Toad)
agentpool serve-acp config.yml

# OpenCode server for OpenCode TUI/Desktop
agentpool serve-opencode config.yml --port 4096

# MCP server (stdio transport)
agentpool serve-mcp config.yml

# MCP server with SSE transport
agentpool serve-mcp config.yml --transport sse --port 3001

# AG-UI server
agentpool serve-agui config.yml --port 8002

# OpenAI-compatible API server
agentpool serve-api config.yml --port 8000
```

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

### Programmatic AG-UI Server Setup

Source: https://phil65.github.io/agentpool/servers/agui-server

Initialize and run an AGUIServer instance within a Python application using anyio.

```python
import anyio
from agentpool import AgentPool
from agentpool_server.agui_server import AGUIServer


async def main():
    pool = AgentPool()
    await pool.add_agent(Agent("assistant", model="openai:gpt-4"))

    server = AGUIServer(pool, host="localhost", port=8002)

    async with server, server.run_context():
        # Server running at http://localhost:8002
        # Agent available at POST http://localhost:8002/assistant
        await anyio.sleep_forever()


anyio.run(main)
```

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

### One-Line ACP Setup with uvx

Source: https://phil65.github.io/agentpool/getting-started/quickstart

Run AgentPool with ACP integration directly using uvx for a quick setup. Ensure Python 3.13 is available.

```bash
uvx --python 3.13 agentpool@latest serve-acp agents.yml

```

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

### CLI Command: serve-opencode

Source: https://phil65.github.io/agentpool/cli/serve-opencode

Starts an HTTP server implementing the OpenCode API protocol for AgentPool agents.

```APIDOC
## serve-opencode

### Description
Run agents as an OpenCode-compatible HTTP server, enabling AgentPool agents to work with OpenCode TUI and SDK clients.

### Usage
`agentpool serve-opencode [OPTIONS] [CONFIG]`

### Options
- **--host** (string) - Optional - Host to bind to (Default: 127.0.0.1)
- **--port** (integer) - Optional - Port to listen on (Default: 4096)
- **--agent** (string) - Optional - Name of specific agent to use (defaults to pool's default agent)
- **--working-dir** (string) - Optional - Working directory for file operations (defaults to current directory)
- **--help** (flag) - Optional - Show help message and exit

### Configuration Layers
Configurations are merged in the following order (later overrides earlier):
1. Global config (~/.config/agentpool/agentpool.yml)
2. Custom config (AGENTPOOL_CONFIG env var)
3. Project config (agentpool.yml in project root)
4. Explicit config (CLI arguments)
```

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

### Start AgentPool ACP Server

Source: https://phil65.github.io/agentpool/advanced/acp-integration

Start an AgentPool ACP server using a configuration file. Ensure the configuration file path is correct.

```bash
agentpool serve-acp agents.yml

```

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

### Example Workflow with Specialized Agents

Source: https://phil65.github.io/agentpool/configuration/toolsets/subagent

Demonstrates a coordinator agent delegating tasks to specialized researcher and writer agents.

```yaml
agents:
  coordinator:
    tools:
      - type: subagent
    system_prompt: You coordinate work between specialized agents.

  researcher:
    model: openai:gpt-4o
    system_prompt: You research topics thoroughly.

  writer:
    model: openai:gpt-4o
    system_prompt: You write clear documentation.

```

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

### Configure Knowledge via YAML

Source: https://phil65.github.io/agentpool/core-concepts/knowledge

Example YAML configuration for defining agent knowledge paths, resources, and prompts.

```yaml
agents:
  researcher:
    # Knowledge configuration
    knowledge:
      # Simple paths
      paths:
        - "docs/**/*.md"
        - "https://api.example.com/docs"

      # Rich resources
      resources:
        - type: path
          path: "src/**/*.py"
          watch: true

        - type: text
          content: "Important context..."

        - type: cli
          command: "git log"

      # Context prompts
      prompts:
        - "Consider these guidelines..."
        - type: file
          path: "prompts/analysis.txt"
```

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

### Correct Async Initialization of Agents

Source: https://phil65.github.io/agentpool/programmatic%20-usage/creating-agents

Always use async context managers for agents to ensure proper async initialization, including MCP server setup, tool registration, runtime configuration loading, resource initialization, and connection setup.

```python
# ❌ Limited: Works, but not everything is initialized
agent = Agent(...)
result = await agent.run("Hello")

# ✅ Correct - proper async initialization
async with Agent(...) as agent:
    result = await agent.run("Hello")

```

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

### Define multi-source filesystem mounts

Source: https://phil65.github.io/agentpool/configuration/toolsets/file-access

Example configuration for mapping multiple remote and local sources.

```yaml
tools:
  - type: file_access
    fs:
      type: mounts
      mounts:
        svelte: "github://sveltejs:svelte@main"
        react: "github://facebook:react@main"
        local: "file:///docs"
```

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

### Basic Composio Agent Setup

Source: https://phil65.github.io/agentpool/configuration/toolsets/composio

Configure an agent to use the Composio toolset with specific applications like GitHub and Slack.

```yaml
agents:
  my_agent:
    tools:
      - type: composio
        apps:
          - github
          - slack
```

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

### AI-Human Interaction Example

Source: https://phil65.github.io/agentpool/examples/mcp_servers_yaml

This example illustrates how AI agents can interact with humans. It covers setting up a human agent and enabling an AI assistant to request human input when it encounters questions it cannot answer.

```text
Assistant: I need to check about Project DoomsDay's status. Let me ask the human.
Human: Project DoomsDay is currently in Phase 2, with 60% completion.
Assistant: Based on the human's input, Project DoomsDay is in Phase 2 and is 60% complete.
```

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

### curl API Examples

Source: https://phil65.github.io/agentpool/servers/openai-api-server

Common curl commands for interacting with the API server.

```bash
# List models
curl http://localhost:8000/v1/models \
  -H "Authorization: Bearer your-secret-key"

# Chat completion
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

# Streaming
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "Authorization: Bearer your-secret-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "assistant",
    "messages": [{"role": "user", "content": "Hello!"}],
    "stream": true
  }'
```

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

### Background Execution Lifecycle

Source: https://phil65.github.io/agentpool/programmatic%20-usage/team-run

Demonstrates starting, waiting for, and cancelling background tasks.

```python
# Start execution
stats = await run.run_in_background("Process this")

# Wait for completion later
results = await run.wait()

# Or cancel if needed
await run.cancel()
```

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

### Define local filesystem access

Source: https://phil65.github.io/agentpool/configuration/toolsets/file-access

Example configuration for accessing a local directory.

```yaml
tools:
  - type: file_access
    fs: "file:///home/user/project"
    max_file_size_kb: 128
```

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

### Initialize and Run AgentPool

Source: https://phil65.github.io/agentpool/cli

Create a starter configuration file and execute a prompt using the discovered configuration.

```bash
# Create a starter config
agentpool config init

# Edit the config, then run
agentpool run myagent "Hello"
```

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

### Run AG-UI Server via CLI

Source: https://phil65.github.io/agentpool/servers/agui-server

Commands to start the AG-UI server using the agentpool CLI.

```bash
# Run with default settings
agentpool serve-agui config.yml

# Custom host and port
agentpool serve-agui config.yml --host 0.0.0.0 --port 8002
```

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

### Initialize and Use Agent Pool

Source: https://phil65.github.io/agentpool/core-concepts/agent-pool

Example of initializing an AgentPool with shared dependencies and performing agent operations.

```python
from agentpool import AgentPool
from myapp.config import AppConfig  # Your dependency type

async def main():
    # Initialize pool with shared dependencies
    async with AgentPool[AppConfig]("agents.yml", shared_deps=app_config) as pool:
        # Get existing agent
        analyzer = pool.get_agent("analyzer")
        # Create new agent dynamically
        planner = Agent(name="dynamic_planner", model="openai:gpt-5", system_prompt="You plan next steps.")
        await pool.add_agent(planner)
        # Use agents
        result = await analyzer.run("Analyze this text...")
        # create teams
        team = pool.create_team([analyzer, planner])
        await team.run("Process this task...")

if __name__ == "__main__":
    anyio.run(main)
```

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

### Initialize New Configuration

Source: https://phil65.github.io/agentpool/cli/config

Commands to generate starter configuration files at various scopes or specific paths.

```bash
# Create a starter config in current project
agentpool config init

# Create a global config for user-wide preferences
agentpool config init global

# Create at a specific path
agentpool config init ./configs/my-agents.yml

# Overwrite existing config
agentpool config init --force
```

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

### CLI Command: agentpool serve-api

Source: https://phil65.github.io/agentpool/cli/serve-api

Starts an OpenAI-compatible completions API server backed by a single agent.

```APIDOC
## CLI Command: agentpool serve-api

### Description
Runs an agent as an OpenAI-compatible completions API server. This creates an API server backed by a single agent, utilizing the agent's model discovery for model listing.

### Usage
`agentpool serve-api [OPTIONS] [CONFIG]`

### Options
- **--host** (string) - Optional - Host to bind server to (Default: localhost)
- **--port** (integer) - Optional - Port to listen on (Default: 8000)
- **--cors** (boolean) - Optional - Enable CORS (Default: True)
- **--agent** (string) - Optional - Name of specific agent to use (defaults to pool's default)
- **--show-messages** (flag) - Optional - Show message activity
- **--help** (flag) - Optional - Show this message and exit
```

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

### Python ImportError Example

Source: https://phil65.github.io/agentpool/configuration/toolsets/user-interaction

This traceback indicates an `ImportError` when trying to import `UserInteractionTools` from `agentpool_toolsets.builtin`. This usually means the package is not installed correctly or the path is incorrect.

```python
Traceback (most recent call last):
  File "/home/runner/work/agentpool/agentpool/.venv/lib/python3.13/site-packages/mknodes/mdext/execute_ext.py", line 226, in formatter
    output = _run_python(source, session=session)
  File "/home/runner/work/agentpool/agentpool/.venv/lib/python3.13/site-packages/mknodes/mdext/execute_ext.py", line 104, in _run_python
    exec(compiled, exec_globals)
    ~~~~^^^^^^^^^^^^^^^^^^^^^^^^
  File "<exec>", line 1, in <module>
ImportError: cannot import name 'UserInteractionTools' from 'agentpool_toolsets.builtin' (/home/runner/work/agentpool/agentpool/src/agentpool_toolsets/builtin/__init__.py)
```

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

### Common Agent Configuration Patterns

Source: https://phil65.github.io/agentpool/core-concepts/toolsets

Example configurations for basic assistants, team coordinators, and developer agents.

```yaml
agents:
  assistant:
    model: openai:gpt-4
    tools:
      - type: resource_access
      - type: file_access
      - type: user_interaction
```

```yaml
agents:
  coordinator:
    model: openai:gpt-4
    tools:
      - type: agent_cli
      - type: history
    system_prompt: You coordinate tasks across multiple agents
```

```yaml
agents:
  developer:
    model: anthropic:claude-3-5-sonnet-20241022
    tools:
      - type: file_access
      - type: code_execution
      - type: process_management
      - type: tool_management
    system_prompt: You are a software developer with full system access
```

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

### Programmatic Agent Interaction with AgentPool

Source: https://phil65.github.io/agentpool/getting-started/quickstart

Use the AgentPool Python library to interact with configured agents. This example shows how to get an agent and run a query, printing the response data.

```python
from agentpool import AgentPool

async def main():
    async with AgentPool("agents.yml") as pool:
        agent = pool.get_agent("assistant")
        response = await agent.run("What is Python?")
        print(response.data)

if __name__ == "__main__":
    import anyio
    anyio.run(main)

```

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

### Hooks Configuration Example

Source: https://phil65.github.io/agentpool/configuration/hooks

YAML configuration for agent lifecycle hooks, specifying events like pre_run, post_run, pre_tool_use, and post_tool_use.

```yaml
- pre_run: []
  post_run: []
  pre_tool_use: []
  post_tool_use: []
```

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

### Configure a Web Assistant Agent

Source: https://phil65.github.io/agentpool/configuration/node-types/agent

A complete example showing agent metadata, model selection, tool definition, and system prompt configuration.

```yaml
agents:
  web_assistant:                   # Name of the agent
    description: "Helps with web tasks"  # Optional description
    model: openai:gpt-5           # Model to use
    tools:
      open_browser:
        import_path: webbrowser.open
        description: "Opens URLs in browser"
    system_prompt:
      - "You are a web assistant."
      - "Use open_browser to open URLs."
    retries: 2                   # Number of retries for failed
```

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

### Create and Use Agent with String Output

Source: https://phil65.github.io/agentpool/getting-started/agent-usage

Demonstrates creating an agent with string output using a configuration file and running a basic command. Ensure 'config.yml' is properly set up.

```python
from agentpool import Agent
from pydantic import BaseModel


    # Create agent with string output. It will have all resources and tools available from the config.
async with Agent(
        runtime="config.yml",
        model="openai:gpt-5",
        system_prompt="You are a helpful assistant."
    ) as basic_agent:
    await basic_agent.run("Open google for me.")  # Uses tool to open browser
```

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

### OpenAPI Tool Configuration Sources

Source: https://phil65.github.io/agentpool/configuration/toolsets/openapi

Examples of configuring the OpenAPI tool using either a remote URL or a local file path.

```yaml
tools:
  - type: openapi
    spec: https://petstore.swagger.io/v2/swagger.json
```

```yaml
tools:
  - type: openapi
    spec: ./specs/my-api.yaml
```

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

### Notifications Toolset Basic Usage (YAML)

Source: https://phil65.github.io/agentpool/configuration/toolsets/notifications

Example of how to configure the notifications toolset in YAML. Ensure to replace placeholders with your actual credentials.

```yaml
agents:
  notifier:
    tools:
      - type: notifications
        email:
          smtp_host: smtp.gmail.com
          smtp_port: 587
          username: ${EMAIL_USER}
          password: ${EMAIL_PASS}
```

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

### AG-UI Agent Configuration Examples

Source: https://phil65.github.io/agentpool/configuration/node-types/agui-agents

Demonstrates different ways to configure AG-UI agents, including remote assistants with API keys and managed agents with startup commands.

```yaml
agents:
  remote_assistant:
    type: agui
    endpoint: http://localhost:8000/agent/run
    timeout: 30.0
    headers:
      X-API-Key: ${API_KEY}
    tools:
      - import_path: mymodule.my_tool_function

  managed_agent:
    endpoint: http://localhost:8765/agent/run
    startup_command: "uv run ag-ui-server config.yml"
    startup_delay: 3.0
    tools:
      - import_path: package.tool_one
      - import_path: package.tool_two
```

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

### Complex Workflow Example

Source: https://phil65.github.io/agentpool/programmatic%20-usage/syntactic-sugar

An example showcasing a complex workflow combining pipeline, team, and forwarding operators.

```python
# Complex workflow
input_agent | (analyzer & researcher) | formatter >> storage
```

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

### Initialize Agent with Knowledge

Source: https://phil65.github.io/agentpool/core-concepts/knowledge

Demonstrates loading knowledge sources automatically within an async agent context.

```python
async with Agent(knowledge=knowledge) as agent:
    # Knowledge is now loaded and available in context
    await agent.run("Use the documentation...")
```

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

### Asynchronous History Processor Example

Source: https://phil65.github.io/agentpool/configuration/session

Example of an asynchronous Python function for processing messages, demonstrating the use of `async` and `await`.

```python
# Async processor
async def processor(messages: list[ModelMessage]) -> list[ModelMessage]:
    return await async_filter(messages)

```

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

### Complete Task Example

Source: https://phil65.github.io/agentpool/configuration/tasks

A comprehensive task configuration including description, prompt, output type, dependencies, knowledge sources, tools, and context requirements.

```yaml
jobs:
  deep_code_review:
    description: "Perform comprehensive code review"
    prompt: "Review the code changes focusing on:"
    required_output_type: "myapp.types:ReviewResult"
    required_dependency: "myapp.types:CodeContext"
    requires_vision: false

    # Required knowledge
    knowledge:
      paths: ["src/**/*.py"]
      resources:
        - type: "cli"
          command: "git diff main"
        - type: "repository"
          url: "https://github.com/user/repo"
      prompts:
        - "Consider these coding standards..."
        - "Focus on performance aspects..."

    # Required tools
    tools:
      - "analyze_complexity"
      - "check_style"
      - import_path: "myapp.tools:metrics"

    # Context requirements
    min_context_tokens: 2000

```

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

### Initialize MCP Servers

Source: https://phil65.github.io/agentpool/core-concepts/mcp

Use an async context manager to automatically connect and clean up MCP servers.

```python
async with Agent(mcp_servers=servers) as agent:
    # MCP servers are now connected
    # Tools are available
    await agent.run("Use MCP tools...")

# MCP servers are automatically cleaned up
```

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

### Inspect Configuration via CLI

Source: https://phil65.github.io/agentpool/configuration

Commands to verify loaded configurations, paths, and initialize new config files.

```bash
# Show which configs are found and loaded
agentpool config show

# Show standard config paths
agentpool config paths

# Create a starter config file
agentpool config init           # In current project
agentpool config init global    # In global config dir
```

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

### Serve ACP with uvx

Source: https://phil65.github.io/agentpool/servers/acp-server

Use uvx to serve the ACP with a specific Python version without installation. Alternatively, use the installed agentpool package.

```bash
# Using uvx (no installation required)
uvx --python 3.13 agentpool@latest serve-acp config.yml

# Or with installed package
agentpool serve-acp config.yml
```

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

### Install AgentPool with uvx

Source: https://phil65.github.io/agentpool/advanced/acp-integration

Use uvx to install and run the latest AgentPool version for one-off usage. This command shows the help for serving ACP.

```bash
uvx --python 3.13 agentpool@latest serve-acp --help

```

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

### Synchronous History Processor Example

Source: https://phil65.github.io/agentpool/configuration/session

Example of a simple synchronous Python function that takes a list of messages and returns a processed list, here keeping only the last 10.

```python
# Simple synchronous processor
def processor(messages: list[ModelMessage]) -> list[ModelMessage]:
    return messages[-10:]  # Keep only last 10 messages

```

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

### Create and Use ChatMessage Instances

Source: https://phil65.github.io/agentpool/core-concepts/messages

Shows how to create ChatMessage instances with string or structured content, access cost information, and format messages for display.

```python
# Simple text message
msg = ChatMessage[str](
    content="Hello!",
    role="user"
)

# Structured content
msg = ChatMessage[AnalysisResult](
    content=AnalysisResult(score=0.8, issues=[...]),
    role="assistant",
    name="analyzer"
)

# Access cost information
if msg.cost_info:
    print(f"Tokens: {msg.cost_info.token_usage['total']}")
    print(f"Cost: ${msg.cost_info.total_cost:.4f}")

# Format for display
print(msg.format("simple"))     # Basic format
print(msg.format("detailed"))   # With metadata
print(msg.format("markdown"))   # As markdown
```

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

### Configure OTEL Desktop Viewer

Source: https://phil65.github.io/agentpool/configuration/observability

Set up the OTEL desktop viewer provider using YAML configuration.

```yaml
- type: otel-desktop-viewer
  enabled: true  # Provider enabled state.
  service_name: null
  environment: null
  protocol: http/protobuf
```

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

### Initialize Agents with MCP Servers

Source: https://phil65.github.io/agentpool/advanced/mcp-servers

Demonstrates loading MCP-enabled agents from YAML and programmatically defining agents with multiple MCP servers.

```python
# Configure agent with MCP server
async with AgentPool("pool.yml") as pool:
    # MCP tools from YAML defined mcp servers are automatically available
    agent = self.get_agent("my_agent_from_yaml")
    result = await agent.run("Use MCP tool to process data")

    # Multiple servers
    async with Agent(
        name="agent_name",
        model="...",
        mcp_servers=[
            "uvx server1",
            "uvx server2 --debug"
        ]
    )) as agent:
        # Tools from both servers available
        result = await agent.run("Use tools from multiple servers")
```

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

### Background Execution

Source: https://phil65.github.io/agentpool/programmatic%20-usage/run-interface

Methods for starting and monitoring background tasks.

```APIDOC
## run_in_background()

### Description
Start execution in background and monitor progress.

### Parameters
- **prompt** (string) - Required - The input prompt.
- **max_count** (int | None) - Optional - Max number of runs.
- **interval** (float) - Optional - Seconds between runs.
- **block** (bool) - Optional - Whether to block until completion.
```

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

### GET /

Source: https://phil65.github.io/agentpool/servers/agui-server

Retrieves a list of all agents currently available in the pool.

```APIDOC
## GET /

### Description
Returns a list of all available agents configured in the server.

### Method
GET

### Endpoint
/

### Response
#### Success Response (200)
- **agents** (array) - List of agent objects containing name, route, and model.
- **count** (integer) - Total number of agents.

#### Response Example
{
  "agents": [
    {
      "name": "assistant",
      "route": "/assistant",
      "model": "openai:gpt-4"
    }
  ],
  "count": 1
}
```

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

### Streaming Chat Completions

Source: https://phil65.github.io/agentpool/servers/openai-api-server

Example of server-sent events when streaming is enabled.

```text
data: {"id":"msg_123","choices":[{"delta":{"content":"Hello"}}]}
data: {"id":"msg_123","choices":[{"delta":{"content":"!"}}]}
data: [DONE]
```

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

### Configure Multiple Storage Providers

Source: https://phil65.github.io/agentpool/core-concepts/storage

Demonstrates how to define multiple active storage providers simultaneously for different logging purposes.

```yaml
storage:
  providers:
    - type: sql               # Main history storage
      url: sqlite:///history.db

    - type: text_file         # Additional logging
      path: logs/output.txt
```

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

### Multi-Agent Configuration

Source: https://phil65.github.io/agentpool/servers/agui-server

Example configuration for exposing multiple specialized agents.

```yaml
agents:
  writer:
    model: openai:gpt-4
    system_prompt: "You are a creative writer."

  reviewer:
    model: anthropic:claude-sonnet-4-20250514
    system_prompt: "You review and improve text."

  translator:
    model: openai:gpt-4
    system_prompt: "You translate text between languages."
```

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

### Configure Code Toolset with Filters and Namespace

Source: https://phil65.github.io/agentpool/configuration/toolsets/code

Example configuration for the code toolset, demonstrating how to filter specific tools and set a namespace prefix for tool names.

```yaml
toolsets:
- type: code
  tools: null  # Optional tool filter to enable/disable specific tools.
  environment: null  # Optional execution environment. If None, falls back to agent's env at runtime.
  namespace: null  # Optional namespace prefix for tool names

```

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

### Process Management Toolset

Source: https://phil65.github.io/agentpool/core-concepts/toolsets

Allows starting and managing background processes.

```APIDOC
## Process Management (`process_management`)

### Description
Start and manage background processes.

### Tools Provided
- `start_process`: Start background processes.
- `get_process_output`: Check process output.
- `wait_for_process`: Wait for process completion.
- `kill_process`: Terminate processes.
- `release_process`: Clean up process resources.
- `list_processes`: Show active processes.

### Configuration Example
```yaml
agents:
  build_manager:
    tools:
      - type: process_management
```
```

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

### Notifications Toolset Configuration

Source: https://phil65.github.io/agentpool/configuration/toolsets/notifications

Configuration example for the Notifications Toolset in YAML format.

```APIDOC
## Notifications Toolset Configuration

### Description
Configuration for the Apprise-based notifications toolset, allowing setup of various notification channels.

### Method
N/A (Configuration)

### Endpoint
N/A (Configuration)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```yaml
toolsets:
- type: notifications
  channels: {}
  namespace: null
```

### Response
N/A (Configuration)

#### Success Response (200)
N/A (Configuration)

#### Response Example
N/A (Configuration)
```

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

### Agent Configuration with Tools

Source: https://phil65.github.io/agentpool/servers/opencode-server

Example agent configuration specifying its type, display name, and a list of available tools including file access, process management, code execution, and search.

```yaml
# config.yml
agents:
  assistant:
    type: claude_code
    display_name: "AI Assistant"
    tools:
      - type: file_access
        edit_tool: batch
      - type: process_management
      - type: code
      - type: search

```

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

### AgentPool CLI Initialization and Management

Source: https://phil65.github.io/agentpool/getting-started/quickstart

Manage AgentPool configurations using the CLI. Commands include initializing a starter configuration, adding to existing configurations, and starting a chat session.

```bash
# Create starter configuration
agentpool init agents.yml

# Add to your configurations
agentpool add agents.yml

# Start chatting
agentpool chat assistant

```

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

### Define GitHub repository access

Source: https://phil65.github.io/agentpool/configuration/toolsets/file-access

Example configuration for accessing a remote GitHub repository.

```yaml
tools:
  - type: file_access
    fs:
      type: github
      org: fastapi
      repo: fastapi
      cached: true
```

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

### Implement Agent Configuration Inheritance

Source: https://phil65.github.io/agentpool/configuration/node-types/agent

Demonstrates how to define a base agent configuration and extend it for specialized use cases.

```yaml
agents:
  base_agent:
    model: "openai:gpt-4o"
    retries: 2
    tools:
      - type: "resource_access"

  specialized_agent:
    model: "openai:gpt-4o"
    description: "Specialized version"
    system_prompt: "You are a specialized agent..."
```

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

### Chat Completions Endpoint

Source: https://phil65.github.io/agentpool/servers/openai-api-server

Request format and example response for standard chat completions.

```text
POST /v1/chat/completions
```

```json
{
  "model": "assistant",
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "stream": false
}
```

```json
{
  "id": "msg_123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "assistant",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 15,
    "total_tokens": 25
  }
}
```

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

### JavaScript Client Request

Source: https://phil65.github.io/agentpool/servers/agui-server

Example of sending a request to an agent using the fetch API.

```javascript
// JavaScript client example
const response = await fetch('http://localhost:8002/assistant', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    // AG-UI request format
    messages: [{ role: 'user', content: 'Hello!' }]
  })
});
```

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

### Agent and Team Setup for Execution

Source: https://phil65.github.io/agentpool/programmatic%20-usage/talk

Initialize Agent objects and group them into a team for coordinated operations. This sets up the agents for subsequent connection and communication.

```python
# Create agents
analyzer = Agent(name="analyzer")
planner = Agent(name="planner")
executor = Agent(name="executor")

# Create team
planning_team = planner & executor
```

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

### start_process

Source: https://phil65.github.io/agentpool/configuration/toolsets/execution

Starts a command in the background and returns a process ID, suitable for long-running tasks.

```APIDOC
## start_process

### Description
Start a command in the background and return process ID. This is the preferred tool for long-running processes that should run in the background.

### Parameters
- **command** (string) - Required - Command to execute
- **args** (array) - Optional - Command arguments
- **cwd** (string) - Optional - Working directory
- **env** (object) - Optional - Environment variables (added to current env)
- **output_limit** (integer) - Optional - Maximum bytes of output to retain
```
Tokens:
Raw