# AgentKit LLM Index

AgentKit creates and runs Agent Capsules: folders with `agentkit.config.ts`, prompts, tools, evals, local storage, and agent-facing docs.

Read `docs/llms-full.txt` only when you need the whole operating contract.

Task guides:

- Create a capsule: `docs/guides/create-agent.md`
- Add a TypeScript tool: `docs/guides/add-tool.md`
- Add Knowledge from local docs/CSVs: `docs/guides/add-knowledge.md`
- Run or prepare evals: `docs/guides/run-evals.md`
- Improve from production traces: `docs/guides/improve-from-production.md`
- Replay collected traces locally: `docs/guides/replay-production-traces.md`
- Send AgentKit product feedback safely: `docs/guides/send-feedback.md`
- Switch from `test/fake` to a real provider: `docs/guides/use-provider.md`
- Prepare for hosted deploy: `docs/guides/prepare-deploy.md`
- Build Cloudflare artifact: `agentkit build --target cloudflare`
- Build container artifact: `agentkit build --target container`
- Generate VPS handoff: `agentkit deploy --target vps --host agent.example.com --dry-run`
- Add hosted channels: `docs/guides/add-channel.md`
- Route replies across channels or add generic output webhooks: `docs/guides/add-channel.md#reply-through-another-channel`
- Add AgentKit-managed Composio: `docs/guides/add-managed-composio.md`
- Buffer rapid channel messages: `docs/guides/add-channel.md#buffer-bursty-messages`
- Connect Discord: `docs/guides/connect-discord.md`
- Connect Slack: `docs/guides/connect-slack.md`
- Connect Telegram: `docs/guides/connect-telegram.md`
- Connect WhatsApp through Evolution API: `docs/guides/connect-whatsapp-evolution.md`
- Connect WhatsApp through UAZAPI: `docs/guides/connect-whatsapp-uazapi.md`
- Connect WhatsApp through Zapster: `docs/guides/connect-whatsapp-zapster.md`
- Follow channel webhook and delivery-log safety rules: `docs/guides/channel-security.md`
- Debug channel delivery and cross-channel reply routing: `docs/guides/debug-channel.md`
- Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`

Current local commands:

```sh
agentkit new [name] --template blank|support|dentista
agentkit new . --template blank
agentkit new [name] --template blank --no-install
agentkit docs full
agentkit env set <NAME> --stdin
agentkit env list
agentkit env unset <NAME>
agentkit handoff codex|claude [goal]
agentkit chat --message "hello"
agentkit tool <name> --input <path-or-json>
agentkit knowledge add <path-or-url>
agentkit knowledge sync
agentkit knowledge inspect
agentkit knowledge search <query> [--top-k <number>]
agentkit eval run
agentkit improve collect --deploy --since 24h
agentkit improve evals .agentkit/improve/<run>
agentkit replay .agentkit/improve/<run> --against local
agentkit feedback create --about last-run --kind bug --summary "what failed"
agentkit feedback send .agentkit/feedback/<draft>.json
agentkit conversations list
agentkit conversations show <conversation-id>
agentkit conversations trace <conversation-id> [--deploy]
agentkit channels list
agentkit channels add telegram support-telegram
agentkit channels connect whatsapp main-whatsapp --provider evolution
agentkit channels connect whatsapp support-whatsapp --provider uazapi
agentkit channels connect discord support-discord
agentkit channels connect discord server-discord --mode bot
agentkit channels connect slack support-slack
agentkit channels connect webhook n8n-webhook
agentkit channels setup support-telegram
agentkit channels status support-telegram
agentkit channels test support-telegram --message "hello"
agentkit channels test-audio support-telegram --fixture voice-note
agentkit transcribe smoke --provider groq
agentkit channels deliveries list support-telegram
agentkit integrations status [--toolkit googlecalendar]
agentkit integrations connect composio --toolkit gmail
agentkit skills status
agentkit skills sync
agentkit billing checkout --slots 1 --email user@example.com
agentkit billing claim billint_... --secret bsec_...
agentkit login --token agk_user_...
agentkit account token create new-laptop --use
agentkit account token list
agentkit deploy doctor
agentkit deploy --smoke "hello"
agentkit deploy status
agentkit deploy smoke --message "hello"
agentkit chat-ui --deploy
agentkit secret set <NAME> --from-local-env
agentkit secret sync --from-local
agentkit secret list
agentkit access token create website-chat --out .agentkit/website-chat-access-token.json
agentkit access token list
agentkit inspect
agentkit dev
agentkit open
```

On Windows PowerShell, if `npm.ps1` or `npx.ps1` is blocked with `PSSecurityException`, run capsule scripts through the `.cmd` shims, for example `npm.cmd run agentkit -- inspect`, `npm.cmd run agentkit -- knowledge sync`, or `npm.cmd run eval`.

Generated capsules include `AGENTKIT.md`, `AGENTS.md`, and a repo-local `skills/` pack so Codex, Claude Code, or another coding agent can treat the owner's natural-language request as the brief and start building immediately without loading the full contract by default. Start with `skills/agentkit-capsule/SKILL.md`, then load the task skill for the current work. `agentkit handoff codex "Develop an ophthalmology office intake agent"` is an optional prompt-printing shortcut for users who are not already inside a coding-agent workspace. There is no AgentKit CLI wizard in the normal flow: the coding agent edits the capsule directly from the scaffold and contract.

UI testing is part of the handoff. For local UI testing, run `agentkit dev`, open the printed `Chat:` URL, and tell the owner the exact URL. After hosted deploy, run `agentkit chat-ui --deploy`, open the printed `Chat:` URL, and tell the owner it is connected to the deploy.

Hosted Chat UI shows the current conversation id, tool calls, tool errors, and a new-conversation control. Use `agentkit conversations trace <conversation-id> --deploy` to pull the hosted trace from the last deploy.

`test/fake` is deterministic and validates scaffold, direct tool calls, and fake-provider evals. It does not validate natural conversation quality. Before claiming real conversation behavior has been tested, ask the owner which provider to use: OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider. Do not choose for them.

For OpenRouter, prefer model ids or aliases known to the installed Pi SDK, such as `~google/gemini-flash-latest`. If an OpenRouter id is newer than Pi's registry, AgentKit passes the raw id through to OpenRouter with conservative unknown-model metadata; OpenRouter can still reject invalid, inaccessible, or unsupported models.

For OpenCode Zen, use `provider: { name: "opencode", model: "big-pickle" }`. For OpenCode Go, use `provider: { name: "opencode-go", model: "deepseek-v4-flash" }`. Both use `OPENCODE_API_KEY` in `secrets` and `.env.schema`.

AgentKit injects the current ISO timestamp, local date, weekday, local date/time, and timezone dynamically into every chat run. Set `timeZone` in `agentkit.config.ts` for scheduling agents so "today", "tomorrow", and weekdays resolve in the business/user timezone; otherwise AgentKit falls back to `AGENTKIT_TIME_ZONE`, valid `TZ`, then the runtime default. Do not hardcode today's date in prompts.

Current local endpoints from `agentkit dev`:

```txt
GET  /_agentkit
POST /v1/chat
GET  /v1/conversations
GET  /v1/conversations/:id
GET  /v1/conversations/:id/trace
```

Local `.env` is for development only. Use `.env.schema` as the committed secret-name contract; local AgentKit commands load `.env` directly. Hosted deploys require an AgentKit Cloud account with `cloudflare_deploy_alpha` or purchased/manual deploy slots. Use `agentkit billing checkout` + `agentkit billing claim` for first-time paid access, or `agentkit login --token ...` when the user already has an `agk_user_...` token. Production uses managed secrets in the hosted contract.
