API Reference

JSON Schema

https://compozy.dev/schemas/agents.json

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

array

required

List of agents available in the workflow.

string

required

Unique identifier for the agent. Must be unique across all agents in your workflow.

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

agents:
  - id: content_moderator
    use: compozy/agents:content-moderator

agents:
  - id: market_analyst
    use: compozy/agents:market-analyst@1.0.0

agents:
  - id: support_agent
    use:
      repo: compozy/agents
      package: support-assistant
      version: 2.1.0

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.

object

Provider-specific configuration options.

Show Properties

string

required

AI provider identifier (e.g., “openrouter”, “anthropic”)

string

required

Model identifier (e.g., “anthropic/claude-3-sonnet”)

string

API key for the provider

string

Custom API endpoint URL

number

Model temperature (0.0 to 1.0)

number

Maximum tokens in the response

number

Nucleus sampling parameter

number

Frequency penalty for token selection

number

Presence penalty for token selection

object

Agent-specific configuration parameters defined by the agent’s schema.

array

List of tools available to the agent. See the Tools API Reference for detailed configuration options.

Example

tools:
  - id: web_search
    config:
      api_key: "{{ env.SEARCH_API_KEY }}"

object

Environment variables specific to this agent instance.

object

Memory configuration for the agent. See the Memory API Reference for detailed configuration options.

Example

memory:
  id: agent_memory
  vector:
    use: compozy/vector:pg-vector
    dimensions: 1536

Action Parameters

array

List of actions the agent can perform.

Show Properties

string

required

Unique identifier for the action

string

required

Instructions for the action

array

Predefined messages for the action

object

required

JSON Schema definition for the action’s output format

object

Action-specific configuration

Output References

any

Agent’s output data, accessible via {{ agents.agent_id.output }}. Example:

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

object

Error information if agent execution fails. Example:

{
  "code": "EXECUTION_ERROR",
  "message": "Failed to execute agent",
  "details": {
    "type": "validation_error",
    "reason": "Invalid input parameters"
  }
}

Getting Started

Core Concepts

JSON Schema

Parameters

Action Parameters

Output References

​JSON Schema

​Parameters

​Action Parameters

​Output References

JSON Schema

Parameters

Action Parameters

Output References