Agents

Agents represent AI entities with persistent identity, lifecycle management, and associated resources. Every agent has a unique ID that follows it across sessions, deployments, and infrastructure.

Create Agent

Endpoint: POST /v1/agents

Create a new agent with metadata and configuration.

Request

POST /v1/agents
Content-Type: application/json
X-API-Key: your-api-key

{
  "name": "support-bot",
  "description": "Customer support agent",
  "metadata": {
    "version": "2.0",
    "model": "gpt-4"
  }
}

Response

{
  "id": "agt_abc123",
  "name": "support-bot",
  "description": "Customer support agent",
  "status": "active",
  "metadata": {
    "version": "2.0",
    "model": "gpt-4"
  },
  "created_at": "2025-01-01T00:00:00Z",
  "updated_at": "2025-01-01T00:00:00Z"
}

Get Agent

Endpoint: GET /v1/agents/:id

Retrieve a specific agent by ID.

List Agents

Endpoint: GET /v1/agents

List all agents with optional filtering.

Query Parameters

• status (optional): Filter by status (active, suspended)
• limit (optional): Maximum number of results (default: 100)
• offset (optional): Pagination offset

Update Agent

Endpoint: PUT /v1/agents/:id

Update agent metadata and configuration.

Suspend Agent

Endpoint: POST /v1/agents/:id/suspend

Temporarily disable an agent. A suspended agent cannot access data or use tools, but all data is preserved.

Activate Agent

Endpoint: POST /v1/agents/:id/activate

Re-enable a suspended agent.

Delete Agent

Endpoint: DELETE /v1/agents/:id

Permanently remove an agent and all associated data.

Query Parameters

• preserve_audit (optional): If true, preserve audit logs after deletion