Atom AI Labs - AI-Powered Multi-Tenant Platform

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:**

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Items per page (default: 20)
`maturity_level`	string	No	Filter by maturity level
`status`	string	No	Filter by status (active/inactive)
`sort`	string	No	Sort field (created_at, name)
`order`	string	No	Sort order (asc, desc)

**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:**

Field	Type	Required	Description
`name`	string	Yes	Agent name (max 100 chars)
`description`	string	No	Agent description
`role`	string	Yes	Agent role (see roles below)
`maturity_level`	string	Yes	Initial maturity level
`capabilities`	array	No	List of capabilities
`configuration`	object	No	LLM configuration

**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:**

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

**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:**

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

**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:**

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

**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:**

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID

**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:**

Field	Type	Required	Description
`task`	string	Yes	Task description
`context`	object	No	Additional context
`parameters`	object	No	Execution parameters

**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:**

Parameter	Type	Required	Description
`agent_id`	string	Yes	Agent ID
`execution_id`	string	Yes	Execution ID

**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:

Tier	Requests/Day	Requests/Minute
Free	50	60
Solo	500	100
Team	5,000	500
Enterprise	Unlimited	Custom

Rate limit headers returned:

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

---

Error Codes

Code	Description
`AGENT_NOT_FOUND`	Agent does not exist
`AGENT_LIMIT_EXCEEDED`	Tenant agent limit reached
`INVALID_INPUT`	Request validation failed
`GOVERNANCE_VIOLATION`	Action not allowed by governance
`EXECUTION_FAILED`	Task execution failed
`RATE_LIMIT_EXCEEDED`	Rate limit exceeded

---

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