Agents API

The Agents API provides programmatic access to the .do platform's autonomous agent capabilities, enabling you to invoke agents, manage teams, assign tasks, and orchestrate multi-agent workflows.

Overview

The .do platform provides a comprehensive agent ecosystem:

102 Named Agents - Specialized agents like Amy (analyst), Tom (developer), Cody (architect)
533 Role-Based Agents - O*NET occupation-based agents for every digital-capable role
35 Agent Teams - Pre-configured teams for complex multi-agent workflows
Services-as-Software - Package agent capabilities into autonomous services

Base URL

All agent API endpoints are available at:

https://api.do/agents

Authentication

All requests require authentication via Bearer token:

curl -X GET "https://api.do/agents/named" \
  -H "Authorization: Bearer YOUR_API_KEY"

Learn more about authentication →

Quick Start

1. List Available Agents

curl -X GET "https://api.do/agents/named" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "agents": [
    {
      "id": "amy",
      "name": "Amy",
      "role": "Business Analyst",
      "capabilities": ["market-research", "data-analysis", "reporting"],
      "status": "available"
    },
    {
      "id": "tom",
      "name": "Tom",
      "role": "Software Engineer",
      "capabilities": ["full-stack-dev", "testing", "code-review"],
      "status": "available"
    }
  ],
  "total": 102
}

2. Invoke an Agent

curl -X POST "https://api.do/agents/named/amy/invoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Analyze Q4 revenue trends",
    "context": {
      "data": "revenue_q4_2024.csv",
      "focusAreas": ["growth", "churn", "expansion"]
    }
  }'

Response:

{
  "taskId": "task_abc123",
  "agentId": "amy",
  "status": "in_progress",
  "estimatedCompletion": "2024-10-27T18:30:00Z",
  "trackingUrl": "https://api.do/agents/tasks/task_abc123"
}

3. Check Task Status

curl -X GET "https://api.do/agents/tasks/task_abc123" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "taskId": "task_abc123",
  "status": "completed",
  "result": {
    "analysis": "Q4 revenue grew 23% YoY...",
    "insights": ["Expansion revenue up 45%", "Churn decreased to 2.1%"],
    "deliverables": [
      {
        "type": "report",
        "url": "https://storage.do/reports/revenue-q4.pdf"
      },
      {
        "type": "presentation",
        "url": "https://storage.do/slides/revenue-q4.pptx"
      }
    ]
  },
  "completedAt": "2024-10-27T18:25:00Z",
  "duration": "25 minutes"
}

API Patterns

RPC Pattern

Call agent methods directly via RPC:

POST /agents/:agentId.:method

Examples:

/agents/amy.analyze - Amy analyzes data
/agents/tom.develop - Tom develops features
/agents/cody.architect - Cody designs architecture
/agents/quinn.test - Quinn runs QA tests

REST Pattern

RESTful endpoints for resource management:

GET    /agents/named              List named agents
GET    /agents/named/:id          Get agent details
POST   /agents/named/:id/invoke   Invoke agent
GET    /agents/roles              List role-based agents
POST   /agents/roles/:soc/invoke  Invoke role-based agent
GET    /agents/teams              List teams
POST   /agents/teams              Create team
GET    /agents/tasks/:id          Get task status
POST   /agents/tasks              Create task

Core Concepts

Named Agents

102 specialized agents with unique personalities and expertise areas:

Amy - Business Analyst (market research, data analysis)
Tom - Software Engineer (full-stack development)
Cody - Technical Architect (system design)
Quinn - QA Engineer (testing, quality assurance)
Sam - Security Engineer (security audits)
And 97 more...

Learn more about named agents →

Role-Based Agents

533 agents based on O*NET occupation data, covering every digital-capable role:

15-1252.00 - Software Developers, Applications
13-1161.00 - Market Research Analysts
11-3021.00 - Computer and Information Systems Managers
15-1211.00 - Computer Systems Analysts
And 529 more...

Learn more about role-based agents →

Agent Teams

Pre-configured teams for multi-agent collaboration:

Engineering Team - Tom, Cody, Quinn, Sam (full dev lifecycle)
Product Team - Priya, Amy, Mira (product strategy)
Marketing Team - Clara, Mira, Eli (content and campaigns)
And 32 more teams...

Learn more about teams →

Tasks

Assign work to agents and track progress:

Create tasks with clear requirements
Monitor status and progress
Retrieve deliverables
Handle errors and retries

Learn more about tasks →

Tools

Agents have access to specialized tools:

Data Analysis - Pandas, NumPy, visualization
Development - Git, Docker, testing frameworks
Communication - Email, Slack, calendar
Research - Web search, knowledge bases

Learn more about tools →

Services

Package agent capabilities as autonomous services:

Define service contracts (inputs/outputs)
Set pricing models (fixed, usage, subscription)
Publish to marketplace
Track performance and SLAs

