Usage

Structure

Agents in Compozy follow a consistent structure:

agents:
  - id: string           # Unique identifier for the agent
    name: string         # Optional human-readable name
    type: string         # Agent type (basic, custom, etc.)
    use: string|object   # Agent implementation reference
    import: string       # Path to external agent definition
    config:             # Agent configuration
      provider: string  # AI provider identifier
      model: string    # Model identifier
      url: string      # API URL
      version: string  # Optional model version
      api_key: string
      organization: string
      temperature: number
      max_tokens: number
      top_p: number
      frequency_penalty: number
      presence_penalty: number
    schema:             # Optional schema definition
      input: object    # Input schema for agent parameters
    with: object       # Agent-specific configuration
    env: object        # Agent-specific environment variables
    tools: array       # Available tools
    memory: object     # Memory configuration

    # Custom agent specific
    actions: array     # List of actions
      - id: string    # Action identifier
        instructions: string # Action instructions
        config: object # Custom action configuration
        messages: array # List of messages
          - role: string # Message role
            content: string # Message content
        output: object # Action output schema

Basic Usage

Agents can be used in three main ways:

agents:
  - id: content_moderator
    type: basic
    use: compozy/agents:content-moderator@1.0.0

agents:
  - id: market_analyst
    type: basic
    use:
      repo: compozy/agents
      package: market-analyst
      version: 0.2.1

agents:
  - id: custom_agent
    type: custom
    config:
      provider: openrouter
      model: anthropic/claude-3-sonnet
      api_key: "{{ env.OPENROUTER_KEY }}"
      url: https://openrouter.ai/api/v1
      temperature: 0.3
    actions:
      - id: analyze
        instructions: "Analyze this content"
        messages:
          - role: user
            content: "Please analyze this content: {{ trigger.content }}"
        output:
          type: object
          properties:
            analysis: string
            confidence: number

Custom Settings

Each agent’s configuration can be overridden regardless of whether it’s an external package or local import. Use config to override provider settings and with to override agent-specific parameters:

agents:
  - id: content_moderator
    use: compozy/agents:content-moderator
    # Override provider configuration
    config:
      model: anthropic/claude-3-sonnet
      temperature: 0.4
      max_tokens: 2000
    # Override agent parameters
    with:
      language: en
      threshold: 0.7

agents:
  - id: support_agent
    import: ./agents/support.yaml
    config:                           # Override imported configuration
      model: gpt-4                     # Replace model from import
      temperature: 0.7                 # Override temperature setting
    with:
      language: es                     # Change default language
      response_type: detailed          # Customize response format

Tools Integration

Agents can be equipped with tools to extend their capabilities and interact with external services. Tools are defined at the agent level:

agents:
  - id: research_assistant
    config:
      provider: openai
      model: gpt-4o-mini
    tools:
      - id: web_search
        use: compozy/tools:web-search@1.0.0
      - id: pdf_reader
        use: compozy/tools:pdf-reader@1.0.0

agents:
  - id: data_processor
    config:
      provider: openrouter
      model: openai/gpt-4o-mini
    tools:
      - id: database
        use: compozy/tools:database@1.0.0
        config:
          connection_string: "{{ env.DB_CONNECTION }}"
          max_results: 100
      - id: api_client
        use: compozy/tools:rest-client@1.0.0
        with:
          base_url: https://api.example.com
          headers:
            Authorization: "{{ env.API_KEY }}"

Best Practices

Agent Design

Keep actions focused and single-purpose
Write clear instructions
Define comprehensive output schemas

Configuration

Start with conservative temperature values
Adjust max_tokens based on expected responses
Use appropriate model versions

Tool Integration

Only include necessary tools
Configure tool timeouts and limits
Test tool interactions thoroughly

Memory Management

Configure memory when needed
Clear state appropriately
Consider persistence requirements

Using Agents in Tasks

Agents can be executed within tasks using the agent task type:

tasks:
  - id: analyze_content
    type: agent
    use: compozy/agents:content-moderator@1.0.0
    with:
      content: "{{ trigger.content }}"

tasks:
  - id: market_analysis
    type: agent
    use: compozy/agents:market-analyst@1.0.0
    config:
      temperature: 0.4
      max_tokens: 2000
    with:
      symbols: "{{ trigger.symbols }}"
      timeframe: "1d"

tasks:
  - id: research_task
    type: agent
    use: compozy/agents:researcher@1.0.0
    actions:
      - id: search
        with:
          query: "{{ trigger.topic }}"
      - id: analyze
        with:
          content: "{{ actions.search.output }}"
      - id: summarize
        with:
          analysis: "{{ actions.analyze.output }}"

When using agents in tasks:

The agent’s output is available as the task output
Task error handling and retry mechanisms apply to the agent execution
Agent configuration can be overridden at the task level
Multiple agent actions can be executed sequentially

Memory Integration

Agents can be configured to use memory defined at the workflow level:

# Define memory in workflow
memory:
  support_memory:
    id: support_memory
    vector:
      use: compozy/vector:pg-vector
      dimensions: 1536

  chat_memory:
    id: chat_memory
    storage:
      use: compozy/storage:postgres
    vector:
      use: compozy/vector:pinecone
      dimensions: 1536
    options:
      lastMessages: 10
      semanticRecall:
        enabled: true

# Reference memory in agents
agents:
  - id: support_agent
    use: compozy/agents:support
    memory: support_memory    # Reference to workflow memory

  - id: chat_agent
    use: compozy/agents:chat
    memory: chat_memory      # Reference to workflow memory

tasks:
  - id: support_task
    type: agent
    use: support_agent
    with:
      context: "{{ memory.support_memory.current_thread }}"
      history: "{{ memory.support_memory.last_messages }}"
      relevant: "{{ memory.support_memory.semantic_search }}"

References

Agent Types

Learn about different types of agents

Tools

Available tools and integration

Memory

Memory overview

API Reference

Complete agent configuration API

Getting Started

Core Concepts

Structure

Basic Usage

Custom Settings

Tools Integration

Best Practices

Using Agents in Tasks

Memory Integration

References

Agent Types

Tools

Memory

API Reference

​Structure

​Basic Usage

​Custom Settings

​Tools Integration

​Best Practices

​Using Agents in Tasks

​Memory Integration

​References

Agent Types

Tools

Memory

API Reference

Structure

Basic Usage

Custom Settings

Tools Integration

Best Practices

Using Agents in Tasks

Memory Integration

References