Role-Based Agents API

Role-based agents are AI agents mapped to Standard Occupational Classification (SOC) codes from O*NET, the US Department of Labor's occupational database. The .do platform provides 533 agents covering every digital-capable occupation.

Base URL

https://api.do/agents/roles

Overview

Role-based agents provide:

533 Occupations - Every digital-capable role from O*NET database
SOC Code Mapping - Standardized occupation codes (e.g., "15-1252.00")
Skills & Tasks - O*NET-defined competencies and responsibilities
Job Family Hierarchies - Organized by major groups and minor groups
Career Pathways - Related occupations and transitions

Endpoints

List Role-Based Agents

Get a list of all role-based agents.

GET /agents/roles

Query Parameters

Parameter	Type	Required	Description
`majorGroup`	string	No	Filter by major SOC group (e.g., "15" for Computer)
`minorGroup`	string	No	Filter by minor group (e.g., "15-12" for Software Developers)
`skills`	string[]	No	Filter by required skills
`education`	string	No	Filter by education level
`experience`	string	No	Filter by experience level
`search`	string	No	Search by title or description
`limit`	number	No	Max results (default: 50)
`offset`	number	No	Pagination offset (default: 0)

Example Request

curl -X GET "https://api.do/agents/roles?majorGroup=15&limit=5" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "15-1252.00",
        "soc": "15-1252.00",
        "title": "Software Developers, Applications",
        "majorGroup": "15-0000",
        "majorGroupTitle": "Computer and Mathematical Occupations",
        "minorGroup": "15-1250",
        "minorGroupTitle": "Software and Web Developers, Programmers",
        "description": "Develop, create, and modify general computer applications software or specialized utility programs.",
        "status": "available",
        "capabilities": ["software-design", "programming", "testing", "debugging", "documentation"],
        "skills": {
          "top": ["Programming", "Systems Analysis", "Software Development", "Testing and Debugging", "User Interface Design"],
          "technical": ["JavaScript", "Python", "Java", "SQL", "Git"]
        },
        "education": {
          "typical": "Bachelor's degree",
          "alternatives": ["Associate degree", "Bootcamp certificate"]
        },
        "experience": {
          "typical": "None to 2 years",
          "range": "0-5 years"
        }
      },
      {
        "id": "15-1211.00",
        "soc": "15-1211.00",
        "title": "Computer Systems Analysts",
        "majorGroup": "15-0000",
        "majorGroupTitle": "Computer and Mathematical Occupations",
        "minorGroup": "15-1210",
        "minorGroupTitle": "Computer Systems Analysts and Architects",
        "description": "Analyze science, engineering, business, and other data processing problems to develop and implement solutions to complex applications problems.",
        "status": "available",
        "capabilities": ["requirements-analysis", "system-design", "process-optimization", "technical-documentation", "stakeholder-communication"],
        "skills": {
          "top": ["Systems Analysis", "Requirements Gathering", "Technical Documentation", "Problem Solving", "Communication"],
          "technical": ["UML", "BPMN", "SQL", "System Architecture", "Agile Methodologies"]
        },
        "education": {
          "typical": "Bachelor's degree",
          "alternatives": ["Master's degree"]
        },
        "experience": {
          "typical": "2 to 4 years",
          "range": "2-8 years"
        }
      }
    ],
    "total": 533,
    "limit": 5,
    "offset": 0
  },
  "metadata": {
    "requestId": "req_role123",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Role Details

Get detailed information about a specific role-based agent.

GET /agents/roles/:soc

Path Parameters

Parameter	Type	Required	Description
`soc`	string	Yes	SOC code (e.g., "15-1252.00")

Example Request

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

Example Response

{
  "success": true,
  "data": {
    "id": "15-1252.00",
    "soc": "15-1252.00",
    "title": "Software Developers, Applications",
    "alternativeTitles": ["Application Developer", "Software Engineer", "Full Stack Developer", "Mobile App Developer"],
    "description": "Develop, create, and modify general computer applications software or specialized utility programs. Analyze user needs and develop software solutions. Design software or customize software for client use.",
    "status": "available",
    "majorGroup": "15-0000",
    "majorGroupTitle": "Computer and Mathematical Occupations",
    "minorGroup": "15-1250",
    "minorGroupTitle": "Software and Web Developers, Programmers",
    "tasks": [
      "Confer with systems analysts, engineers, programmers to design systems",
      "Analyze user needs and software requirements",
      "Design, develop and test computer applications",
      "Modify existing software to correct errors",
      "Write and maintain technical documentation"
    ],
    "skills": {
      "core": ["Programming", "Software Development", "Systems Analysis", "Testing and Debugging", "Problem Solving"],
      "technical": ["JavaScript", "Python", "Java", "React", "Node.js", "SQL", "Git", "Docker"],
      "soft": ["Communication", "Teamwork", "Attention to Detail", "Time Management", "Critical Thinking"]
    },
    "knowledge": ["Computers and Electronics", "Engineering and Technology", "Mathematics", "English Language", "Design"],
    "abilities": ["Deductive Reasoning", "Information Ordering", "Problem Sensitivity", "Written Comprehension", "Oral Expression"],
    "tools": ["development-ide", "version-control", "debugging-tools", "testing-frameworks", "deployment-platforms"],
    "education": {
      "typical": "Bachelor's degree",
      "alternatives": ["Associate degree", "Bootcamp certificate", "Self-taught"]
    },
    "experience": {
      "typical": "None to 2 years",
      "range": "0-5 years"
    },
    "salary": {
      "median": 110140,
      "percentile25": 87940,
      "percentile75": 140470,
      "currency": "USD",
      "period": "annual"
    },
    "outlook": {
      "growth": "22%",
      "period": "2022-2032",
      "demand": "very high"
    },
    "relatedOccupations": [
      "15-1256.00", // Software Developers, Systems
      "15-1255.00", // Web and Digital Interface Designers
      "15-1253.00", // Software Quality Assurance Analysts
      "15-1299.08" // Computer Systems Engineers/Architects
    ],
    "availability": {
      "nextAvailable": "2024-10-27T18:00:00Z",
      "currentLoad": 0.4,
      "estimatedResponseTime": "20 minutes"
    }
  },
  "metadata": {
    "requestId": "req_role124",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Invoke Role-Based Agent

Invoke a role-based agent to perform a task.

POST /agents/roles/:soc/invoke

Path Parameters

Parameter	Type	Required	Description
`soc`	string	Yes	SOC code

Request Body

Field	Type	Required	Description
`task`	string	Yes	Task description
`context`	object	No	Additional context
`priority`	string	No	Priority (low, medium, high, urgent)
`deadline`	string	No	ISO 8601 deadline
`skills`	string[]	No	Required skills for the task

Example Request

curl -X POST "https://api.do/agents/roles/15-1252.00/invoke" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Develop a REST API for user authentication",
    "context": {
      "requirements": "JWT-based auth, OAuth integration, rate limiting",
      "stack": "Node.js, Express, PostgreSQL",
      "timeline": "1 week"
    },
    "priority": "high",
    "skills": ["api-design", "authentication", "security"]
  }'

Example Response

{
  "success": true,
  "data": {
    "taskId": "task_role456",
    "agentId": "15-1252.00",
    "agentTitle": "Software Developers, Applications",
    "status": "in_progress",
    "task": "Develop a REST API for user authentication",
    "estimatedCompletion": "2024-11-03T18:00:00Z",
    "estimatedDuration": "40 hours",
    "matchScore": 0.95,
    "matchReasons": ["Strong match for API development", "Experience with authentication systems", "Node.js expertise"],
    "trackingUrl": "https://api.do/agents/tasks/task_role456",
    "createdAt": "2024-10-27T18:00:00Z"
  },
  "metadata": {
    "requestId": "req_role125",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Search Roles by Capability

Find roles that match specific capabilities or skills.

POST /agents/roles/search

Request Body

Field	Type	Required	Description
`capabilities`	string[]	No	Required capabilities
`skills`	string[]	No	Required skills
`education`	string	No	Education level
`experience`	string	No	Experience level
`query`	string	No	Free-text search

Example Request

curl -X POST "https://api.do/agents/roles/search" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "capabilities": ["data-analysis", "machine-learning"],
    "skills": ["Python", "SQL", "TensorFlow"],
    "education": "Bachelor'\''s degree"
  }'

Example Response

{
  "success": true,
  "data": {
    "matches": [
      {
        "id": "15-2051.00",
        "soc": "15-2051.00",
        "title": "Data Scientists",
        "matchScore": 0.92,
        "matchReasons": ["Strong data analysis capabilities", "Machine learning expertise", "Python and SQL proficiency"],
        "status": "available"
      },
      {
        "id": "15-1299.05",
        "soc": "15-1299.05",
        "title": "Information Security Engineers",
        "matchScore": 0.78,
        "matchReasons": ["Data analysis skills", "Python experience", "Security-focused ML applications"],
        "status": "available"
      }
    ],
    "total": 12
  },
  "metadata": {
    "requestId": "req_role126",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Get Role Hierarchy

Get the SOC hierarchy (major groups, minor groups, detailed occupations).

GET /agents/roles/hierarchy

Query Parameters

Parameter	Type	Required	Description
`level`	string	No	Hierarchy level (major, minor, detailed)
`group`	string	No	Filter by group code

Example Request

curl -X GET "https://api.do/agents/roles/hierarchy?level=major" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "success": true,
  "data": {
    "hierarchy": [
      {
        "code": "15-0000",
        "title": "Computer and Mathematical Occupations",
        "count": 87,
        "minorGroups": [
          {
            "code": "15-1210",
            "title": "Computer Systems Analysts and Architects",
            "count": 3
          },
          {
            "code": "15-1250",
            "title": "Software and Web Developers, Programmers",
            "count": 12
          }
        ]
      },
      {
        "code": "13-0000",
        "title": "Business and Financial Operations Occupations",
        "count": 68,
        "minorGroups": [
          {
            "code": "13-1160",
            "title": "Market Research Analysts and Marketing Specialists",
            "count": 5
          }
        ]
      }
    ]
  },
  "metadata": {
    "requestId": "req_role127",
    "timestamp": "2024-10-27T18:00:00Z"
  }
}

Major Occupation Groups

15-0000: Computer and Mathematical

Software developers, data scientists, systems analysts, database administrators

Popular Roles:

15-1252.00 - Software Developers, Applications
15-2051.00 - Data Scientists
15-1211.00 - Computer Systems Analysts
15-1243.00 - Database Architects

13-0000: Business and Financial Operations

Market analysts, financial analysts, management analysts, business intelligence

Popular Roles:

13-1161.00 - Market Research Analysts
13-2051.00 - Financial Analysts
13-1111.00 - Management Analysts
13-1199.00 - Business Intelligence Analysts

27-0000: Arts, Design, Entertainment, Sports, Media

Writers, designers, editors, photographers

Popular Roles:

27-3042.00 - Technical Writers
27-1024.00 - Graphic Designers
27-1014.00 - Multimedia Artists
27-3031.00 - Public Relations Specialists

11-0000: Management

IT managers, project managers, executives

Popular Roles:

11-3021.00 - Computer and Information Systems Managers
11-9199.11 - Product Management Specialists
11-3031.00 - Financial Managers
11-2021.00 - Marketing Managers

TypeScript SDK Example

import { $ } from 'sdk.do'

// List roles in a major group
const computerRoles = await $.Agent.list({
  type: 'role',
  majorGroup: '15',
  limit: 20,
})

// Get role details
const softwareDev = await $.Agent.getRole('15-1252.00')

// Invoke role-based agent
const task = await $.Agent.invokeRole({
  soc: '15-1252.00',
  task: 'Develop REST API for authentication',
  context: {
    requirements: 'JWT-based auth, OAuth',
    stack: 'Node.js, Express, PostgreSQL',
  },
  skills: ['api-design', 'authentication', 'security'],
})

// Search by capability
const matches = await $.Agent.searchRoles({
  capabilities: ['data-analysis', 'machine-learning'],
  skills: ['Python', 'SQL'],
  education: "Bachelor's degree",
})

// Get hierarchy
const hierarchy = await $.Agent.getRoleHierarchy({
  level: 'major',
})

Python SDK Example

from do_sdk import Agent

# List roles in a major group
computer_roles = Agent.list(
    type='role',
    major_group='15',
    limit=20
)

# Get role details
software_dev = Agent.get_role('15-1252.00')

# Invoke role-based agent
task = Agent.invoke_role(
    soc='15-1252.00',
    task='Develop REST API for authentication',
    context={
        'requirements': 'JWT-based auth, OAuth',
        'stack': 'Node.js, Express, PostgreSQL'
    },
    skills=['api-design', 'authentication', 'security']
)

# Search by capability
matches = Agent.search_roles(
    capabilities=['data-analysis', 'machine-learning'],
    skills=['Python', 'SQL'],
    education='Bachelor\'s degree'
)

CLI Example

# List roles in major group
do agent list --type role --major-group 15

# Get role details
do agent get-role 15-1252.00

# Invoke role-based agent
do agent invoke-role 15-1252.00 "Develop REST API" \
  --requirements "JWT-based auth" \
  --stack "Node.js" \
  --skills api-design,authentication

# Search by capability
do agent search-roles \
  --capabilities data-analysis,machine-learning \
  --skills Python,SQL \
  --education "Bachelor's degree"

# Get hierarchy
do agent hierarchy --level major

Best Practices

1. Match Task to Role

Choose roles based on O*NET-defined capabilities:

// Good: Software developer for API work
await $.Agent.invokeRole({
  soc: '15-1252.00',
  task: 'Build REST API',
})

// Good: Data scientist for ML work
await $.Agent.invokeRole({
  soc: '15-2051.00',
  task: 'Build recommendation system',
})

2. Use Search for Complex Requirements

When requirements span multiple skills, use search:

const matches = await $.Agent.searchRoles({
  capabilities: ['full-stack', 'devops', 'security'],
  skills: ['Node.js', 'Docker', 'AWS'],
  experience: '3-5 years',
})

// Use the best match
const bestMatch = matches[0]
await $.Agent.invokeRole({ soc: bestMatch.soc, task: '...' })

3. Specify Required Skills

Help match agents with the right expertise:

await $.Agent.invokeRole({
  soc: '15-1252.00',
  task: 'Build mobile app',
  skills: ['React Native', 'TypeScript', 'Mobile UX'],
})

Find alternative roles for specialized tasks:

const role = await $.Agent.getRole('15-1252.00')

// Check related occupations
for (const relatedSoc of role.relatedOccupations) {
  const related = await $.Agent.getRole(relatedSoc)
  console.log(`${related.title}: ${related.description}`)
}

Error Responses

Invalid SOC Code

{
  "success": false,
  "error": {
    "code": "INVALID_SOC_CODE",
    "message": "SOC code '99-9999.99' is not valid",
    "details": {
      "provided": "99-9999.99",
      "format": "XX-XXXX.XX",
      "suggestion": "Use GET /agents/roles/hierarchy to browse valid codes"
    }
  }
}

Role Not Found

{
  "success": false,
  "error": {
    "code": "ROLE_NOT_FOUND",
    "message": "No agent found for SOC code '15-9999.00'",
    "details": {
      "soc": "15-9999.00",
      "suggestion": "Search for similar roles using /agents/roles/search"
    }
  }
}

Agents API Overview - Complete API overview
Named Agents - 102 specialized agents
Teams API - Multi-agent teams
Tasks API - Task management
O*NET Data - Official O*NET database

Support

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

Role-Based Agents API

On this page