@andreprado/agentkit 0.1.0-alpha.20 → 0.1.0-alpha.22

package/docs/guides/use-provider.md

@@ -6,7 +6,7 @@ Switch a capsule from the offline `test/fake` provider to a Pi-backed provider.
 
 ## When To Use This
 
-Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, or another supported provider.
+Use this when local fake responses are no longer enough and the agent needs model behavior from OpenRouter, OpenAI, Anthropic, OpenCode Zen, OpenCode Go, or another supported provider.
 
 The coding agent should not choose a real provider automatically. Ask the owner which provider to use, then update the capsule.
 
@@ -87,6 +87,30 @@ secrets: ["OPENROUTER_API_KEY"],
 
 Prefer model ids or aliases listed by the installed Pi SDK when available, such as `~google/gemini-flash-latest`. If an OpenRouter model id is newer than the Pi model registry, AgentKit passes the id through to OpenRouter using Pi's OpenAI-compatible transport with conservative unknown-model metadata. The provider may still reject the request if the id is invalid, inaccessible, or does not support the tools/features the agent uses.
 
+OpenCode Zen:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`. OpenCode Zen uses `OPENCODE_API_KEY`.
+
+OpenCode Go:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`. OpenCode Go also uses `OPENCODE_API_KEY`.
+
 ## UI Verification
 
 After the provider is configured and the local secret is set, test through chat and UI:
@@ -135,7 +159,7 @@ npm run agentkit -- inspect
 
 `provider_model_unsupported`:
 
-For OpenAI or Anthropic, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
+For OpenAI, Anthropic, OpenCode Zen, or OpenCode Go, use a model id known to the installed Pi SDK for that provider. For OpenRouter, prefer a known Pi alias when possible; otherwise a raw OpenRouter model id is passed through and any remaining model error comes from OpenRouter.
 
 Provider returns auth failure:
 

package/docs/llms-full.txt

@@ -60,8 +60,8 @@ agentkit conversations list
 agentkit conversations show <conversation-id>
 agentkit conversations trace <conversation-id> [--deploy]
 agentkit channels list
-agentkit channels add <website|telegram|whatsapp|discord|slack> <name> [--provider zapster|meta] [--mode interactions|bot] [--api <url>]
-agentkit channels connect <website|telegram|whatsapp|discord|slack> <name> [--provider zapster|meta] [--mode interactions|bot] [--api <url>]
+agentkit channels add <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
+agentkit channels connect <website|telegram|whatsapp|discord|slack|webhook> <name> [--provider zapster|meta|uazapi|evolution] [--mode interactions|bot] [--api <url>]
 agentkit channels setup <name> [--apply] [--api <url>]
 agentkit channels status <name> [--api <url>]
 agentkit channels test <name> [--message <text>] [--fixture <path>] [--api <url>]
@@ -161,7 +161,7 @@ Then open the folder in Codex, Claude Code, or another coding agent and ask dire
 Develop an appointment and intake agent for an ophthalmology office.
 ```
 
-The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not wait for a wizard or recipe. AgentKit provides the scaffold and contract; the coding agent implements directly in the capsule.
+The coding agent should infer the first useful version, edit `prompts/instructions.md`, `agentkit.config.ts`, `schema.sql`, `tools/`, and `evals/`, then run the verification commands before finishing. Do not send the owner back to a CLI brief wizard. AgentKit provides the scaffold, contract, and skills; the coding agent implements directly in the capsule from the owner's chat message.
 
 Optional handoff shortcut:
 
@@ -217,6 +217,8 @@ test
 openai
 anthropic
 openrouter
+opencode
+opencode-go
 custom
 ```
 
@@ -227,6 +229,8 @@ test/fake
 openai via Pi SDK
 anthropic via Pi SDK
 openrouter via Pi SDK
