Compozy Symbol
ALPHA
DocsInstallGetting StartedFeaturesPricing
CoreCLI ReferenceSchema DefinitionAPI Reference

Agents

Agent management operations

Agent management operations

List agents

List agents with cursor pagination. Optionally filter by workflow usage.

GET
/agents

Query Parameters

project?string

Project override

workflow_id?string

Return only agents referenced by the given workflow

limit?integer

Page size (max 500)

cursor?string

Opaque pagination cursor

q?string

Filter by agent ID prefix

Response Body

curl -X GET "https://loading/api/v0/agents?project=string&workflow_id=string&limit=0&cursor=string&q=string"
{
  "data": {
    "agents": [
      {
        "actions": [
          {
            "attachments": [
              null
            ],
            "id": "string",
            "input": {
              "property1": null,
              "property2": null
            },
            "output": {
              "property1": null,
              "property2": null
            },
            "prompt": "string",
            "with": {
              "property1": null,
              "property2": null
            }
          }
        ],
        "attachments": [
          null
        ],
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "etag": "abc123",
        "id": "string",
        "instructions": "string",
        "max_iterations": 0,
        "mcps": [
          {
            "args": [
              "string"
            ],
            "command": "string",
            "env": {
              "property1": "string",
              "property2": "string"
            },
            "headers": {
              "property1": "string",
              "property2": "string"
            },
            "id": "string",
            "max_sessions": 0,
            "proto": "string",
            "resource": "string",
            "start_timeout": -9223372036854776000,
            "transport": "stdio",
            "url": "string"
          }
        ],
        "memory": [
          {
            "id": "string",
            "key": "string",
            "mode": "read-write"
          }
        ],
        "model": {
          "config": {
            "api_key": "string",
            "api_url": "string",
            "default": true,
            "max_tool_iterations": 0,
            "model": "string",
            "organization": "string",
            "params": {
              "max_length": 0,
              "max_tokens": 0,
              "min_length": 0,
              "repetition_penalty": 0,
              "seed": 0,
              "stop_words": [
                "string"
              ],
              "temperature": 0,
              "top_k": 0,
              "top_p": 0
            },
            "provider": "openai"
          },
          "ref": "string"
        },
        "resource": "string",
        "tools": [
          {
            "config": {
              "property1": null,
              "property2": null
            },
            "cwd": {
              "path": "string"
            },
            "description": "string",
            "env": {
              "property1": "string",
              "property2": "string"
            },
            "id": "string",
            "input": {
              "property1": null,
              "property2": null
            },
            "output": {
              "property1": null,
              "property2": null
            },
            "resource": "string",
            "timeout": "string",
            "with": {
              "property1": null,
              "property2": null
            }
          }
        ],
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "page": {
      "limit": 50,
      "next_cursor": "v2:after:tool-001",
      "prev_cursor": "v2:before:tool-000",
      "total": 2
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Export agents

Write agent YAML files for the active project.

POST
/agents/export

Authorization

Response Body

curl -X POST "https://loading/api/v0/agents/export"
{
  "data": {
    "property1": 0,
    "property2": 0
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}

Import agents

Read agent YAML files from the project directory.

POST
/agents/import

Authorization

Query Parameters

strategy?string

seed_only|overwrite_conflicts

Value in"seed_only" | "overwrite_conflicts"

Response Body

curl -X POST "https://loading/api/v0/agents/import?strategy=seed_only"
{
  "data": {},
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}

Get agent

Retrieve an agent configuration by ID.

GET
/agents/{agent_id}

Path Parameters

agent_idstring

Agent ID

Query Parameters

project?string

Project override

Response Body

curl -X GET "https://loading/api/v0/agents/string?project=string"
{
  "data": {
    "actions": [
      {
        "attachments": [
          null
        ],
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "prompt": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "attachments": [
      null
    ],
    "env": {
      "property1": "string",
      "property2": "string"
    },
    "id": "string",
    "instructions": "string",
    "max_iterations": 0,
    "mcps": [
      {
        "args": [
          "string"
        ],
        "command": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "max_sessions": 0,
        "proto": "string",
        "resource": "string",
        "start_timeout": -9223372036854776000,
        "transport": "stdio",
        "url": "string"
      }
    ],
    "memory": [
      {
        "id": "string",
        "key": "string",
        "mode": "read-write"
      }
    ],
    "model": {
      "config": {
        "api_key": "string",
        "api_url": "string",
        "default": true,
        "max_tool_iterations": 0,
        "model": "string",
        "organization": "string",
        "params": {
          "max_length": 0,
          "max_tokens": 0,
          "min_length": 0,
          "repetition_penalty": 0,
          "seed": 0,
          "stop_words": [
            "string"
          ],
          "temperature": 0,
          "top_k": 0,
          "top_p": 0
        },
        "provider": "openai"
      },
      "ref": "string"
    },
    "resource": "string",
    "tools": [
      {
        "config": {
          "property1": null,
          "property2": null
        },
        "cwd": {
          "path": "string"
        },
        "description": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "resource": "string",
        "timeout": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "with": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Delete agent

Delete an agent configuration. Returns conflict when referenced.

DELETE
/agents/{agent_id}

Path Parameters

agent_idstring

Agent ID

Query Parameters

project?string

Project override

Response Body

curl -X DELETE "https://loading/api/v0/agents/string?project=string"
"string"
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Create or update agent

Create an agent when absent or update an existing one using strong ETag concurrency.

PUT
/agents/{agent_id}

Path Parameters

agent_idstring

Agent ID

Query Parameters

project?string

Project override

Header Parameters

If-Match?string

Strong ETag for optimistic concurrency

Request Body

Agent configuration payload

Empty Object

Response Body

curl -X PUT "https://loading/api/v0/agents/string?project=string" \
  -H "If-Match: string" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "data": {
    "actions": [
      {
        "attachments": [
          null
        ],
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "prompt": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "attachments": [
      null
    ],
    "env": {
      "property1": "string",
      "property2": "string"
    },
    "id": "string",
    "instructions": "string",
    "max_iterations": 0,
    "mcps": [
      {
        "args": [
          "string"
        ],
        "command": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "max_sessions": 0,
        "proto": "string",
        "resource": "string",
        "start_timeout": -9223372036854776000,
        "transport": "stdio",
        "url": "string"
      }
    ],
    "memory": [
      {
        "id": "string",
        "key": "string",
        "mode": "read-write"
      }
    ],
    "model": {
      "config": {
        "api_key": "string",
        "api_url": "string",
        "default": true,
        "max_tool_iterations": 0,
        "model": "string",
        "organization": "string",
        "params": {
          "max_length": 0,
          "max_tokens": 0,
          "min_length": 0,
          "repetition_penalty": 0,
          "seed": 0,
          "stop_words": [
            "string"
          ],
          "temperature": 0,
          "top_k": 0,
          "top_p": 0
        },
        "provider": "openai"
      },
      "ref": "string"
    },
    "resource": "string",
    "tools": [
      {
        "config": {
          "property1": null,
          "property2": null
        },
        "cwd": {
          "path": "string"
        },
        "description": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "resource": "string",
        "timeout": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "with": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": {
    "actions": [
      {
        "attachments": [
          null
        ],
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "prompt": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "attachments": [
      null
    ],
    "env": {
      "property1": "string",
      "property2": "string"
    },
    "id": "string",
    "instructions": "string",
    "max_iterations": 0,
    "mcps": [
      {
        "args": [
          "string"
        ],
        "command": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "max_sessions": 0,
        "proto": "string",
        "resource": "string",
        "start_timeout": -9223372036854776000,
        "transport": "stdio",
        "url": "string"
      }
    ],
    "memory": [
      {
        "id": "string",
        "key": "string",
        "mode": "read-write"
      }
    ],
    "model": {
      "config": {
        "api_key": "string",
        "api_url": "string",
        "default": true,
        "max_tool_iterations": 0,
        "model": "string",
        "organization": "string",
        "params": {
          "max_length": 0,
          "max_tokens": 0,
          "min_length": 0,
          "repetition_penalty": 0,
          "seed": 0,
          "stop_words": [
            "string"
          ],
          "temperature": 0,
          "top_k": 0,
          "top_p": 0
        },
        "provider": "openai"
      },
      "ref": "string"
    },
    "resource": "string",
    "tools": [
      {
        "config": {
          "property1": null,
          "property2": null
        },
        "cwd": {
          "path": "string"
        },
        "description": "string",
        "env": {
          "property1": "string",
          "property2": "string"
        },
        "id": "string",
        "input": {
          "property1": null,
          "property2": null
        },
        "output": {
          "property1": null,
          "property2": null
        },
        "resource": "string",
        "timeout": "string",
        "with": {
          "property1": null,
          "property2": null
        }
      }
    ],
    "with": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}
{
  "code": "invalid_cursor",
  "detail": "Invalid cursor parameter",
  "instance": "/api/v0/workflows",
  "status": 400,
  "title": "Bad Request",
  "type": "about:blank"
}

Execute agent synchronously

Execute an agent and wait for the output in the same HTTP response.

POST
/agents/{agent_id}/executions

Path Parameters

agent_idstring

Agent ID

Header Parameters

X-Idempotency-Key?string

Optional idempotency key to prevent duplicate execution

Request Body

Execution request

action?string

Action selects a predefined agent action to execute.

prompt?string

Prompt supplies an ad-hoc prompt for the agent when no action is provided.

timeout?integer

Timeout in seconds for synchronous execution.

with?core.Input

With passes structured input parameters to the agent execution.

Empty Object

Response Body

curl -X POST "https://loading/api/v0/agents/string/executions" \
  -H "X-Idempotency-Key: string" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "data": {
    "exec_id": "2Z4PVTL6K27XVT4A3NPKMDD5BG",
    "output": {
      "property1": null,
      "property2": null
    }
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}

Start agent execution asynchronously

Start an asynchronous agent execution and return a polling handle.

POST
/agents/{agent_id}/executions/async

Path Parameters

agent_idstring

Agent ID

Header Parameters

X-Correlation-ID?string

Optional correlation ID for request tracing

Request Body

Execution request

action?string

Action selects a predefined agent action to execute.

prompt?string

Prompt supplies an ad-hoc prompt for the agent when no action is provided.

timeout?integer

Timeout in seconds for synchronous execution.

with?core.Input

With passes structured input parameters to the agent execution.

Empty Object

Response Body

curl -X POST "https://loading/api/v0/agents/string/executions/async" \
  -H "X-Correlation-ID: string" \
  -H "Content-Type: application/json" \
  -d '{}'
{
  "data": {
    "exec_id": "2Z4PVTL6K27XVT4A3NPKMDD5BG",
    "exec_url": "https://api.compozy.dev/api/v0/executions/agents/2Z4PVTL6K27XVT4A3NPKMDD5BG"
  },
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}
{
  "data": null,
  "error": {
    "code": "string",
    "details": "string",
    "message": "string"
  },
  "message": "string",
  "status": 0
}

Tasks

Task management operations

Tools

Tool management operations