PacketChatDocs

Agent run API#

Start a published agent from a script or another service and collect its result. A run can execute inside the request, or be queued so that it survives the caller closing the page and the web application restarting.

Before you start#

  • Publish the agent and confirm you can run it in Agents.
  • Obtain an access token for the user the run belongs to. These endpoints accept an Authorization: Bearer token only; a browser session cookie is not enough.
  • Note the agent id from its page in Agents.
  • Keep the worker service running if you intend to queue runs. See Deploy.

Start a run inside the request#

POST /api/agents/{agentId}/runs executes the run and answers when it reaches a terminal state.

curl -fsS -X POST "$BASE_URL/api/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarise the latest release notes"}'

Request fields:

Field Required Purpose
inputText or input Yes The text the agent is run against
async No true queues the run instead of executing it in the request
conversation No true creates a conversation and records the exchange in it
conversationId No Records the exchange in an existing conversation you own

The response is 201 and carries runId, conversationId, status, and outputText. A run that stops for an approval also returns approvalId. A run that fails still returns 201 with status of failed and an error message, so read status rather than relying on the HTTP code alone.

This path runs in the web process, so the reverse proxy request timeout caps it. Use a queued run for work that may take minutes.

Queue a run#

Send "async": true in the body, or the header Prefer: respond-async.

curl -sS -i -X POST "$BASE_URL/api/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input":"Summarise the latest release notes","async":true}'

The response is 202 with runId, conversationId, and a status of queued. The worker executes the run, so it continues after the response is sent and survives a restart of the web application. Exactly one executor takes ownership of a run, so a redelivered or retried job never runs it twice or charges the provider twice.

If Redis cannot accept the job, the attempt is abandoned after five seconds and the web process executes the run itself. The response is the same 202. That run is not durable: restarting the web application before it finishes leaves it unfinished. A poll made soon afterwards still reports running; the run is reported timed_out only by a status read taken more than twenty minutes after it started.

Poll a run#

GET /api/agents/{agentId}/runs/{runId} returns the run with its steps, events, and usage totals.

curl -fsS "$BASE_URL/api/agents/$AGENT_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

GET /api/agents/{agentId}/runs returns your 25 most recent runs for that agent, each with the same status and usage summary.

Statuses:

Status Meaning
queued Accepted, waiting for an executor
running Claimed and executing
waiting_input Stopped at an approval checkpoint
completed Finished with output
failed Ended with an error; error_message explains it
cancelled Ended because an approval was rejected
timed_out Exceeded its execution limit, or the process running it ended

Limits#

  • One run is allowed fifteen minutes of execution.
  • A run that has started and is still running twenty minutes later is marked timed_out by the next status request, with the error code run_abandoned. This is how a run left behind by a restart is closed out.
  • Time spent waiting in the queue does not count towards that limit. A run that is still queued is never failed for waiting, so a backlogged or briefly stopped worker delays runs rather than losing them.
  • Starting a run is limited to RATE_LIMIT_CHAT_PER_MINUTE requests per user over a sliding one-minute window. Agent runs get their own allowance of that size; they do not spend the chat allowance. An over-limit start returns 429 with Retry-After and the X-RateLimit-* headers.
  • Reading a run and listing runs are not rate limited, so polling does not return 429.
  • A run that reaches an approval checkpoint stops there. See Agents and approvals for what happens next.

Verify#

  1. Start a queued run and confirm the response is 202 with a run id.
  2. Poll the run and confirm it moves out of queued and reaches completed.
  3. Confirm the recorded usage names the provider and model you expected.
  4. Restart the web application during a queued run and confirm the run still completes.

If it does not work#

Symptom Check
404 on a valid agent id The agent must have a published version and be shared with the caller.
400 naming providerAccountId or model Re-select the provider account and model on the agent, then publish again.
Run stays queued Confirm the worker service is running and consuming its queues.
Queued run reports timed_out without output The process that held it ended. Check whether the web application restarted while running the fallback path, then start the run again.
401 on every request Use a current access token in the Authorization header; these endpoints do not read the session cookie.