Agents API

Get Agent Details

Retrieve detailed information about a specific agent.

GET /api/v1/agents/{agent_id}
Authorization: Bearer <api_key>

Path Parameters

Activate Agent

Execute an agent with input data and receive results.

POST /api/v1/agents/{agent_id}/activate
Authorization: Bearer <api_key>
Content-Type: application/json

{
    "input_data": {
        "text": "Content to process",
        "options": {
            "mode": "analyze"
        }
    },
    "context_type": "general",
    "metadata": {
        "source": "api_call"
    }
}

Request Body

Response

{
    "activation_id": "activation_456",
    "status": "pending",
    "message": "Agent activation has been created successfully"
}

Response Fields

Get Agent Activations

Retrieve a list of activations for a specific agent.

GET /api/v1/agents/{agent_id}/activations?limit=10
Authorization: Bearer <api_key>

Query Parameters

Get Activation Details

Retrieve details about a specific activation, including results if completed.

GET /api/v1/activations/{activation_id}
Authorization: Bearer <api_key>

Response

{
    "activation_id": "activation_123",
    "status": "completed",
    "input_data": {
        "text": "Content to process",
        "options": {"mode": "analyze"}
    },
    "output_data": {
        "analysis": "Processed analysis results",
        "confidence": 0.95
    },
    "created_at": "2024-01-01T00:00:00Z",
    "completed_at": "2024-01-01T00:01:00Z"
}

Usage Examples

JavaScript/Node.js

// List all agents
async function listAgents() {
    const response = await fetch('http://localhost:5555/api/v1/agents', {
        headers: {
            'Authorization': 'Bearer fw_key_abc123...',
            'Content-Type': 'application/json'
        }
    });

    const data = await response.json();
    return data.agents;
}

// Activate an agent
async function activateAgent(agentId, inputData) {
    const response = await fetch(`http://localhost:5555/api/v1/agents/${agentId}/activate`, {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer fw_key_abc123...',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            input_data: inputData,
            context_type: 'general'
        })
    });

    const activation = await response.json();
    return activation.activation_id;
}

// Check activation status
async function checkActivation(activationId) {
    const response = await fetch(`http://localhost:5555/api/v1/activations/${activationId}`, {
        headers: {
            'Authorization': 'Bearer fw_key_abc123...',
            'Content-Type': 'application/json'
        }
    });

    return await response.json();
}

Python

import requests
import time

API_BASE = 'http://localhost:5555/api/v1'
HEADERS = {
    'Authorization': 'Bearer fw_key_abc123...',
    'Content-Type': 'application/json'
}

def list_agents():
    """List all available agents"""
    response = requests.get(f'{API_BASE}/agents', headers=HEADERS)
    return response.json()['agents']

def activate_agent(agent_id, input_data):
    """Activate an agent with input data"""
    payload = {
        'input_data': input_data,
        'context_type': 'general'
    }

    response = requests.post(
        f'{API_BASE}/agents/{agent_id}/activate',
        headers=HEADERS,
        json=payload
    )

    return response.json()['activation_id']

def wait_for_completion(activation_id, timeout=60):
    """Wait for activation to complete"""
    start_time = time.time()

    while time.time() - start_time < timeout:
        response = requests.get(
            f'{API_BASE}/activations/{activation_id}',
            headers=HEADERS
        )

        activation = response.json()
        status = activation['status']

        if status == 'completed':
            return activation['output_data']
        elif status == 'failed':
            raise Exception(f"Activation failed: {activation.get('error', 'Unknown error')}")

        time.sleep(1)

    raise TimeoutError(f"Activation {activation_id} did not complete within {timeout} seconds")

# Example usage
agents = list_agents()
text_agent = next((a for a in agents if 'text' in a['name'].lower()), None)

if text_agent:
    activation_id = activate_agent(text_agent['id'], {
        'text': 'Analyze this text for sentiment and key topics.'
    })

    result = wait_for_completion(activation_id)
    print(f"Analysis result: {result}")

cURL

# List agents
curl -X GET "http://localhost:5555/api/v1/agents" \
  -H "Authorization: Bearer fw_key_abc123..."

# Activate agent
curl -X POST "http://localhost:5555/api/v1/agents/agent_123/activate" \
  -H "Authorization: Bearer fw_key_abc123..." \
  -H "Content-Type: application/json" \
  -d '{
    "input_data": {
      "text": "Content to analyze"
    },
    "context_type": "general"
  }'

# Check activation status
curl -X GET "http://localhost:5555/api/v1/activations/activation_456" \
  -H "Authorization: Bearer fw_key_abc123..."

Error Handling

The Agents API returns standard HTTP status codes and error messages:

{"detail": "Missing required field: input_data"}

{"detail": "Invalid API key"}

{"detail": "Agent with id 'invalid_agent' not found"}

{"detail": "Rate limit exceeded. Try again in 60 seconds."}

{"detail": "Internal server error occurred during agent activation"}

Next Steps

Explore related API endpoints to build complete applications: