​
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

​
agents
array
required

List of agents available in the workflow.

​
agents[].id
string
required

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

​
agents[].use
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[].import
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.

​
agents[].config
object

Provider-specific configuration options.

​
agents[].with
object

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

​
agents[].tools
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 }}"
​
agents[].env
object

Environment variables specific to this agent instance.

​
agents[].memory
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

​
agents[].actions
array

List of actions the agent can perform.

​
Output References

​
agents.agent_id.output
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"
    }
  }
}
​
agents.agent_id.error
object

Error information if agent execution fails. Example:

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