Agents
Trigger a goal-driven agent to run on demand from your own backend. The run is detached - the call returns immediately, and the agent works its goal in the background. Read the outcome later as a conversation.
bot_type="agent") - the goal-driven, multi-step runners described in Scheduled agents. For a turn-by-turn conversational reply from any agent, use the Chat API instead.
Trigger an agent
| Method & path | Ability |
|---|---|
POST /api/v1/agents/{id}/trigger | agents:trigger |
{id} is the agent's bot id. It must be an Autonomous Agent (bot_type="agent"); triggering an Agent (bot_type="chatbot") is rejected. The agent runs with its own configured goal, prompt, tools, and output settings - see the bot object (agent_goal, max_iterations, timeout_seconds, output_config).
Request body
The body is the event that starts the run. Send whatever your system has, up to 64 KiB. JSON, plain text and form data all work. The agent gets its goal with your event added below it, exactly as you sent it. It reads the event as information about what happened, not as instructions, and keeps following its own goal and instructions. Send an empty body and the agent simply runs its goal, the same as a scheduled run.
413. If the events come from another service, you don't have to relay them through your own code: set up an incoming webhook and the service can start the agent itself.
curl -X POST https://app.hania.ai/api/v1/agents/b1f2c3d4-…/trigger \
-H "Authorization: Bearer $HANIA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"ticket": 4521, "text": "customer cannot log in"}'
Response
A successful trigger returns 202 Accepted - the run has been accepted and started, not finished:
{
"success": true,
"data": {
"conversation_id": "c9a8b7c6-…",
"status": "accepted"
},
"message": "Agent run accepted"
}
Persist the returned conversation_id. The run executes detached, with a 24-hour safety-net deadline, so neither the result nor a run failure appears in this response - both land on that conversation, which you poll for progress and the final outcome. For an agent with Persistent conversation turned on, the id you get back is its existing thread rather than a fresh one. If a run fails before the agent replies, the conversation still gets two messages: the run's goal (with your event) and a short note saying what went wrong.
Errors: 400 when the bot isn't an agent; 413 for a body over 64 KiB; 402 with code INSUFFICIENT_BALANCE, PLAN_LIMIT_REACHED or SERVICE_SUSPENDED when billing blocks the workspace (see errors); 404 when the id doesn't match an active agent in your workspace; 403 when the key lacks the agents:trigger ability, or for the built-in assistant; 409 with code: "RUN_IN_PROGRESS" when the agent's persistent conversation already has a run executing; 500 when the run couldn't be started.
Each trigger starts a new run, and an agent can have several runs at once. An agent with Persistent conversation turned on runs one at a time in it: a trigger while its run is executing returns 409, which just means you're early. A run waiting on a person (an approval, a question or a credential form) isn't executing, so it doesn't block a new one. Wait for the current run to finish, then trigger again, rather than retrying in a tight loop.
Reading the outcome
An agent run surfaces as a conversation with channel=agent. Fetch it with conversations:read:
GET /api/v1/conversations/{conversation_id}- messages and final output, plusstop_reasonandgoal(below).GET /api/v1/conversations/{conversation_id}/trace- the step-by-step execution trace (model turns and tool calls), useful for debugging a run.
By default a run ends on the agent's first complete reply that calls no tool. Two completion settings change that. With goal_tool_enabled on, the agent ends the run by marking the goal complete or blocked. With goal_check_enabled on, a separate step checks the goal against what the tools actually returned during the run, and sends the agent back if something was described but never confirmed. With tracing on, the check appears in the trace as a Goal Completion Check step with its verdict, so a caller reading the trace can see the reasoning behind the outcome. See how a run knows it's done.
Three fields on the conversation tell you how the run ended:
stop_reason(string) says why the last run ended early, in plain words you can show as they are. It's left out when the run ended normally. When the agent marked the goal blocked, it reads "the goal is blocked: …". When the completion check ended the run, it reads "the goal cannot be done: …", "the goal was not met after 8 completion checks with no tool use in between", or "the completion check failed (…)".goal(object) is the record of how the last run was judged. It's left out when both completion settings are off, when the conversation is a live chat, or when a new run hasn't finished yet.output_valid(boolean) isfalsewhen the agent has an output schema and its final output still didn't fit it after the agent's retries. The output is delivered as it was written anyway, so check this before passing it on to a system that expects fixed fields. It's left out when the output fit, or when the agent has no output schema.
"goal": {
"outcome": "impossible",
"reason": "The store has no product with that SKU.",
"checks": [
{ "verdict": "incomplete", "reason": "The price was never updated.", "at": "2026-11-07T09:14:02Z" },
{ "verdict": "impossible", "reason": "The store has no product with that SKU.", "at": "2026-11-07T09:15:40Z" }
]
}
outcome appears once the run is judged, and is one of:
achieved- the goal was met.reasonis empty.not_met- the goal wasn't met, for example because the completion check kept sending the agent back, or the check itself failed.impossible- the completion check agreed the goal can't be done with the agent's tools. Only with the check on.blocked- the agent marked the goal blocked, or the run stopped because something kept going wrong, such as a tool that kept failing.reasonsays which.budget_limited- the run ran out of steps, time or tokens, or reached its deadline.reasonsays which.
checks is there only when the completion check is on. It lists every verdict in order, each one complete, incomplete, impossible or error (the check itself failed), with its reason and time.
So a typical flow is: trigger the run, keep the conversation_id from the 202 response, then read that conversation and check stop_reason and goal.
Incoming webhooks
Another service can start an agent without an API key by sending signed events to the agent's webhook URL. You set this up in the dashboard, as described in starting runs from another service. Deliveries use the Standard Webhooks format, so any service that already supports it works as it is. The rest of this section is for when you're writing the sender yourself.
| Method & path | Auth |
|---|---|
POST /webhooks/agents/{id} | Signature |
Signing
Send these three headers with every delivery:
webhook-id- a unique id for the event, up to 255 characters. Use the same id when you retry it.webhook-timestamp- the time you sent it, in Unix seconds. Deliveries more than 5 minutes off from Hania's clock are refused.webhook-signature-v1,followed by the base64 signature. You can send more than one, separated by spaces. One validv1signature is enough.
To sign, take the secret, drop the whsec_ prefix if it has one, and base64-decode the rest. Use that as the key for an HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}, where the body is exactly the bytes you send. When the secret is replaced in the dashboard, the old one keeps working for 24 hours.
Body and event types
The body must be JSON, up to 64 KiB. Its top-level type field is the event type, and the agent only runs for types in its list. A body with no type runs only when the list is *. The agent gets the event the same way as with the API trigger.
Replies
| Case | Status |
|---|---|
The run started. data holds the conversation_id, the same as for the API trigger. | 202 |
The event type isn't in the agent's list, so nothing ran. data.status is "ignored". | 200 |
An event with this webhook-id was already accepted in the last 30 days, so nothing ran. data.status is "duplicate". | 200 |
| The signature is missing or wrong, the timestamp is too old, or the agent has no webhook set up. | 401 |
The body isn't JSON, or the webhook-id is longer than 255 characters. | 400 |
| The body is larger than 64 KiB. | 413 |
| The agent was deleted or turned off, or it's no longer an Autonomous Agent. Stop sending to this URL. | 410 |
More than 60 events a minute for this agent. code is RATE_LIMITED, and Retry-After says how long to wait. | 429 |
The agent has Persistent conversation on and is still busy with a run. code is RUN_IN_PROGRESS. | 429 |
The workspace can't be billed. code is INSUFFICIENT_BALANCE, PLAN_LIMIT_REACHED or SERVICE_SUSPENDED. | 429 |
| Something went wrong on our side. | 500 |
A busy agent and a billing problem both answer 429, which tells the sender to try again later. When it does, the run starts as normal, because a delivery that was turned away isn't counted as received.