@agentos-sdk/core

Official TypeScript SDK for AgentOS — instrument your AI agents with runs, events, and tasks.

The SDK is a thin client over the AgentOS ingest API. Your agent code runs wherever you want; AgentOS observes it.

Install

npm install @agentos-sdk/core
# or
pnpm add @agentos-sdk/core
# or
yarn add @agentos-sdk/core

Quick start

Generate an API key from your agent's page in the AgentOS dashboard, then pick a path:

Calling a hosted agent

For agents you've defined in AgentOS — invoke runs the agent server-side and returns its output:

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

const aos = new AgentOS({
  apiKey: process.env.AGENTOS_API_KEY!,
  agentId: process.env.AGENTOS_AGENT_ID!,
});

const { output } = await aos.invoke({ prompt: "Hello" });
console.log(output);

Instrumenting your own agent

For agents that run in your own code — startRun / emit / complete reports them to AgentOS for observability:

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

const aos = new AgentOS({
  apiKey: process.env.AGENTOS_API_KEY!,
  agentId: process.env.AGENTOS_AGENT_ID!,
});

const run = await aos.startRun({ input: { prompt: "Hello" } });

try {
  run.emit("step.started", { step: 1 });

  // ... do work ...

  run.emit("step.completed", { step: 1, durationMs: 42 });
  await run.complete({ output: { answer: "..." } });
} catch (err) {
  await run.fail({ errorMessage: String(err) });
}

emit(type, payload?, level?) is non-blocking and returns void — events are buffered and flushed on a timer (default 500ms) or when the buffer fills (50 events). Call await run.flush() if you need to be sure pending events are sent before the process exits (e.g. in a Lambda or short-lived script). await run.complete() and await run.fail() flush automatically.

LangChain.js integration

Drop in AgentOSCallbackHandler to mirror LangChain runs into AgentOS automatically:

import { AgentOS } from "@agentos-sdk/core";
import { AgentOSCallbackHandler } from "@agentos-sdk/core/langchain";
import { ChatAnthropic } from "@langchain/anthropic";

const aos = new AgentOS({ apiKey: process.env.AGENTOS_API_KEY!, agentId: "..." });
const run = await aos.startRun();

const model = new ChatAnthropic({
  callbacks: [new AgentOSCallbackHandler(run)],
});

await model.invoke("What's the weather in SF?");
await run.complete();

@langchain/core is an optional peer dependency — only install it if you use the LangChain handler.

Configuration

new AgentOS({
  apiKey: "...",         // required
  agentId: "...",        // required
  baseUrl: "http://localhost:3000",              // optional — defaults to the AgentOS production URL; override for self-hosted or local dev
  batchInterval: 500,    // ms between event flushes
  batchSize: 50,         // max events per batch
  disabled: false,       // no-op the SDK in tests
});

Requirements

• Node.js 18+
• An AgentOS workspace with an agent + API key (sign up)

License

MIT