# Agents

Create and manage agents for automation workloads

## GET /v1/agents

> List agents for your team.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents":{"get":{"tags":["Agents"],"description":"List agents for your team.","parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"Number of agents per page (1-100, default 20)"},{"schema":{"type":"integer","minimum":0,"default":0},"in":"query","name":"offset","required":false,"description":"Number of agents to skip"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agents":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false}},"total":{"type":"number"},"limit":{"type":"number"},"offset":{"type":"number"}},"required":["agents","total","limit","offset"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}}}}
```

## POST /v1/agents

> Create a new agent. Optionally include a build configuration to create the first build in the same request.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents":{"post":{"tags":["Agents"],"description":"Create a new agent. Optionally include a build configuration to create the first build in the same request.","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Human-readable agent name"},"build":{"type":"object","properties":{"name":{"type":"string","minLength":1,"description":"Build name"},"config":{"type":"object","additionalProperties":{},"description":"Build configuration"}},"required":["name","config"],"additionalProperties":false,"description":"Optional initial build configuration. When provided, a build is created alongside the agent."}},"required":["name"],"additionalProperties":false}}},"required":true},"responses":{"201":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false},"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"required":["agent"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}}}}
```

## GET /v1/agents/{agent\_id}

> Get an agent by ID.

```json
{"openapi":"3.0.3","info":{"title":"Duvo Public API","version":"1.0.0"},"tags":[{"name":"Agents","description":"Create and manage agents for automation workloads"}],"servers":[{"url":"https://api.duvo.ai","description":"Production server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key authentication. Get your API key from the Duvo dashboard."}}},"paths":{"/v1/agents/{agent_id}":{"get":{"tags":["Agents"],"description":"Get an agent by ID.","parameters":[{"schema":{"type":"string","format":"uuid"},"in":"path","name":"agent_id","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"created_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true},"updated_at":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"}],"nullable":true}},"required":["id","name","created_at","updated_at"],"additionalProperties":false},"build":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"agent_id":{"type":"string","format":"uuid"},"name":{"type":"string"},"config":{"anyOf":[{"type":"object","properties":{"version":{"type":"string","enum":["v1"]},"data":{"type":"object","properties":{"model":{"type":"string"},"temperature":{"type":"number","minimum":0,"maximum":2,"nullable":true},"max_output_tokens":{"type":"number","exclusiveMinimum":true,"minimum":0,"nullable":true},"top_p":{"type":"number","minimum":0,"maximum":1,"nullable":true},"store":{"type":"boolean","nullable":true},"tools":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["mcp"]},"server_label":{"type":"string"},"server_url":{"type":"string"},"allowed_tools":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false}],"nullable":true},"headers":{"type":"object","additionalProperties":{"type":"string"},"nullable":true},"require_approval":{"anyOf":[{"type":"string","enum":["always"]},{"type":"string","enum":["never"]},{"type":"object","properties":{"always":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true},"never":{"type":"object","properties":{"tool_names":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false,"nullable":true}},"additionalProperties":false}],"nullable":true}},"required":["type","server_label","server_url"],"additionalProperties":false},"nullable":true},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"text":{"type":"object","properties":{"format":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["text"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["json_object"]}},"required":["type"],"additionalProperties":false}],"nullable":true}},"additionalProperties":false,"nullable":true},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]}},"required":["model","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false},{"type":"object","properties":{"version":{"type":"string","enum":["v2"]},"data":{"type":"object","properties":{"models":{"type":"object","properties":{"agent":{"type":"object","properties":{"model":{"type":"string","enum":["claude-sonnet-4-20250514","claude-sonnet-4-20250514[1m]","claude-sonnet-4-5-20250929","claude-sonnet-4-5-20250929[1m]","claude-opus-4-1-20250805","claude-opus-4-5-20251101","claude-sonnet-4-6","claude-sonnet-4-6[1m]","claude-opus-4-6","claude-opus-4-6[1m]","claude-opus-4-7","claude-opus-4-7[1m]","d1-max","duvo-1-max","duvo-1-max-sonnet-1m","duvo-1-max-sonnet-4.5","duvo-1-max-sonnet-4.5-1m","duvo-1-max-opus","duvo-1-max-opus-4.5","gpt-4.1","gpt-4o","gpt-4o-mini","gpt-5","gpt-5.1"]}},"required":["model"],"additionalProperties":false},"browsing":{"type":"object","properties":{"provider":{"type":"string","enum":["google","anthropic"]},"model":{"type":"string","enum":["gemini-2.5-pro","gemini-2.5-flash","gemini-3-pro-preview","claude-haiku-4-5","claude-sonnet-4-5","claude-opus-4-1"]}},"required":["provider","model"],"additionalProperties":false}},"required":["agent","browsing"],"additionalProperties":false},"input":{"anyOf":[{"type":"string"},{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["system","user","assistant"]},"content":{"anyOf":[{"type":"string"},{"type":"array","items":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["input_text"]},"text":{"type":"string"}},"required":["type","text"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_image"]},"detail":{"type":"string","enum":["low","high","auto"],"nullable":true},"file_id":{"type":"string","nullable":true},"url":{"type":"string","nullable":true}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["input_file"]},"file_id":{"type":"string"}},"required":["type","file_id"],"additionalProperties":false}]}}]},"type":{"type":"string","enum":["message"],"nullable":true}},"required":["role","content"],"additionalProperties":false}}]},"files":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"skills":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"plugins":{"type":"array","items":{"type":"string"},"nullable":true,"default":[]},"options":{"type":"object","properties":{"browserProvider":{"type":"string","enum":["browserbase","browser-use"]},"evaluationSchemaId":{"type":"string"},"benchmarkExpectedOutcomes":{"type":"array","items":{"type":"object","properties":{"description":{"type":"string"},"criteria":{"type":"string"}},"required":["description","criteria"],"additionalProperties":false}}},"additionalProperties":true}},"required":["models","input"],"additionalProperties":false}},"required":["version","data"],"additionalProperties":false}],"nullable":true},"revision_number":{"type":"number","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["id","agent_id","name","config","revision_number","created_at","updated_at"],"additionalProperties":false}},"required":["agent"],"additionalProperties":false}}}},"400":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"401":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"404":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}},"500":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"],"additionalProperties":false}}}}}}}}}
```