docs/API.md

API Documentation

Overview

The Multi-Agent System provides a RESTful API for task execution, workflow management, and agent coordination.

Base URL: http://localhost:8000

Authentication

Currently, the API is open. For production, implement JWT or API key authentication.

Endpoints

Health Check

GET /health

Check if the service is healthy.

Response:

{
  "status": "healthy",
  "version": "0.1.0"
}

GET /ready

Check if the service is ready to accept requests.

Response:

{
  "status": "ready",
  "version": "0.1.0"
}

Tasks

POST /tasks

Create and execute a new task.

Request Body:

{
  "task": "Analyze the latest market trends for tech stocks",
  "task_id": "optional-custom-id"
}

Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "Analyze the latest market trends for tech stocks",
  "status": "processing"
}

GET /tasks/{task_id}

Get the status and results of a task.

Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "task": "Analyze the latest market trends for tech stocks",
  "status": "completed"
}

DELETE /tasks/{task_id}

Cancel a running task.

Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled"
}

Workflows

POST /workflows/execute

Execute a workflow with optional streaming.

Request Body:

{
  "task": "Fetch weather data and create a report",
  "stream": false
}

Response (Non-streaming):

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "result": null
}

Response (Streaming): Server-Sent Events (SSE) with real-time updates:

data: {"agent": "planner", "step": 1, "status": "planning"}
data: {"agent": "executor", "step": 1, "status": "executing", "action": "web_search"}
data: {"agent": "executor", "step": 2, "status": "executing", "result": "..."}

GET /workflows/{task_id}/status

Get the current status of a workflow.

Response:

{
  "task_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "running",
  "progress": 50,
  "current_agent": "executor"
}

Error Handling

All errors follow this format:

{
  "detail": "Error description",
  "status": 400
}

Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 404 - Not Found
• 500 - Internal Server Error

Rate Limiting

Currently not implemented. For production, consider adding:

• Request rate limits per API key
• Concurrent task limits
• Token usage tracking

Examples

Create and Execute Task

curl -X POST "http://localhost:8000/tasks" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Find information about Python 3.11 release notes"
  }'

Stream Workflow Results

curl -X POST "http://localhost:8000/workflows/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Summarize recent AI breakthroughs",
    "stream": true
  }'

Check Task Status

curl "http://localhost:8000/tasks/550e8400-e29b-41d4-a716-446655440000"

Python Client Example

import requests

API_URL = "http://localhost:8000"

# Create task
response = requests.post(f"{API_URL}/tasks", json={
    "task": "Analyze competitor pricing strategies"
})
task_id = response.json()["task_id"]

# Get status
status_response = requests.get(f"{API_URL}/tasks/{task_id}")
print(status_response.json())

# Stream workflow
with requests.post(f"{API_URL}/workflows/execute", 
                   json={"task": "...", "stream": True}, 
                   stream=True) as response:
    for line in response.iter_lines():
        if line:
            print(line.decode('utf-8'))

Interactive API Documentation

Visit http://localhost:8000/docs for Swagger UI with interactive testing.

Visit http://localhost:8000/redoc for ReDoc documentation.