Agent API Documentation

Complete API reference for agent management, execution, and training operations.

Base URL

Production: https://api.atomagentos.com Development: http://localhost:8000

All endpoints are prefixed with /api.

Authentication

Include authentication token in request headers:

# JWT Token
Authorization: Bearer <your_jwt_token>

# API Key
X-API-Key: <your_api_key>

Endpoints

1. List All Agents

Get all agents for the current tenant.

GET /api/agents

Query Parameters:

Example Request:

curl -X GET "https://api.atomagentos.com/api/agents?page=1&limit=10&maturity_level=student" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "success": true,
  "data": {
    "agents": [
      {
        "id": "agent_abc123",
        "name": "Research Assistant",
        "description": "Helps with research tasks",
        "role": "general-assistant",
        "maturity_level": "student",
        "status": "active",
        "created_at": "2025-02-01T10:00:00Z",
        "updated_at": "2025-02-06T15:30:00Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "pages": 3
    }
  },
  "meta": {
    "timestamp": "2025-02-06T16:00:00Z",
    "request_id": "req_xyz789"
  }
}

Error Responses:

• 401 - Unauthorized (invalid/missing token)
• 403 - Forbidden (insufficient permissions)
• 500 - Internal server error

2. Create Agent

Create a new agent for the current tenant.

POST /api/agents

Request Body:

{
  "name": "Research Assistant",
  "description": "Helps with academic research tasks",
  "role": "general-assistant",
  "maturity_level": "student",
  "capabilities": [
    "web_browsing",
    "search",
    "summarization"
  ],
  "configuration": {
    "temperature": 0.7,
    "max_tokens": 2000
  }
}

Field Requirements:

Agent Roles:

• general-assistant - All-purpose helper
• finance-agent - Financial analysis
• marketing-agent - Marketing tasks
• developer-agent - Code and development
• custom - Custom role

Maturity Levels:

• student - Read-only, low-complexity
• intern - Analyze, suggest
• supervised - Create, moderate actions
• autonomous - All actions including high-risk

Example Request:

curl -X POST "https://api.atomagentos.com/api/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Finance Assistant",
    "role": "finance-agent",
    "maturity_level": "intern",
    "capabilities": ["analyze", "report", "forecast"]
  }'

Example Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent_def456",
      "name": "Finance Assistant",
      "description": null,
      "role": "finance-agent",
      "maturity_level": "intern",
      "capabilities": ["analyze", "report", "forecast"],
      "status": "active",
      "created_at": "2025-02-06T16:05:00Z",
      "tenant_id": "tenant_abc123"
    }
  },
  "meta": {
    "timestamp": "2025-02-06T16:05:00Z",
    "request_id": "req_xyz780"
  }
}

Error Responses:

• 400 - Validation error (invalid input)
• 403 - Agent limit exceeded
• 401 - Unauthorized
• 500 - Internal server error

3. Get Agent Details

Retrieve detailed information about a specific agent.

GET /api/agents/{agent_id}

Path Parameters:

Example Request:

curl -X GET "https://api.atomagentos.com/api/agents/agent_abc123" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent_abc123",
      "name": "Research Assistant",
      "description": "Helps with research tasks",
      "role": "general-assistant",
      "maturity_level": "student",
      "capabilities": [
        "web_browsing",
        "search",
        "summarization"
      ],
      "configuration": {
        "temperature": 0.7,
        "max_tokens": 2000
      },
      "statistics": {
        "total_executions": 150,
        "successful_executions": 142,
        "success_rate": 0.946,
        "avg_confidence": 0.87,
        "last_execution": "2025-02-06T15:30:00Z"
      },
      "graduation": {
        "current_level": "student",
        "readiness_score": 0.72,
        "eligible_levels": ["intern"],
        "episodes_until_exam": 8
      },
      "created_at": "2025-02-01T10:00:00Z",
      "updated_at": "2025-02-06T15:30:00Z"
    }
  },
  "meta": {
    "timestamp": "2025-02-06T16:10:00Z",
    "request_id": "req_xyz781"
  }
}

