Docs contents

Quickstart

Get your first agent reporting to AgentOS in under 5 minutes: create an agent, install the SDK, wrap your code, and watch every run, tool call and token.

This quickstart connects an agent that runs in your own code (a non-hosted agent). To have AgentOS run the agent for you instead, see Hosted vs non-hosted.

1. Create an agent

On the Agents page, click New. The Create agent form defaults to a hosted agent, so click I'm connecting an existing agent (SDK) →, give the agent a name, and pick its Framework (LangChain, CrewAI, AutoGen, OpenAI Assistants, Claude, or Custom).

When you click Create agent, AgentOS generates an agent key (aos_agent_…) and shows it once. Copy it now; you can create more keys later on the agent's Keys tab. You'll also need the agent's ID.

2. Install the SDK

npm install @agentos-sdk/core

Using Python? Install pyagentos-sdk and see the Python SDK.

3. Wrap your agent code

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

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

const run = await client.startRun({ input: { query: "Hello" } });

// emit events as your agent works
run.emit("step.started", { step: "fetch-data" });

// complete or fail the run
await run.complete({ output: { result: "Done" } });

Open the agent in your dashboard to see the run and its events.

Hosted agents: add a provider key

Hosted agents run on your own model provider key. Supported providers are Anthropic, OpenAI, Google (Gemini, with a Google AI Studio key), and any OpenAI- or Anthropic-compatible endpoint (with presets for Groq and OpenRouter). An owner or admin adds keys under Backoffice → API Keys → LLM Provider Keys. Non-hosted agents don't need one: your code makes its own model calls.

Next steps