Aicado Agent API Integration

This document explains how to use the call-an-agent endpoint to invoke an Aicado agent via API and get a response based on user input.


📌 Endpoint Information

  • Method: POST

  • URL:

    <https://run.aicado.ai/api/1.1/wf/call-an-agent?api_token=access_token>
    
  • Content-Type: application/json


🔑 URL Parameters

Parameter
Description

access_token

Özel API erişim anahtarı

Final URL format:

<https://run.aicado.ai/api/1.1/wf/call-an-agent?api_token=YOUR_ACCESS_TOKEN>

🧾 Request Body (JSON)

{
  "agent_id": "AGENT_ID",
  "user_input": "Kullanıcıdan gelen mesaj",
  "system_instructions": "Agent için sistem talimatları",
  "response_webhook_url": ""
}

Field Descriptions:

Field
Description

agent_id

The unique ID of the agent defined in Aicado. It can be found in the Aicado agent editor.

user_input

Natural language input from the user.

system_instructions

System-level instructions that shape the agent’s behavior and response style. If left empty, the instructions defined in the Aicado Agent Editor will be used.

response_webhook_url

(Optional) The webhook URL where the response will be posted. This is useful when using asynchronous tools. If left empty, the response will be returned directly.


✅ Response Structure

Aicado will return a response in the following structure:

{
  "call": {
    "call_id": "1749027897108x743874372478867000",
    "call_status": "success",
    "call_error": null,
    "creation_date": 1749027897114,
    "completion_date": 1749027897143
  },
  "tool": {
    "tool_status": "",
    "tool_name": "",
    "tool_error": null
  },
  "agent": {
    "agent_id": "1749023792510x127939515425357090",
    "agent_status": "completed",
    "agent_output": "{\\"a_points\\": 0, \\"r_points\\": 0, \\"t_points\\": 0, \\"i_points\\": 0, \\"a_report\\": \\"No input provided for analysis.\\", \\"r_report\\": \\"No data to assess for relevance.\\", \\"t_report\\": \\"No testable information supplied.\\", \\"i_report\\": \\"No item to interpret.\\"}"
  },
  "usage": {
    "agent_expense": 0.28734,
    "tool_expense": null,
    "total_expense": 0.28734
  },
  "credit": 643.758554,
  "error": null
}

⚠️ Security and Tips

  • Keep your access_token secure and never expose it on the client side.

  • Use system_instructions to maintain control over the agent's behavior and ensure consistent responses.

  • If you want responses delivered to a webhook, make sure to provide the response_webhook_url parameter.

Last updated

Was this helpful?