Examples¶

These examples demonstrate how to create and use agents through YAML configuration files.

Simple Text Agent¶

Create a simple agent that opens websites in your browser:

agents.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
agents:
  url_opener:
    type: native
    model: openai:gpt-5-mini
    system_prompt: |
      You help users open websites. Use the open_url tool to open URLs.
      When given a website name, find its URL in the bookmarks resource.
      Always confirm what you're about to open.
    toolsets:
      - type: import_tools
        tools:
          - import_path: webbrowser.open
            name: open_url
            description: "Open URL in default browser"

Use the agent via an ACP client of your choice.

Or programmatically:

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)

Structured Responses¶

Define structured outputs for consistent response formats:

agents.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
responses:
  CodeReview:
    response_schema:
      type: inline
      description: "Code review result"
      fields:
        issues:
          type: list[str]
          description: "Found issues"
        score:
          type: int
          description: "Quality score (0-100)"

agents:
  code_reviewer:
    type: native
    model: openai:gpt-5
    output_type: CodeReview # Use structured response
    system_prompt: "You review Python code and provide structured feedback."

Tool Usage¶

Create an agent that interacts with the file system:

agents.yml

# yaml-language-server: $schema=https://raw.githubusercontent.com/phil65/agentpool/refs/heads/main/schema/config-schema.json
agents:
  file_manager:
    type: native
    model: openai:gpt-5
    system_prompt: "You help users manage their files and directories."
    toolsets:
      - type: import_tools
        tools:
          - import_path: os.listdir
            name: list_files
            description: "List directory contents"
          - import_path: builtins.open
            name: read_file
            description: "Read file contents"
          - import_path: builtins.open
            name: write_file
            description: "Write file contents"
          - import_path: os.remove
            name: delete_file
            description: "Delete a file"
          - import_path: custom_tools.modify_file
            name: modify_file
            description: "Modify file contents"

Use the file manager:

from agentpool import Agent

async with AgentPool("agents.yml" as pool:
    agent = pool.get_agent("file_manager")
    # List files
    result = await agent.run("What files are in the current directory?")
    print(result.data)

    # Read a file
    result = await agent.run("Show me the contents of config.py")
    print(result.data)