Hosted vs non-hosted agents

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

---

Non-hosted agents (most common)

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

Use this when your agent logic lives in your own infrastructure (a server, a Lambda, a cron job, a script).

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()

---

Hosted agents

AgentOS runs the agent for you. You define the agent's system prompt, model, and tools inside the AgentOS dashboard. Your code just calls in with an input and gets 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_agent_...",
});

// AgentOS runs the agent — you get the output back
const { runId, output } = await client.invoke({
  query: "Summarise the Q1 sales report",
});

console.log(output.summary);

SDK method used: invoke()

---

Comparison

	Non-hosted	Hosted
Who runs the agent	Your infrastructure	AgentOS
LLM calls	Your code	AgentOS
Primary SDK method	startRun()	invoke()
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 agent that calls hosted sub-agents via invoke() and reports its own run via startRun().