Agents API

Create, version, and execute agents. Agents are the core runtime unit for automation workflows.

Required Scopes

agents:readagents:writeagents:execute

Endpoints

GET/agents

List all agents in the workspace.

POST/agents

Create a new agent draft.

GET/agents/{agentId}

Fetch a single agent by ID.

PATCH/agents/{agentId}

Update agent metadata and config.

DELETE/agents/{agentId}

Delete an existing agent.

POST/agents/{agentId}/execute

Execute the agent and create a run record.

Code Examples

Curl

curl -X POST "https://api.servoagent.com/v1/agents/agent_123/execute" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"input":{"message":"Summarize this support thread"}}'

Python

from servoagent import ServoAgentClient

client = ServoAgentClient(api_key="sk_live_...")
run = client.agents.execute(
    agent_id="agent_123",
    input={"message": "Summarize this support thread"},
)
print(run.id, run.status)

Node.js

import { ServoAgentClient } from 'servoagent'

const client = new ServoAgentClient({ apiKey: 'sk_live_...' })
const run = await client.agents.execute({
  agentId: 'agent_123',
  input: { message: 'Summarize this support thread' },
})
console.log(run.id, run.status)

client := servoagent.NewClient(servoagent.Config{APIKey: "sk_live_..."})

run, err := client.Agents.Execute(ctx, "agent_123", map[string]any{
  "message": "Summarize this support thread",
})
if err != nil {
  log.Fatal(err)
}
fmt.Println(run.ID, run.Status)

Ruby

client = ServoAgent::Client.new(api_key: 'sk_live_...')

run = client.agents.execute(
  agent_id: 'agent_123',
  input: { message: 'Summarize this support thread' }
)
puts "#{run['id']} #{run['status']}"

Test It Live

Use API Explorer to execute these endpoints and generate request snippets from real inputs.

Open API Explorer