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.