> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Learn about the parameters and definitions of agents in Compozy.

## JSON Schema

```json https://compozy.dev/schemas/agents.json [expandable] theme={"dark"}
{
  "type": "object",
  "required": ["agents"],
  "properties": {
    "agents": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["id", "use"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier for the agent"
          },
          "use": {
            "oneOf": [
              { "type": "string" },
              {
                "type": "object",
                "required": ["repo", "package"],
                "properties": {
                  "repo": { "type": "string" },
                  "package": { "type": "string" },
                  "version": { "type": "string" }
                }
              }
            ],
            "description": "Agent implementation reference"
          },
          "import": {
            "type": "string",
            "description": "Path to external YAML file containing agent definition"
          },
          "config": {
            "type": "object",
            "required": ["provider", "model"],
            "properties": {
              "provider": { "type": "string" },
              "model": { "type": "string" },
              "api_key": { "type": "string" },
              "url": { "type": "string" },
              "temperature": { "type": "number", "minimum": 0, "maximum": 1 },
              "max_tokens": { "type": "number" },
              "top_p": { "type": "number" },
              "frequency_penalty": { "type": "number" },
              "presence_penalty": { "type": "number" }
            }
          },
          "with": {
            "type": "object",
            "description": "Agent-specific configuration parameters"
          },
          "tools": {
            "type": "array",
            "items": {
              "$ref": "https://compozy.ai/schemas/tools.json"
            },
            "description": "List of tools available to the agent"
          },
          "env": {
            "type": "object",
            "description": "Environment variables for this agent"
          },
          "memory": {
            "$ref": "https://compozy.ai/schemas/memory.json",
            "description": "Memory configuration for the agent"
          },
          "actions": {
            "type": "array",
            "items": {
              "type": "object",
              "required": ["id", "instructions", "output"],
              "properties": {
                "id": { "type": "string" },
                "instructions": { "type": "string" },
                "messages": { "type": "array" },
                "output": { "type": "object" },
                "config": { "type": "object" }
              }
            }
          }
        }
      }
    }
  }
}
```

## Parameters

<ParamField path="agents" type="array" required>
  List of agents available in the workflow.
</ParamField>

<ParamField path="agents[].id" type="string" required>
  Unique identifier for the agent. Must be unique across all agents in your
  workflow.
</ParamField>

<ParamField path="agents[].use" type="string | object" required>
  Agent implementation reference. Can be specified in three formats:

  * `"repo/package"` (e.g., `"compozy/agents:content-moderator"`)
  * `"repo:package@version"` (e.g., `"compozy/agents:content-moderator@1.0.0"`)
  * Object with `repo` and `package` fields

  <CodeGroup>
    ```yaml Shorthand theme={"dark"}
    agents:
      - id: content_moderator
        use: compozy/agents:content-moderator
    ```

    ```yaml Version theme={"dark"}
    agents:
      - id: market_analyst
        use: compozy/agents:market-analyst@1.0.0
    ```

    ```yaml Detailed theme={"dark"}
    agents:
      - id: support_agent
        use:
          repo: compozy/agents
          package: support-assistant
          version: 2.1.0
    ```
  </CodeGroup>
</ParamField>

<ParamField path="agents[].import" type="string">
  Path to an external YAML file containing the agent definition. When specified,
  the agent configuration will be loaded from this file instead of being defined inline.
</ParamField>

<ParamField path="agents[].config" type="object">
  Provider-specific configuration options.

  <Expandable title="Properties">
    <ParamField path="provider" type="string" required>
      AI provider identifier (e.g., "openrouter", "anthropic")
    </ParamField>

    <ParamField path="model" type="string" required>
      Model identifier (e.g., "anthropic/claude-3-sonnet")
    </ParamField>

    <ParamField path="api_key" type="string">
      API key for the provider
    </ParamField>

    <ParamField path="url" type="string">
      Custom API endpoint URL
    </ParamField>

    <ParamField path="temperature" type="number">
      Model temperature (0.0 to 1.0)
    </ParamField>

    <ParamField path="max_tokens" type="number">
      Maximum tokens in the response
    </ParamField>

    <ParamField path="top_p" type="number">
      Nucleus sampling parameter
    </ParamField>

    <ParamField path="frequency_penalty" type="number">
      Frequency penalty for token selection
    </ParamField>

    <ParamField path="presence_penalty" type="number">
      Presence penalty for token selection
    </ParamField>
  </Expandable>
</ParamField>

<ParamField path="agents[].with" type="object">
  Agent-specific configuration parameters defined by the agent's schema.
</ParamField>

<ParamField path="agents[].tools" type="array">
  List of tools available to the agent. See the [Tools API Reference](/core/tools/api) for detailed configuration options.

  ```yaml Example theme={"dark"}
  tools:
    - id: web_search
      config:
        api_key: "{{ env.SEARCH_API_KEY }}"
  ```
</ParamField>

<ParamField path="agents[].env" type="object">
  Environment variables specific to this agent instance.
</ParamField>

<ParamField path="agents[].memory" type="object">
  Memory configuration for the agent. See the [Memory API Reference](/core/memory/api) for detailed configuration options.

  ```yaml Example theme={"dark"}
  memory:
    id: agent_memory
    vector:
      use: compozy/vector:pg-vector
      dimensions: 1536
  ```
</ParamField>

## Action Parameters

<ParamField path="agents[].actions" type="array">
  List of actions the agent can perform.

  <Expandable title="Properties">
    <ParamField path="id" type="string" required>
      Unique identifier for the action
    </ParamField>

    <ParamField path="instructions" type="string" required>
      Instructions for the action
    </ParamField>

    <ParamField path="messages" type="array">
      Predefined messages for the action
    </ParamField>

    <ParamField path="output" type="object" required>
      JSON Schema definition for the action's output format
    </ParamField>

    <ParamField path="config" type="object">
      Action-specific configuration
    </ParamField>
  </Expandable>
</ParamField>

## Output References

<ResponseField name="agents.agent_id.output" type="any">
  Agent's output data, accessible via `{{ agents.agent_id.output }}`. Example:

  ```json theme={"dark"}
  {
    "data": {
      "analysis": {
        "sentiment": "positive",
        "confidence": 0.92,
        "key_points": [
          "excellent performance",
          "strong growth"
        ]
      },
      "metadata": {
        "model": "anthropic/claude-3-sonnet",
        "timestamp": "2024-03-20T10:30:00Z"
      }
    }
  }
  ```
</ResponseField>

<ResponseField name="agents.agent_id.error" type="object">
  Error information if agent execution fails. Example:

  ```json theme={"dark"}
  {
    "code": "EXECUTION_ERROR",
    "message": "Failed to execute agent",
    "details": {
      "type": "validation_error",
      "reason": "Invalid input parameters"
    }
  }
  ```
</ResponseField>