JavaScript SDK

JavaScript SDK

The JavaScript/TypeScript SDK (packages/sdk-js/) provides the same observability capabilities as the Python SDK for Node.js environments. Zero external dependencies — uses native fetch.

Installation

npm install agent-os-sdk

Quick Start

import { AgentOS } from "agent-os-sdk";

const aos = new AgentOS({ apiKey: "your-api-key" });

const result = await aos.trace("my-agent", async (runId) => {
  // your agent logic here
  return { answer: "Hello!" };
});

AgentOS Client

Constructor

import { AgentOS } from "agent-os-sdk";

const aos = new AgentOS({
  apiKey: string,                              // Required
  baseUrl?: string,                            // Default: "https://app.agent-os.dev"
  timeout?: number,                            // Default: 10000 (ms)
});

trace(agentName, fn)

Wraps an async function with automatic run lifecycle events (run_start, run_end, error):

const result = await aos.trace("my-agent", async (runId) => {
  // runId is auto-generated and available for manual events
  await aos.sendEvent({
    eventType: EventType.STEP,
    sdkRunId: runId,
    payload: { node: "search", phase: "start" },
  });

  const output = await doWork();
  return output;
});

• Sends run_start before fn executes
• Sends run_end after fn returns successfully
• Sends error if fn throws (exception is re-thrown)

sendEvent(options)

Send a single event manually:

import { EventType } from "agent-os-sdk";

await aos.sendEvent({
  eventType: EventType.STEP,
  sdkRunId: "run-123",
  payload: { node: "classifier", result: "positive" },
  agentName: "my-agent",  // optional
});

Options:

Parameter	Type	Required	Description
eventType	EventType | string	Yes	Event type to send
sdkRunId	string	Yes	Run identifier
payload	Record<string, unknown>	Yes	Event data
agentName	string	No	Agent name (shown in dashboard)

hitlRequest(sdkRunId, question, context?, channel?)

Signal that the agent is waiting for human input:

await aos.hitlRequest(
  "run-123",
  "Should we deploy to production?",
  { target: "prod", changes: 5 },
  "slack"
);

hitlReceived(sdkRunId, response, respondedBy?)

Signal that human input has been received:

await aos.hitlReceived("run-123", "yes", "tobias");

Event Types

import { EventType } from "agent-os-sdk";

EventType.RUN_START              // "run_start"
EventType.RUN_END                // "run_end"
EventType.STEP                   // "step"
EventType.TOOL_CALL              // "tool_call"
EventType.ERROR                  // "error"
EventType.HUMAN_INPUT_REQUESTED  // "human_input_requested"
EventType.HUMAN_INPUT_RECEIVED   // "human_input_received"

Reliability

• Retries: Failed requests are retried up to 2 times with backoff (500ms, 1000ms)
• Non-blocking: SDK failures are caught and logged via console.warn
• No dependencies: Uses native fetch and crypto.randomUUID
• Timeout: Configurable request timeout with AbortController

Environment Variables

export AGENT_OS_API_KEY="your-api-key"

const aos = new AgentOS({ apiKey: process.env.AGENT_OS_API_KEY! });