Error Responses:

• 401 - Unauthorized
• 403 - Forbidden (agent not owned by tenant)
• 404 - Agent not found

4. Update Agent

Update an existing agent's configuration.

PUT /api/agents/{agent_id}

Path Parameters:

Request Body:

All fields are optional. Only include fields to update.

{
  "name": "Updated Name",
  "description": "Updated description",
  "capabilities": ["web_browsing", "search", "summarization", "analysis"],
  "configuration": {
    "temperature": 0.8,
    "max_tokens": 3000
  }
}

Example Request:

curl -X PUT "https://api.atomagentos.com/api/agents/agent_abc123" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Senior Research Assistant",
    "configuration": {
      "temperature": 0.8
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "agent": {
      "id": "agent_abc123",
      "name": "Senior Research Assistant",
      "description": "Updated description",
      "configuration": {
        "temperature": 0.8,
        "max_tokens": 2000
      },
      "updated_at": "2025-02-06T16:15:00Z"
    }
  },
  "meta": {
    "timestamp": "2025-02-06T16:15:00Z",
    "request_id": "req_xyz782"
  }
}

Constraints:

• Cannot change role or maturity_level directly (use graduation/promotion)
• Name max length: 100 characters
• Max 50 capabilities

Error Responses:

• 400 - Validation error
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Agent not found

5. Delete Agent

Delete an agent and all associated data.

DELETE /api/agents/{agent_id}

Path Parameters:

Example Request:

curl -X DELETE "https://api.atomagentos.com/api/agents/agent_abc123" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "success": true,
  "data": {
    "deleted": true,
    "agent_id": "agent_abc123"
  },
  "meta": {
    "timestamp": "2025-02-06T16:20:00Z",
    "request_id": "req_xyz783"
  }
}

Warning:

• This action cannot be undone
• All episodes, executions, and learning data will be deleted
• Consider exporting data before deletion

Error Responses:

• 401 - Unauthorized
• 403 - Forbidden
• 404 - Agent not found
• 409 - Conflict (agent has active executions)

6. Execute Agent Task

Execute a task using an agent.

POST /api/agents/{agent_id}/execute

Path Parameters:

Request Body:

{
  "task": "Search for recent AI research papers and summarize findings",
  "context": {
    "domain": "academic",
    "time_range": "last_7_days",
    "sources": ["arxiv", "scholar"]
  },
  "parameters": {
    "max_results": 10,
    "include_citations": true
  }
}

Field Requirements:

Example Request:

curl -X POST "https://api.atomagentos.com/api/agents/agent_abc123/execute" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Analyze Q4 sales data",
    "context": {
      "quarter": "Q4",
      "year": 2024
    }
  }'

Example Response (Synchronous):

{
  "success": true,
  "data": {
    "execution_id": "exec_xyz789",
    "agent_id": "agent_abc123",
    "status": "completed",
    "result": {
      "summary": "Q4 sales increased by 15% compared to Q3...",
      "details": {
        "total_sales": 1500000,
        "growth_rate": 0.15,
        "top_products": ["SKU-123", "SKU-456"]
      }
    },
    "confidence": 0.92,
    "reasoning_trace": [...],
    "started_at": "2025-02-06T16:25:00Z",
    "completed_at": "2025-02-06T16:26:30Z",
    "duration_seconds": 90
  },
  "meta": {
    "timestamp": "2025-02-06T16:26:30Z",
    "request_id": "req_xyz784"
  }
}

Example Response (Async/Long-running):

{
  "success": true,
  "data": {
    "execution_id": "exec_xyz789",
    "agent_id": "agent_abc123",
    "status": "in_progress",
    "message": "Task is being processed",
    "poll_url": "/api/agents/agent_abc123/executions/exec_xyz789"
  },
  "meta": {
    "timestamp": "2025-02-06T16:25:00Z",
    "request_id": "req_xyz784"
  }
}

