Agents API

Manage agents and their configuration.

Endpoints

Method	Endpoint	Description
GET	/api/agents	List all agents
POST	/api/agents	Create new agent
GET	/api/agents/{id}	Get agent details
PUT	/api/agents/{id}	Update agent
DELETE	/api/agents/{id}	Delete agent

List Agents

GET /api/agents

Response

{
  "agents": [
    {
      "id": "agent-123",
      "name": "support-bot",
      "description": "Customer support agent",
      "status": "active",
      "owner_email": "admin@example.com",
      "created_at": "2024-12-01T00:00:00Z",
      "updated_at": "2024-12-15T10:00:00Z"
    }
  ]
}

Create Agent

POST /api/agents
Content-Type: application/json

Request Body

{
  "name": "support-bot",
  "description": "Customer support automation"
}

Response

{
  "id": "agent-123",
  "name": "support-bot",
  "description": "Customer support automation",
  "status": "active",
  "created_at": "2024-12-15T10:00:00Z"
}

Validation

Field	Rules
name	Required, unique, alphanumeric with hyphens
description	Optional, max 500 characters

Get Agent

GET /api/agents/{id}

Response

{
  "id": "agent-123",
  "name": "support-bot",
  "description": "Customer support automation",
  "status": "active",
  "owner_email": "admin@example.com",
  "created_at": "2024-12-01T00:00:00Z",
  "updated_at": "2024-12-15T10:00:00Z",
  "settings": {
    "llm_provider": "workers-ai",
    "llm_model": "@cf/meta/llama-3.1-8b-instruct",
    "llm_temperature": 0.7
  },
  "stats": {
    "workflows": 5,
    "schedules": 10,
    "contacts": 100,
    "messages": 1500
  }
}

Update Agent

PUT /api/agents/{id}
Content-Type: application/json

Request Body

{
  "name": "support-bot-v2",
  "description": "Updated description",
  "status": "active"
}

Response

{
  "id": "agent-123",
  "name": "support-bot-v2",
  "description": "Updated description",
  "status": "active",
  "updated_at": "2024-12-15T11:00:00Z"
}

Delete Agent

DELETE /api/agents/{id}

Response

{
  "success": true,
  "message": "Agent deleted"
}

Notes

• Cannot delete the default agent
• Deletes all associated data (workflows, schedules, etc.)
• Requires owner role

Agent Status

Status	Description
active	Agent is running
paused	Agent is paused
disabled	Agent is disabled

Get Accessible Agents

For authenticated users:

GET /api/auth/agents

Response

{
  "agents": [
    {
      "id": "agent-123",
      "name": "support-bot",
      "role": "owner"
    },
    {
      "id": "agent-456",
      "name": "data-processor",
      "role": "admin"
    }
  ]
}

Manage Admins

List Admins

GET /api/agents/{id}/admins

Add Admin

POST /api/agents/{id}/admins
Content-Type: application/json

{
  "email": "user@example.com",
  "role": "admin"
}

Remove Admin

DELETE /api/agents/{id}/admins/{adminId}

Errors

Code	Description
400	Invalid agent data
403	Not authorized
404	Agent not found
409	Agent name already exists

Examples

Create and Configure Agent

# Create agent
curl -X POST https://your-domain.com/api/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "description": "My agent"}'

# Configure settings
curl -X PUT https://your-domain.com/api/agents/my-agent/settings \
  -H "Content-Type: application/json" \
  -d '{
    "llm_provider": "openai",
    "llm_model": "gpt-4",
    "llm_temperature": 0.5
  }'

List Active Agents

curl "https://your-domain.com/api/agents?status=active"