Invoking hosted agents

Invoking means asking AgentOS to run a hosted agent and return its output. AgentOS handles the LLM calls, tool routing, and execution — you supply an input and consume the result.

This page is about hosted agents. If your own code runs the agent and you only report what happened, that's the opposite flow — see Reporting runs.

The invoke flow

your call ──▶ run created (status: running)
                │
                ├─ LLM ⇄ tool loop  (each tool call logged as an event)
                │
                ├─ pauses?  ──▶ awaiting_approval  /  awaiting_input   (HTTP 202)
                │                     └─ you approve / answer ─▶ resumes
                │
                └─ done  ──▶ status: completed,  { output }

A run can finish in one request, or pause mid-flight if the agent calls an approval-gated tool (see Approvals) or asks the operator a question (the ask_human tool). A paused invoke returns 202 with the run id — you resume it by approving/answering from the dashboard or API, and the agent continues. See Paused runs.

Ways to invoke

A hosted agent can be triggered from several surfaces. The run's trigger_type records where it came from:

trigger_type is a read-only field recorded on the run — it reflects where the run came from. Callers don't pass it on the invoke endpoint; agent in particular is set by the platform for sub-runs and can't be supplied by a caller.

The rest of this page covers the HTTP / SDK path, which all the others build on.

Basic invoke

import { AgentOS } from "@agentos-sdk/core";

const client = new AgentOS({ agentId: "<agentId>", apiKey: "aos_ws_…" });

const { runId, output } = await client.invoke({ query: "Summarise the Q1 report" });
console.log(output.summary);

Authenticate with a workspace key (aos_ws_…) or an agent key scoped to that agent. See Authentication.

Response

{ "data": { "run_id": "uuid", "output": { "summary": "…" } }, "error": null }

Options

Streaming

Pass stream: true to receive a text/event-stream of progressive events instead of a buffered JSON body — useful for chat UIs.

curl -N -X POST https://agentos-ai.dev/api/v1/agents/<agentId>/invoke \
  -H "Authorization: Bearer aos_ws_…" \
  -H "Content-Type: application/json" \
  -d '{ "input": { "query": "…" }, "stream": true }'

Event types: chunk (token text), tool (a tool call's status), and a terminal done — or awaiting_approval (with approval_id) if the run pauses for approval, or error. Note: a ask_human pause currently resolves the stream as done; use buffered mode if you need to handle awaiting_input distinctly.

Paused runs

If the agent calls an approval-gated tool or ask_human, the buffered invoke returns HTTP 202 with the run id and no output yet:

{ "data": { "run_id": "uuid", "awaiting_approval": { "approval_id": "uuid" }, "output": null }, "error": null }

{
  "data": {
    "run_id": "uuid",
    "awaiting_input": {
      "request_id": "uuid",
      "question": "Which account should I charge?",
      "options": ["Account A", "Account B"]
    },
    "output": null
  },
  "error": null
}

question is always present (show it to your user); options appears only when the agent offered choices.

Resume an approval from /approvals or the API; resume a human-input request by answering it from the run page or the API. The run then continues and reaches completed.

Errors

Same envelope as the rest of the HTTP API:

See the HTTP API reference for the exact endpoint, and Hosted vs non-hosted for when to invoke vs ingest.