# AgentSky developer docs

> Agents start here: https://agentsky.dev/start.md

> Long-lived agents over HTTP: /v1 management plus a streaming conversation plane, the sky CLI, and the agent.toml declarative format.

Every page below is also available as markdown at the listed .md URL.
The machine-readable OpenAPI spec is at https://api.agentsky.dev/v1/openapi.json.

## Choose your path

| I want to… | Use | Start here | Not this |
|---|---|---|---|
| Use an agent from my terminal or shell scripts | **CLI / terminal** | [Quickstart](https://agentsky.dev/docs/index.md) | Agent API (overkill for local use) |
| Embed agents in my product — sessions, streaming, history | **Agent API** | [Agent API guide](https://agentsky.dev/docs/agent-api.md) | Gateway (no sessions) |
| Use one AgentSky key instead of separate Anthropic/OpenAI keys | **API Gateway** | [Gateway guide](https://agentsky.dev/docs/gateway.md) | Agent API (not for plain LLM calls) |
| Use agents as tools inside Claude Desktop, Cursor, or any MCP client | **MCP server** | [MCP guide](https://agentsky.dev/docs/mcp.md) | Agent API (MCP client manages the session) |
| Send agents messages from Slack, Telegram, WhatsApp, Discord | **Channels** | [Channels guide](https://agentsky.dev/docs/channels.md) | Agent API (channels handle the webhook routing) |
| Trigger agents on a schedule | **Routines** | [Routines guide](https://agentsky.dev/docs/routines.md) | Agent API (routines handle the cron loop) |

## Get started

- [Choose your path](https://agentsky.dev/docs/overview.md): Pick the right AgentSky integration for what you want to build: CLI/terminal, Agent API, API Gateway, MCP server, Channels, or Routines.
- [Developer quickstart](https://agentsky.dev/docs/index.md): Launch a long-lived agent from your terminal in two commands, then talk to it over a streaming API.
- [Authentication](https://agentsky.dev/docs/authentication.md): API tokens, scopes (read ⊂ write ⊂ admin), sky auth login, and the X-Universe header for workspace isolation.
- [Concepts](https://agentsky.dev/docs/concepts.md): Agents, sessions, events, universes, and billing — the four primitives every API response is built on.

## Use cases

- [Agent API](https://agentsky.dev/docs/agent-api.md): Embed long-lived agents in your product: create agents, start sessions, send messages, and stream responses. Includes advanced topics: idempotency, budgets, interrupts, replay, files, secrets, webhooks, environments.
- [API Gateway](https://agentsky.dev/docs/gateway.md): One AgentSky key in front of the Anthropic and OpenAI wires plus run endpoints: base URLs, model ids, provider routing and failover, cost in the response.
- [MCP server](https://agentsky.dev/docs/mcp.md): Run your AgentSky agents as tools from remote MCP clients: server URL, auth, the tool set, client setup, and a task from start to finish.
- [Channels](https://agentsky.dev/docs/channels.md): Put your agent in Telegram, Slack, Discord, WhatsApp, Microsoft Teams, Lark, and iMessage — one normalized API for connections, threads, and events.
- [Channels quickstart](https://agentsky.dev/docs/channels/quickstart.md): Five minutes from a BotFather token to your agent replying on Telegram, under your bot's identity.
- [Channel routing](https://agentsky.dev/docs/channels/routing.md): Bindings and precedence, webhook mode, re-binding, proactive deliveries, and the hosted connect flow.
- [Channel webhooks](https://agentsky.dev/docs/channels/webhooks.md): The channel event reference — signatures, retries, idempotency, and the SSE mirror for local development.
- [Telegram guide](https://agentsky.dev/docs/channels/guides/telegram.md): Your BotFather bot on the channels API — registration, connect links, and rendering.
- [Slack guide](https://agentsky.dev/docs/channels/guides/slack.md): Your Slack app on the channels API — registration, event URLs, per-agent channels.
- [Discord guide](https://agentsky.dev/docs/channels/guides/discord.md): Your Discord bot on the channels API — we hold the gateway socket for you.
- [Microsoft Teams guide](https://agentsky.dev/docs/channels/guides/teams.md): Your Azure Bot on the channels API — webhook validation, markdown, and conversation-specific connections.
- [WhatsApp guide](https://agentsky.dev/docs/channels/guides/whatsapp.md): Your WhatsApp business number on the channels API, via Meta's Cloud API.
- [Lark guide](https://agentsky.dev/docs/channels/guides/lark.md): Your Lark or Feishu custom or App Store app on the channels API — registration, the events URL, connect codes, and rendering.
- [Buzz guide](https://agentsky.dev/docs/channels/guides/buzz.md): Connect an existing Buzz bot and shared group to an agent.
- [Google Chat guide](https://agentsky.dev/docs/channels/guides/gchat.md): Use your Google Chat app with AgentSky connections and signed events.
- [iMessage guide](https://agentsky.dev/docs/channels/guides/imessage.md): Your Linq iMessage number on the channels API — coming soon.
- [Email guide (AWS SES)](https://agentsky.dev/docs/channels/guides/email.md): Receive and reply to emails through AgentSky using AWS Simple Email Service.
- [LINE guide](https://agentsky.dev/docs/channels/guides/line.md): Connect a LINE Official Account to AgentSky with signed Messaging API events.
- [X (Twitter) channel guide](https://agentsky.dev/docs/channels/guides/x.md): Bring your X developer app: mentions and DMs routed to your agent, webhook CRC handled automatically.

## Advanced

- [Capabilities reference](https://agentsky.dev/docs/capabilities.md): Every built-in capability action agents can call — inputs, outputs, limits, and pricing units for web, image, video, and voice.
- [Skills](https://agentsky.dev/docs/skills.md): Reusable instruction + script bundles your agents load on demand — upload once, attach by reference with pinned revisions, or load straight from a GitHub repo.
- [Routines](https://agentsky.dev/docs/routines.md): Run agents on a schedule — a cron-fired routine starts a fresh session per run or sends a turn into a long-lived session, with per-run budgets, a runs ledger, and webhooks.

## Reference

- [API reference](https://agentsky.dev/docs/api.md): Every /v1 endpoint with schemas, the error contract, and the stream event catalog.
- [CLI reference — sky](https://agentsky.dev/docs/cli.md): Every sky command: auth, launch/deploy, agents and sessions, billing, keys, memory, routines, webhooks, and workspaces.
- [agent.toml reference](https://agentsky.dev/docs/agent-toml.md): The declarative agent file — everything the create wizard can set, in a fly.toml-style file.

## Full content

- [llms-full.txt](https://agentsky.dev/docs/llms-full.txt): every page in one document