Skip to content

Getting Started

This guide will help you quickly integrate with the Agent Controller API.

Prerequisites

  • Network API key (obtained from your administrator)
  • HTTP client and optionally a WebSocket library
  • Basic understanding of REST APIs and WebSocket connections

Step 1: Authentication

All API requests require authentication using a network API key. Include this key in the x-network-api-key header:

x-network-api-key: your-api-key-here

Step 2: Create a Task

Start by creating a new task for a user:

POST /api/v1/external/tasks
Content-Type: application/json
x-network-api-key: your-api-key-here

{
  "user_id": "user123"
}

Response:

{
  "id": "68e78d0dc5a4b19a030d03d6",
  "user_id": "user123",
  "title": "New Task",
  "welcome_message": "Hello! How can I help you today?",
  "followup_suggestions": [
    "What products are you looking for?",
    "Do you need help with specifications?"
  ]
}

Step 3: Send a Message

REST API (Non-streaming)

POST /api/v1/external/message
Content-Type: application/json
x-network-api-key: your-api-key-here

{
  "task_id": "68e78d0dc5a4b19a030d03d6",
  "text": "I'm looking for a built-in microwave with at least 20 liters capacity",
  "context": {
    "url": "https://example.com/products/product_id",
    "lead_details": {
      "customer_type": "residential"
    }
  }
}

WebSocket (Streaming)

Connect to the WebSocket endpoint and send messages:

const ws = new WebSocket('wss://data-services.aui.io/api/ia-controller/api/v1/external/session?network_api_key=your-api-key');

ws.onopen = function() {
  ws.send(JSON.stringify({
    task_id: "68e78d0dc5a4b19a030d03d6",
    text: "I'm looking for a built-in microwave with at least 20 liters capacity",
    context: {
      url: "https://example.com/products/product_id",
      lead_details: {
        customer_type: "residential"
      }
    }
  }));
};

ws.onmessage = function(event) {
  const response = JSON.parse(event.data);
  console.log('Received:', response);
};

Step 4: Handle Responses

Streaming Response Types

  1. Text Content Updates: Real-time text streaming
  2. Final Message: Complete response with product recommendations
  3. Options: Product options with detailed parameters
  4. Follow-up Suggestions: Suggested next questions

Example Streaming Response

{
  "channel": {
    "type": "WEBSOCKET",
    "channel_name": "aeab24b2-a335-4561-976e-40f9c2b7babe",
    "event_name": "thread-message-text-content-updated"
  },
  "scope": {
    "type": "LLM_ACTIVATION_EXECUTION",
    "data": {
      "status": "SUCCESS"
    },
    "context": {
      "message_id": "8a37d5ea-2182-46dc-b2ca-87584e23f227",
      "task_id": "68e78d0dc5a4b19a030d03d6",
      "interaction_id": "68e78d98240f9b18e0f578c8",
      "pillar": "WORKFLOW"
    }
  },
  "data": {
    "text": "I found several built-in microwaves that meet your requirements..."
  },
  "timestamp": "2025-10-09 10:25:31.180051"
}

Error Handling

The Agent Controller API uses consistent error response formats across all endpoints:

Standard Error Responses

401/403 Errors: 

{
  "status_code": 401,
  "errors": ["Unauthorized"]
}

422 Validation Errors: 

{
  "status_code": 422,
  "errors": [
    {
      "loc": ["string", 0],
      "msg": "string",
      "type": "string"
    }
  ]
}

Application Errors (4xx/5xx): 

{
  "status_code": 422,
  "description": "Unprocessable Entity",
  "message": "Workflow execution failed due to policy constraints, please check extra_data for more context",
  "extra_data": {
    "method": "POST",
    "path": "/api/v1/external/message",
    "query": "",
    "workflow_id": "wf_12345",
    "policy_violation": "rate_limit_exceeded"
  }
}

Dynamic Extra Data

The extra_data field is dynamic and its content will differ based on the specific error type and context. Always check this field for additional error details relevant to your specific situation.

Next Steps