TypeScript SDK

Package: @agentos-sdk/core

Installation

npm install @agentos-sdk/core

AgentOS

The main client. Create one instance per agent.

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

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

Config options

Option	Type	Default	Description
agentId	string	required	Agent ID from the AgentOS dashboard
apiKey	string	required	Agent key (aos_agent_…) from the agent's Keys tab
baseUrl	string	https://agentos-ai.dev	Override for self-hosted instances
batchInterval	number	500	ms between event flushes
batchSize	number	50	Max events per batch
disabled	boolean	false	No-op mode for tests

client.startRun(options?)

Starts a new run and returns a Run object.

const run = await client.startRun({
  input: { query: "Analyse this dataset" },
  triggerType: "sdk", // "manual" | "scheduled" | "webhook" | "sdk"
  externalRunId: "my-internal-id", // optional correlation ID
});

client.invoke(input?, options?)

Calls a hosted agent and waits for its output. Use this when AgentOS is running the agent — not when your own code is the agent.

const { runId, output } = await client.invoke({ query: "Summarise this" });

// With prompt variable overrides
const { runId, output } = await client.invoke(
  { query: "Summarise this" },
  { promptVariables: { TONE: "formal", LANGUAGE: "Spanish" } },
);

---

Run

Returned by startRun(). Tracks a single agent execution.

run.emit(type, payload?, level?)

Emits a custom event. Events are batched and flushed automatically.

run.emit("step.completed", { step: "fetch-data", rows: 42 });
run.emit("warning.detected", { message: "Low confidence" }, "warn");

level defaults to "info". Options: "debug" | "info" | "warn" | "error".

Built-in emit helpers

run.emitLLMRequest(model, prompt, options?)
run.emitLLMResponse(model, response, tokenUsage?)
run.emitToolCall(tool, input?)
run.emitToolReturn(tool, output?)
run.emitToolError(tool, errorMessage)

run.startTask(name, input?)

Creates a task under the run. Returns a Task object.

const task = await run.startTask("parse-pdf", { file: "report.pdf" });
await task.complete({ output: { pages: 12 } });

run.complete(options?)

Marks the run as completed and flushes remaining events.

await run.complete({ output: { summary: "..." } });

run.fail(options)

Marks the run as failed.

await run.fail({
  errorMessage: "API timeout after 3 retries",
  errorDetail: { endpoint: "/ingest", attempts: 3 },
});

run.flush()

Manually flushes the event buffer. Called automatically by complete() and fail().

---

Task

Returned by run.startTask(). Represents a discrete step within a run.

task.complete(options?)

await task.complete({ output: { result: "ok" } });

task.fail(options)

await task.fail({ errorMessage: "Step failed" });

task.skip()

await task.skip();

---

Error types

Class	Code	When thrown
AgentOSAuthError	UNAUTHENTICATED	Invalid or revoked API key
AgentOSValidationError	VALIDATION_ERROR	Bad request payload
AgentOSRateLimitError	RATE_LIMITED	Too many requests
AgentOSError	varies	All other errors