Agent Tools

How Tools Work with Agents

When an agent has tools available:

Tool Discovery: The agent receives descriptions of available tools
Decision Making: Based on the task, the agent decides if and which tools to use
Tool Invocation: The agent calls tools with appropriate parameters
Result Integration: Tool outputs are incorporated into the agent's response

Tool Configuration

Understanding Tool Patterns

Compozy uses three distinct patterns for working with tools:

Tool Definition
Define tools in separate files with resource: tool. This creates reusable tool components.
Tool Reference in Agents
Reference tools in agent configurations using $ref: local::tools.#(id=="tool-id").
Tool Usage in Tasks
Use tools in task configurations with $use: tool(local::tools.#(id="tool-id")).

Basic Tool Assignment

Assign tools to agents in the agent configuration:

agents:
  - id: data-processor
    config:
      provider: openai
      model: gpt-4-turbo-preview
    instructions: |
      You are a data processing assistant.
      Use available tools to fetch, process, and analyze data.
    tools:
      - $ref: local::tools.#(id=="fetch-data")
      - $ref: local::tools.#(id=="transform-data")
      - $ref: local::tools.#(id=="save-results")

Tool References

Tools must be defined separately and then referenced in agent configurations:

Tools cannot be defined inline within agent configurations. They must be defined in separate files with resource: tool and then referenced using $ref patterns.

# Reference tools defined in the same workflow file
tools:
  - $ref: local::tools.#(id=="weather_tool")
  - $ref: local::tools.#(id=="calculator")

Tool Usage Patterns

Automatic Tool Selection

By default, agents automatically decide when to use tools:

config:
  provider: openai
  model: gpt-4-turbo-preview
  tool_choice: auto  # Default behavior

actions:
  - id: process-request
    prompt: |
      Process the user's request using available tools as needed.
      Request: {{.input.request}}

Forced Tool Usage

Force the agent to use a specific tool:

config:
  tool_choice: "weather_tool"  # Force specific tool

# Or disable tool usage
config:
  tool_choice: none

MCP Tools

Agents can use tools provided by MCP (Model Context Protocol) servers. MCP servers must be configured in the mcps field, separate from standard tools:

MCP servers are configured in the mcps field, not in the tools array. Standard tools and MCP tools are managed separately.

agents:
  - id: system-admin
    instructions: |
      You are a system administrator with access to server tools.
    # Standard tools (defined with resource: tool)
    tools:
      - $ref: local::tools.#(id=="log-analyzer")
    # MCP servers (separate configuration)
    mcps:
      - id: filesystem
        transport: stdio
        command: npx
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/"]

    actions:
      - id: check-logs
        prompt: |
          Use the MCP filesystem tools to:
          1. List files in /var/log
          2. Read the most recent error logs
          3. Summarize any critical issues found

On this page