+opencode via Pi SDK
+opencode-go via Pi SDK
 ```
 
 `custom` is a reserved config value. It is not implemented as a local provider adapter yet.
@@ -245,7 +249,7 @@ secrets: [],
 
 `test/fake` is deterministic. It is useful for scaffold checks, direct tool checks, and fake-provider evals, but 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, or another supported provider. Do not choose for them. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
+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. After the owner chooses, update `agentkit.config.ts`, `.env.schema`, local secrets, hosted secrets if deploying, then rerun chat/UI checks.
 
 OpenAI example:
 
@@ -270,6 +274,30 @@ If a provider key is missing, the runtime returns `secret_not_found`.
 
 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, and unknown-model cost/capability metadata is not authoritative.
 
+OpenCode Zen example:
+
+```ts
+provider: {
+  name: "opencode",
+  model: "big-pickle",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Zen model id listed by the installed Pi SDK, such as `big-pickle`, `deepseek-v4-flash-free`, `claude-sonnet-4-5`, or `gpt-5.4-mini`.
+
+OpenCode Go example:
+
+```ts
+provider: {
+  name: "opencode-go",
+  model: "deepseek-v4-flash",
+},
+secrets: ["OPENCODE_API_KEY"],
+```
+
+Use an OpenCode Go model id listed by the installed Pi SDK, such as `deepseek-v4-flash`, `deepseek-v4-pro`, `glm-5.1`, `kimi-k2.6`, `minimax-m2.7`, or `qwen3.6-plus`.
+
 ## Knowledge Contract
 
 Knowledge is AgentKit's native retrieval layer for facts the agent should ground in source files. Use it for FAQs, prices, policies, service descriptions, procedures, CSV tables, and reference docs. Do not put secrets, credentials, `.env` contents, or live customer/payment records in Knowledge. Use tools for live or authorization-sensitive data.
@@ -344,7 +372,7 @@ Channels are hosted inbound/outbound conversation transports. They are separate
 Use these helpers in `agentkit.config.ts`:
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -357,9 +385,11 @@ export default defineAgent({
     websiteChannel({ name: "website-chat" }),
     telegramChannel({ name: "support-telegram" }),
     whatsappChannel({ name: "support-whatsapp", provider: "zapster" }),
+    whatsappChannel({ name: "support-uazapi", provider: "uazapi" }),
     discordChannel({ name: "support-discord" }),
     discordChannel({ name: "server-discord", mode: "bot" }),
     slackChannel({ name: "support-slack" }),
+    webhookChannel({ name: "n8n-webhook" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -398,6 +428,8 @@ Useful guides:
 - 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`
 - Debug a channel: `docs/guides/debug-channel.md`
 - Channel security: `docs/guides/channel-security.md`
@@ -417,6 +449,22 @@ ZAPSTER_INSTANCE_ID
 ZAPSTER_WEBHOOK_ID
 ```
 
+UAZAPI WhatsApp required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+```
+
+Evolution API WhatsApp required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
 Discord slash-command required secret:
 
 ```txt
@@ -429,6 +477,24 @@ Discord bot-mode required secret:
 DISCORD_BOT_TOKEN
 ```
 
+Generic webhook required secret:
+
+```txt
+AGENTKIT_WEBHOOK_SECRET
+```
+
+Generic webhook payloads should be canonical JSON:
+
+```json
+{
+  "event_id": "evt_123",
+  "external_id": "customer_123",
+  "message": "hello from n8n"
+}
+```
+
+Use `Authorization: Bearer <AGENTKIT_WEBHOOK_SECRET>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>` where the HMAC is SHA-256 over the exact raw JSON body. The hosted URL is `/channels/<name>/webhook`.
+
 Common channel verification:
 
 ```sh
@@ -436,9 +502,12 @@ agentkit inspect
 agentkit 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 test support-telegram --message "hello"
 agentkit channels test-audio support-telegram --fixture voice-note
@@ -447,7 +516,7 @@ agentkit channels deliveries list support-telegram
 agentkit channels deliveries show <delivery-id>
 ```
 
-`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`.
+`channels connect` creates or refreshes the channel resource, validates secrets, runs provider setup when supported, then runs the official synthetic smoke. `channels setup` is read-only by default. `channels setup <telegram-name> --apply` calls Telegram `setWebhook` and requires `TELEGRAM_BOT_TOKEN` plus `TELEGRAM_WEBHOOK_SECRET`. `channels setup <uazapi-whatsapp-name> --apply` calls UAZAPI `/webhook` and requires `UAZAPI_BASE_URL` plus `UAZAPI_TOKEN`. `channels setup <evolution-whatsapp-name> --apply` calls Evolution API `/webhook/set/{instance}` and requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `EVOLUTION_WEBHOOK_TOKEN`.
 
 Discord slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against `DISCORD_PUBLIC_KEY`, answers signed `PING` requests with `type: 1`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up. Discord bot mode uses `DISCORD_BOT_TOKEN`, Discord Gateway `MESSAGE_CREATE`, Message Content Intent, and `/channels/<channel_id>/messages` bot replies. Discord channels support buffering but do not support `audio` in V1.
 
@@ -456,10 +525,14 @@ Default tests are offline. Real provider smoke tests are opt-in:
 ```sh
 AGENTKIT_RUN_TELEGRAM_CHANNEL_TESTS=1 bun test
 AGENTKIT_RUN_ZAPSTER_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_UAZAPI_CHANNEL_TESTS=1 bun test
+AGENTKIT_RUN_EVOLUTION_CHANNEL_TESTS=1 bun test
 ```
 
 Telegram smoke also requires `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET`, and `AGENTKIT_TELEGRAM_WEBHOOK_URL`.
 Zapster smoke also requires `ZAPSTER_API_KEY`, `AGENTKIT_ZAPSTER_SEND_URL`, and `AGENTKIT_ZAPSTER_TO`.
+UAZAPI smoke also requires `UAZAPI_BASE_URL`, `UAZAPI_TOKEN`, and `AGENTKIT_UAZAPI_TO`.
+Evolution smoke also requires `EVOLUTION_API_BASE_URL`, `EVOLUTION_API_KEY`, `EVOLUTION_INSTANCE_NAME`, and `AGENTKIT_EVOLUTION_TO`.
 
 ## Tool Contract
 
@@ -557,7 +630,7 @@ CREATE TABLE IF NOT EXISTS appointments (
 );
 ```
 
-`schema.sql` is an idempotent bootstrap file in v1. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. AgentKit does not automatically run destructive changes or ordered `migrations/*.sql` yet.
+`schema.sql` is an idempotent bootstrap file. Use `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and only safe additive `ALTER TABLE` statements. Use ordered `migrations/*.sql` for production-shaped schema evolution; `agentkit db migrate` applies unapplied local migrations before `schema.sql`.
 
 Example tool:
 
@@ -786,7 +859,7 @@ tools.order
 tools.persisted
 ```
 
-Import `defineEval` from `@andreprado/agentkit` when writing new evals. `tools.persisted` validates the tool call saved in local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`. `tool_call` and `persisted_tool_call` remain accepted as backwards-compatible aliases, but new evals should use `tools.persisted`.
+Import `defineEval` from `@andreprado/agentkit` when writing new evals. `tools.persisted` validates the tool call saved in the eval run's local SQLite `tool_calls`, not a provider-specific raw response shape. It can be a tool name string or an object with `name`, `input`, `output`, `rendered`, `status`, and/or `visibility`. `tool_call` and `persisted_tool_call` remain accepted as backwards-compatible aliases, but new evals should use `tools.persisted`.
 
 For date-sensitive evals, set top-level `now` to an ISO timestamp with an explicit timezone designator such as `Z` or `-05:00`. AgentKit uses that fixed clock for every turn and tool call in the eval so "today", "tomorrow", and weekdays remain deterministic while normal chat continues to use the real current date.
 
@@ -894,7 +967,7 @@ agentkit deploy smoke --message "hello"
 agentkit chat-ui --deploy
 ```
 
-`agentkit deploy doctor` checks AgentKit Cloud login, hosted deploy entitlement, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, and writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json` for hosted deploys. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production deploys require an account with `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
+`agentkit deploy doctor` checks AgentKit Cloud login, hosted deploy entitlement, online deploy capacity, hosted secrets, local `.env` names that still need `agentkit secret set`, managed Composio API/auth-config readiness by toolkit, and private-access runtime token handling. `agentkit deploy` sends the capsule to AgentKit Cloud, runs the same readiness check automatically before building and uploading, updates the current project deploy slot by default, writes the local chat/UI deploy access token to `.agentkit/chat-access-token.json`, and prints a production handoff with URL, UI command, secret status, database/schema artifact, integration connect commands, smoke status, and the next recommended command. `agentkit deploy --smoke "hello"` deploys and then tests `/v1/chat` with the deploy access token. `agentkit deploy smoke --message "hello"` repeats that smoke against the last local deploy. `agentkit chat-ui --deploy` serves a local UI pointed at the hosted deploy using that token without exposing it to browser code, shows the conversation id and tool calls, and supports starting a new conversation. Use `agentkit conversations trace <conversation-id> --deploy` to pull hosted conversation messages and tool calls from the last deploy. Production deploys require an account with `cloudflare_deploy_alpha` or purchased/manual deploy slots; local commands and dry-run builds do not require login. AgentKit owns infrastructure selection, backend migration, managed secrets, and public URL creation.
 
 The CLI defaults to the hosted AgentKit Cloud API at `https://agentkit-cloud.aibuilders.com.br`. Use `AGENTKIT_CLOUD_API_URL` or `agentkit deploy --api <url>` only when the owner gives you a non-default AgentKit Cloud API URL.
 

package/docs/llms.txt

@@ -24,6 +24,8 @@ Task guides:
 - 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`
 - Follow secret, access, and tool safety rules: `docs/guides/security-rules.md`
@@ -55,9 +57,12 @@ 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"
@@ -90,16 +95,18 @@ 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 wizard or recipe layer: the coding agent edits the capsule directly from the scaffold and contract.
+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, or another supported provider. Do not choose for them.
+`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`:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andreprado/agentkit",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "private": false,
   "type": "module",
   "repository": {