Hosted vs non-hosted agents

AgentOS supports two integration modes. Which one applies to you determines which SDK methods you use.

---

Non-hosted agents

Your code runs the agent. AgentOS is the observer: it receives reports about what the agent is doing and shows them in the dashboard as runs and events.

Use this when your agent logic lives in your own infrastructure (a server, a Lambda, a cron job, a script). When you create the agent, click I'm connecting an existing agent (SDK) → and pick its Framework (LangChain, CrewAI, AutoGen, OpenAI Assistants, Claude, or Custom).

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

const client = new AgentOS({
  agentId: "your-agent-id",
  apiKey: "aos_agent_...",
});

// Tell AgentOS the run is starting
const run = await client.startRun({ input: { invoiceId: "INV-001" } });

// Your agent logic runs here
const result = await processInvoice("INV-001");
run.emit("invoice.processed", { total: result.total });

// Tell AgentOS the run is done
await run.complete({ output: { processed: true } });

SDK methods used: startRun(), run.emit(), run.complete(), run.fail(), run.cancel(), or withRun(), which completes or fails the run for you. See Reporting runs.

Already instrumented with OpenTelemetry? Send OTLP/JSON traces to /api/ingest/v1/traces instead of using the SDK. See Tracing & spans.

---

Hosted agents

AgentOS runs the agent for you. You define the agent's system prompt, model, and tools in the AgentOS dashboard. Your code calls in with an input and gets the output back.

Use this when you want AgentOS to handle LLM calls, tool routing, and execution, and you just need to trigger the agent and consume its output.

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

const client = new AgentOS({
  agentId: "your-agent-id",
  apiKey: "aos_ws_...",
});

// AgentOS runs the agent and returns the result
const result = await client.invoke({ query: "Summarise the Q1 sales report" });

if (result.status === "completed") {
  console.log(result.output);
} else {
  // Paused for an approval or a question; output is null until it resumes
  console.log(result.status, result.runId);
}

SDK methods used: invoke(), invokeStream(), reply(). See Invoking hosted agents.

Hosted agents also get features that need AgentOS to run the agent: tools, schedules, evals, approvals on gated tools, test runs, and pipelines.

---

Comparison

	Non-hosted	Hosted
Who runs the agent	Your infrastructure	AgentOS
LLM calls	Your code, on your provider account	AgentOS, on your provider key
Primary SDK method	startRun()	invoke()
Schedules, evals, tools, test runs	No	Yes
Use case	Existing agent code you want to observe	Agents built and run inside AgentOS

---

Can I use both?

Yes. A common pattern is a non-hosted orchestrator that reports its own run with startRun() and calls hosted sub-agents with invoke(). Pass the orchestrator's run id as parentRunId (on invoke() or startRun()) to link each child run to it; the dashboard shows them as a tree.

// A workspace key (aos_ws_…) can act for both agents; an agent key is limited to its own agent.
const client = new AgentOS({ agentId: "orchestrator-agent-id", apiKey: "aos_ws_..." });

const run = await client.startRun({ input: { batch: "2026-09" } });
const summary = await client.invoke(
  { query: "Summarise this batch" },
  { agentId: "hosted-agent-id", parentRunId: run.runId },
);
await run.complete({ output: { status: summary.status } });