Learn more about services →

Workflows

Orchestrate multi-agent workflows:

Define sequential or parallel workflows
Handle dependencies between tasks
Coordinate teams on complex projects
Monitor end-to-end execution

Learn more about workflows →

Response Format

All API responses follow a consistent structure:

Success Response

{
  "success": true,
  "data": {
    /* resource data */
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent with ID 'xyz' not found",
    "details": {
      "agentId": "xyz",
      "availableAgents": ["amy", "tom", "cody"]
    }
  },
  "metadata": {
    "requestId": "req_abc123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Common Error Codes

Code	HTTP Status	Description
`AGENT_NOT_FOUND`	404	Specified agent does not exist
`AGENT_UNAVAILABLE`	503	Agent is busy or offline
`INVALID_TASK`	400	Task definition is invalid
`TASK_NOT_FOUND`	404	Task ID not found
`TEAM_NOT_FOUND`	404	Team ID not found
`INSUFFICIENT_PERMISSIONS`	403	User lacks required permissions
`RATE_LIMIT_EXCEEDED`	429	Too many requests

View all error codes →

Rate Limits

Agent API rate limits vary by tier:

Tier	Requests/Min	Requests/Day	Concurrent Tasks
Free	10	1,000	3
Pro	100	10,000	25
Enterprise	Custom	Custom	Custom

Learn more about rate limits →

SDK Support

TypeScript/JavaScript

import { $ } from 'sdk.do'

// Invoke named agent
const result = await $.Agent.invoke({
  agentId: 'amy',
  task: 'Analyze Q4 revenue trends',
  context: { data: 'revenue_q4_2024.csv' },
})

// List available agents
const agents = await $.Agent.list({ type: 'named' })

// Get task status
const task = await $.Task.get('task_abc123')

View TypeScript SDK docs →

Python

from do_sdk import Agent, Task

# Invoke named agent
result = Agent.invoke(
    agent_id='amy',
    task='Analyze Q4 revenue trends',
    context={'data': 'revenue_q4_2024.csv'}
)

# List available agents
agents = Agent.list(type='named')

# Get task status
task = Task.get('task_abc123')

CLI

# Invoke agent
do agent invoke amy "Analyze Q4 revenue trends" --data revenue_q4_2024.csv

# List agents
do agent list --type named

# Check task status
do task get task_abc123

View CLI docs →

Webhooks

Subscribe to agent events via webhooks:

POST /webhooks/agents
{
  "url": "https://your-app.com/webhooks/agents",
  "events": [
    "task.started",
    "task.completed",
    "task.failed",
    "agent.available",
    "agent.busy"
  ]
}

Learn more about webhooks →

Examples

Example 1: Research and Report Generation

// Amy researches market, Tom builds dashboard, Clara writes report
const workflow = await $.Workflow.create({
  steps: [
    {
      agent: 'amy',
      task: 'Market research for SaaS pricing',
      output: 'research-data',
    },
    {
      agent: 'tom',
      task: 'Build pricing dashboard',
      input: 'research-data',
      output: 'dashboard',
    },
    {
      agent: 'clara',
      task: 'Write executive summary',
      input: ['research-data', 'dashboard'],
      output: 'report',
    },
  ],
})

const result = await $.Workflow.execute(workflow.id)

Example 2: Full-Stack Development

// Engineering team builds feature end-to-end
const task = await $.Team.assign({
  teamId: 'engineering',
  task: 'Build user authentication system',
  requirements: {
    features: ['email-login', 'oauth', 'mfa'],
    timeline: '2 weeks',
  },
})

// Team automatically distributes work:
// - Cody: Architecture design
// - Tom: Backend implementation
// - Rae: Frontend implementation
// - Quinn: Testing
// - Sam: Security audit

Example 3: Service Creation

// Create a market research service
const service = await $.Service.create({
  name: 'Competitive Analysis Service',
  provider: { type: 'agent', agentId: 'mira' },
  inputs: [
    { name: 'industry', type: 'text', required: true },
    { name: 'competitors', type: 'array', required: true },
  ],
  outputs: [
    { name: 'report', type: 'pdf' },
    { name: 'data', type: 'spreadsheet' },
  ],
  pricing: { model: 'fixed', price: 2500 },
  sla: { turnaroundTime: '5 business days' },
})

// Publish to marketplace
await $.Service.publish(service.id)

Named Agents API - 102 specialized agents
Role-Based Agents API - 533 occupation-based agents
Teams API - Multi-agent team management
Tasks API - Task assignment and tracking
Tools API - Agent tools and capabilities
Services API - Services-as-Software
Workflows API - Multi-agent orchestration

Support

Documentation - docs.do
API Status - status.do
Community - Discord
Support - support@do

Agents API

On this page