​
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

​
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

​
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

​
Best Practices

1

Agent Design

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

Configuration

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

Tool Integration

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

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 }}"

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

​
References

Agent Types

Learn about different types of agents

Tools

Available tools and integration

Memory

Memory overview

API Reference

Complete agent configuration API