Error Responses:

• 400 - Validation error
• 401 - Unauthorized
• 403 - Forbidden (action not allowed by governance)
• 404 - Agent not found
• 429 - Rate limit exceeded
• 500 - Execution failed

7. Get Execution Status

Check the status of an async execution.

GET /api/agents/{agent_id}/executions/{execution_id}

Path Parameters:

Example Request:

curl -X GET "https://api.atomagentos.com/api/agents/agent_abc123/executions/exec_xyz789" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "success": true,
  "data": {
    "execution_id": "exec_xyz789",
    "agent_id": "agent_abc123",
    "status": "completed",
    "result": {
      "summary": "Task completed successfully"
    },
    "progress": 100,
    "started_at": "2025-02-06T16:25:00Z",
    "completed_at": "2025-02-06T16:26:30Z"
  }
}

Status Values:

• pending - Queued, not started
• in_progress - Currently executing
• completed - Finished successfully
• failed - Failed with error
• cancelled - Cancelled by user

8. Get Training Status

Get agent's learning and training progress.

GET /api/agents/{agent_id}/training

Example Request:

curl -X GET "https://api.atomagentos.com/api/agents/agent_abc123/training" \
  -H "Authorization: Bearer $TOKEN"

Example Response:

{
  "success": true,
  "data": {
    "agent_id": "agent_abc123",
    "learning_statistics": {
      "total_experiences": 45,
      "successful_experiences": 42,
      "success_rate": 0.933,
      "avg_confidence": 0.88
    },
    "patterns_detected": [
      {
        "pattern": "Weighted average costing",
        "success_rate": 0.95,
        "sample_size": 12
      }
    ],
    "adaptations_available": [
      {
        "id": "adapt_def456",
        "type": "reinforce_pattern",
        "description": "Increase usage of successful pattern",
        "expected_improvement": 0.08
      }
    ],
    "graduation_readiness": {
      "current_level": "intern",
      "readiness_score": 0.82,
      "eligible_levels": ["supervised"],
      "episodes_until_exam": 5
    }
  }
}

Rate Limiting

Agent API rate limits by tier:

Rate limit headers returned:

X-RateLimit-Limit: 500
X-RateLimit-Remaining: 450
X-RateLimit-Reset: 1707225600

Error Codes

SDK Examples

TypeScript/JavaScript

import { AtomClient } from '@atom/sdk';

const client = new AtomClient({
  apiKey: process.env.ATOM_API_KEY
});

// List agents
const agents = await client.agents.list({
  maturity_level: 'student'
});

// Create agent
const agent = await client.agents.create({
  name: 'Research Assistant',
  role: 'general-assistant',
  maturity_level: 'student'
});

// Execute task
const result = await client.agents.execute(agent.id, {
  task: 'Search for AI papers'
});

Python

from atom import AtomClient

client = AtomClient(api_key="your_api_key")

# List agents
agents = client.agents.list(maturity_level="student")

# Create agent
agent = client.agents.create(
    name="Research Assistant",
    role="general-assistant",
    maturity_level="student"
)

# Execute task
result = client.agents.execute(
    agent.id,
    task="Search for AI papers"
)

Webhooks

Subscribe to agent events:

Execution Completed

{
  "event": "agent.executed",
  "data": {
    "agent_id": "agent_abc123",
    "execution_id": "exec_xyz789",
    "status": "completed",
    "result": {...}
  },
  "timestamp": "2025-02-06T16:30:00Z"
}

Graduation Completed

{
  "event": "agent.graduated",
  "data": {
    "agent_id": "agent_abc123",
    "previous_level": "intern",
    "new_level": "supervised",
    "readiness_score": 0.82
  },
  "timestamp": "2025-02-06T16:30:00Z"
}

Last Updated: 2025-02-06 API Version: v8.0