Quickstart (5 Minutes)

Get agent-os running with your LangGraph agent in under 5 minutes. This guide takes you from zero to seeing live events in the dashboard.

Prerequisites

• Python 3.10+ (or Node.js 18+ for the JS SDK)
• A LangGraph, CrewAI, or custom AI agent

Step 1: Create your account

1. Go to agent-os.dev/register and create a free account
2. After registration, you’ll see the onboarding wizard — it auto-creates your first API key
3. Copy your API key — you’ll need it in the next step

Tip

If you already have an account, go to Settings > API Keys to create a new key.

Step 2: Install the SDK

Python

pip install agent-os-sdk

JavaScript

npm install agent-os-sdk

Step 3: Instrument your agent

Python (LangGraph)

from agent_os_sdk import AgentOS

# Initialize with your API key
aos = AgentOS(
    api_key="your-api-key-here",
    base_url="https://app.agent-os.dev"
)

# Wrap your compiled LangGraph graph — that's it!
graph = aos.instrument(compiled_graph, agent_name="my-agent")

# Run as usual — events are sent automatically
result = graph.invoke({"messages": ["Hello, agent!"]})

Python (CrewAI)

from agent_os_sdk import AgentOS, instrument_crew

aos = AgentOS(
    api_key="your-api-key-here",
    base_url="https://app.agent-os.dev"
)

# Wrap your CrewAI crew
instrumented = instrument_crew(aos, crew, agent_name="my-crew")
result = instrumented.kickoff()

JavaScript

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

const aos = new AgentOS({
  apiKey: "your-api-key-here",
  baseUrl: "https://app.agent-os.dev",
});

// Wrap your agent function
const result = await aos.trace("my-agent", async (runId) => {
  // Your agent logic here
  return await yourAgentFunction();
});

cURL (test)

# Send a test event without any SDK
curl -X POST https://app.agent-os.dev/api/ingest \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "run_start",
    "sdk_run_id": "test-run-1",
    "agent_name": "test-agent",
    "payload": {}
  }'

Step 4: Check the dashboard

1. Open your dashboard
2. Your agent run should appear in real-time
3. Click on a run to see the full event timeline

You should see:

• run_start — when your agent started
• step — each LangGraph node execution
• tool_call — any tool invocations
• run_end — when the run completed (with cost and token info)

What happens behind the scenes

Your Agent
    │  aos.instrument(graph)
    │
    ├─► run_start event → Dashboard shows "running"
    ├─► step events → Timeline fills up
    ├─► tool_call events → Tool usage tracked
    └─► run_end event → Status becomes "success", cost calculated

The SDK automatically captures:

• Run lifecycle (start, end, errors)
• Each graph node execution with timing
• Tool calls with input preview
• Token usage and cost (if your LLM returns it)
• Errors with stack traces (truncated to 1000 chars)

Next steps

• Dashboard Guide — Learn about filters, real-time updates, and run details
• Alerts — Set up email or webhook notifications for errors
• Cost Tracking — Monitor token usage and spending
• Human-in-the-Loop — Track when agents wait for human input
• API Reference — Direct API access without the SDK

---

Troubleshooting

401 Unauthorized

Your API key is invalid or missing. Check:

• The key is correct (copy it again from Settings > API Keys)
• The Authorization: Bearer <key> header is set
• The key hasn’t been deleted

429 Too Many Requests

You’ve either:

• Hit the rate limit (200 requests/minute) — wait a moment and retry
• Hit your plan event limit (1,000/month on Free) — check Settings > Plan & Usage

Connection refused / timeout

• Check base_url is correct
• Ensure you can reach the API from your network
• The SDK retries automatically (2 retries with backoff)

Events not appearing in dashboard

• Make sure you’re logged in with the same account that owns the API key
• Check that the run completed (run_end event was sent)
• Hard-refresh the dashboard page (Ctrl+Shift+R)
• Events appear in real-time via WebSocket — if WebSocket is blocked, refresh the page