# Agents, from your terminal

AgentSky agents are persistent — they keep state, memory, and history for life. The `sky` CLI launches one in two commands; the API is a 202 send plus one standing event stream.

New to AgentSky? [See what you can build with the API and its included browser UI](https://agentsky.dev/docs/overview.md), then launch your first agent below.

## 1. Install and log in

```bash
npm i -g @agentsky/sky
sky auth login          # opens the browser once; CI: set SKY_API_TOKEN
```

Login mints an API token scoped to you (revocable anytime under Developer → API keys). Headless machines use `sky auth login --no-browser`.

## 2. Launch an agent

```bash
cd my-project
sky launch              # scaffolds ./agent.toml, creates the agent, prints its address
```

[agent.toml](https://agentsky.dev/docs/agent-toml.md) is optional — `sky launch` with no file gives you the one-click default (pi). An agent is a reusable spec; `launch` also creates its first **session** (the pod-backed runtime you talk to), which boots on your first message (`--start` boots it now). Edit the file and re-apply with `sky deploy`.

## 3. Talk to it

```bash
sky agent message agent_cmtb2f0a8m9k7x51q4ez6r0d "Summarize the signups from today"   # default session; streams until idle
sky agent chat agent_cmtb2f0a8m9k7x51q4ez6r0d       # interactive REPL
```

Or over HTTP — one origin, one namespace (`https://api.agentsky.dev/v1`). Chat is session-scoped; find the session id with `sky session list agent_…` (or `defaultSessionId` on `GET /v1/agents/agent_…`):

```bash
# send (echoes the event; output never rides this response)
curl -X POST https://api.agentsky.dev/v1/sessions/SESSION_ID/events \
  -H "Authorization: Bearer ast_..." -H "Content-Type: application/json" \
  -d '{"events":[{"type":"user.message","content":[{"type":"text","text":"Summarize the signups from today"}]}]}'

# listen (standing SSE — every turn, every channel, agent-initiated posts)
curl -N https://api.agentsky.dev/v1/sessions/SESSION_ID/stream \
  -H "Authorization: Bearer ast_..."
```

One Q&A = POST the message, read the stream until `session.status_idle` (check its `stop_reason`). Missed events replay from `GET /v1/sessions/SESSION_ID/events` — the list returns the same event objects as the stream; dedupe by event `id`.

## Go deeper

- [API reference](https://agentsky.dev/docs/api.md): every /v1 endpoint, the error contract, and the full stream event catalog.
- [CLI reference](https://agentsky.dev/docs/cli.md): every sky command: auth, launch/deploy, agents and sessions, billing, keys, memory, routines, webhooks, and workspaces.
- [agent.toml](https://agentsky.dev/docs/agent-toml.md): the declarative agent file — everything the create wizard can set.
- [Skills](https://agentsky.dev/docs/skills.md): reusable instruction + script bundles — upload once, attach by reference, pin revisions, or load from a GitHub repo.
- [Routines](https://agentsky.dev/docs/routines.md): run agents on a schedule — cron-fired sessions or turns into a long-lived session, per-run budgets, runs ledger, webhooks.