FAQRelease NotesCommunity

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

PreviousWhite labeling

Last updated

Was this helpful?