Call an agent API

The Call an Agent endpoint allows you to interact with an Aicado agent programmatically. You can send user input, optional instructions, and receive a response either synchronously or asynchronously.

---

Endpoint

POST https://run.aicado.ai/api/1.1/wf/call-an-agent/

---

Authentication

All requests must include an Authorization header with a Bearer token.

Authorization: Bearer <your_access_token>

You can get your access token from Settings section.

---

Request Body

The request must be sent as JSON.

{
  "agent_id": "<agent_id>",
  "instructions": "<instructions>",
  "user_input": "<user_input>",
  "response_webhook_url": ""
}

---

Parameters

Field	Type	Required	Description
agent_id	String	Yes	The unique identifier of the Aicado agent.
instructions	String	No	Additional context or instructions for the agent. If you don't fill this field, the agent instructions comes from agent editor -> settings section.
user_input	String	Yes	The user’s input (e.g., text query, request, or command).
response_webhook_url	String	No	Optional webhook URL for asynchronous responses. Leave empty for sync mode.

---

Example Request

POST https://run.aicado.ai/api/1.1/wf/call-an-agent/
Content-Type: application/json
Authorization: Bearer bus|1751539548390x38855731272

Body:

{
  "agent_id": "1756206481771x7072709",
  "instructions": "Provide a concise summary of the input.",
  "user_input": "10x10 wooden frame",
  "response_webhook_url": ""
}

---

Example Response

{
  "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
}

---

Error Handling

If the request fails, the API will return an error object:

{
  "status": "error",
  "message": "Invalid agent_id"
}

⚡ Notes

• Always include a valid Authorization header.

• If response_webhook_url is provided, the agent response will be sent asynchronously.

• Ensure the agent_id exists and is valid.

Structured Outputs

The Call an Agent endpoint also supports Structured Outputs. This allows you to define the format of the response returned by the agent.

---

How it Works

You can specify the output format in two ways:

1. From the editor – Define the schema visually in the editor.

2. Via API request – Send the schema in the request body as a "text" value.

In both cases, the schema should always be sent in a minified JSON format, for more details check this page

---