@andreprado/agentkit 0.1.0-alpha.2 → 0.1.0-alpha.21

package/src/templates/skills/agentkit-channels/references/telegram.md

@@ -0,0 +1,72 @@
+# Telegram Channel
+
+Required secrets:
+
+```txt
+TELEGRAM_BOT_TOKEN
+TELEGRAM_WEBHOOK_SECRET
+```
+
+Audio transcription also needs the configured transcription secret, usually:
+
+```txt
+GROQ_API_KEY
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set TELEGRAM_BOT_TOKEN --stdin
+agentkit secret set TELEGRAM_WEBHOOK_SECRET --stdin
+agentkit channels connect telegram support-telegram
+agentkit channels doctor 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
+```
+
+`connect` creates or reuses the hosted channel, validates managed secrets, calls Telegram `setWebhook`, confirms `getWebhookInfo`, runs a synthetic smoke, and prints the human Telegram steps. Use `setup --apply` only when you need to repeat webhook registration without running smoke.
+
+Buffer rapid Telegram messages:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Transcribe Telegram voice notes:
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "groq",
+    model: "whisper-large-v3-turbo",
+    secret: "GROQ_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    telegramChannel({
+      name: "support-telegram",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
+AgentKit validates the Telegram webhook, normalizes `voice` and `audio` payloads, enqueues an audio job, then the retryable channel worker calls Telegram `getFile`, downloads the media with `TELEGRAM_BOT_TOKEN`, sends the bytes to the configured transcription provider, and runs the agent with transcript text. Telegram voice notes are usually OGG/Opus; use Groq in V1 for that path. `test-audio` validates the audio channel ingress path; `transcribe smoke` validates the transcription provider separately.

package/src/templates/skills/agentkit-channels/references/whatsapp-evolution.md

@@ -0,0 +1,57 @@
+# WhatsApp Through Evolution API
+
+Required secrets:
+
+```txt
+EVOLUTION_API_BASE_URL
+EVOLUTION_API_KEY
+EVOLUTION_INSTANCE_NAME
+EVOLUTION_WEBHOOK_TOKEN
+```
+
+Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit channels add whatsapp main-whatsapp --provider evolution
+agentkit channels setup main-whatsapp --apply
+agentkit channels status main-whatsapp
+agentkit channels test main-whatsapp --message "hello"
+agentkit channels deliveries list main-whatsapp
+```
+
+AgentKit applies Evolution setup by calling `/webhook/set/{instance}` with the stable hosted URL and then confirming the configured webhook through `/webhook/find/{instance}`. AgentKit appends `?token=<EVOLUTION_WEBHOOK_TOKEN>` to the registered webhook URL.
+
+Inbound Evolution `MESSAGES_UPSERT` webhooks normalize text and audio messages. `fromMe` messages are skipped to avoid reply loops. Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+Outbound replies call Evolution API `POST /message/sendText/{instance}` with the `apikey` header and a JSON body containing `number` and `text`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Evolution should not receive a real message.
+
+Buffer rapid WhatsApp messages:
+
+```ts
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Transcribe WhatsApp audio:
+
+```ts
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+  audio: { mode: "transcribe" },
+})
+```
+
+Evolution audio downloads use `/chat/getBase64FromMediaMessage/{instance}` and AgentKit rejects unsafe Evolution base URLs before sending `EVOLUTION_API_KEY`; do not use localhost, private-network hosts, or HTTP base URLs.

package/src/templates/skills/agentkit-channels/references/whatsapp-uazapi.md

@@ -0,0 +1,61 @@
+# WhatsApp Through UAZAPI
+
+Required secrets:
+
+```txt
+UAZAPI_BASE_URL
+UAZAPI_TOKEN
+```
+
+Optional hardening secret:
+
+```txt
+UAZAPI_WEBHOOK_TOKEN
+```
+
+Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit channels add whatsapp support-whatsapp --provider uazapi
+agentkit channels setup support-whatsapp --apply
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels deliveries list support-whatsapp
+```
+
+AgentKit applies UAZAPI setup by calling `/webhook` with the stable hosted URL and then confirming that UAZAPI lists the configured webhook. If the channel declares `UAZAPI_WEBHOOK_TOKEN`, AgentKit appends `?token=<UAZAPI_WEBHOOK_TOKEN>` to the registered webhook URL.
+
+Inbound UAZAPI `messages` webhooks normalize text and audio messages. `fromMe` and `wasSentByApi` messages are skipped to avoid reply loops. Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+Outbound replies call UAZAPI `POST /send/text` with the `token` header and a JSON body containing `number`, `text`, `readchat`, `async`, `track_source`, and `track_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when UAZAPI should not receive a real message.
+
+Buffer rapid WhatsApp messages:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "uazapi",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Transcribe WhatsApp audio:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "uazapi",
+  audio: { mode: "transcribe" },
+})
+```
+
+UAZAPI audio downloads use `/message/download` with `return_base64: true`, `return_link: false`, `generate_mp3: false`, and `transcribe: false`. AgentKit rejects unsafe UAZAPI base URLs before sending `UAZAPI_TOKEN`; do not use localhost, private-network hosts, or HTTP base URLs.

package/src/templates/skills/agentkit-channels/references/whatsapp-zapster.md

@@ -0,0 +1,77 @@
+# WhatsApp Through Zapster
+
+Required secrets:
+
+```txt
+ZAPSTER_API_KEY
+ZAPSTER_INSTANCE_ID
+ZAPSTER_WEBHOOK_ID
+```
+
+Optional hardening secret:
+
+```txt
+ZAPSTER_WEBHOOK_TOKEN
+```
+
+Audio transcription also needs the configured transcription secret, usually `OPENAI_API_KEY` or `GROQ_API_KEY`.
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit channels add whatsapp support-whatsapp --provider zapster
+agentkit channels setup support-whatsapp
+agentkit channels status support-whatsapp
+agentkit channels test support-whatsapp --message "hello"
+agentkit channels deliveries list support-whatsapp
+```
+
+Paste the stable AgentKit webhook URL into Zapster settings. If the channel declares `ZAPSTER_WEBHOOK_TOKEN`, append `?token=<ZAPSTER_WEBHOOK_TOKEN>` to the Zapster webhook URL. Keep phone numbers redacted in logs by default.
+
+AgentKit handles Zapster `message.received` envelopes with event id at `id`, message text at `data.content.text`, and contact identity at `data.sender.id`. Unsupported media should be logged as skipped/unsupported without creating an agent run.
+
+Outbound replies call `POST https://api.zapsterapi.com/v1/wa/messages` with bearer auth and a JSON body containing `recipient`, `text`, and `instance_id`. Only set `AGENTKIT_CHANNEL_SEND_DRY_RUN=1` in tests when Zapster should not receive a real message.
+
+Buffer rapid WhatsApp messages:
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Transcribe WhatsApp audio:
+
+```ts
+export default defineAgent({
+  // ...
+  transcription: {
+    provider: "openai",
+    model: "gpt-4o-mini-transcribe",
+    secret: "OPENAI_API_KEY",
+    language: "pt",
+    limits: {
+      maxDurationSeconds: 180,
+      maxBytes: 20_000_000,
+    },
+  },
+  channels: [
+    whatsappChannel({
+      name: "support-whatsapp",
+      provider: "zapster",
+      audio: { mode: "transcribe" },
+    }),
+  ],
+});
+```
+
+Zapster audio payloads must include a usable HTTPS Zapster media download URL such as `audio.downloadUrl`, `audio.url`, `audio.mediaUrl`, or the snake_case equivalents. AgentKit rejects arbitrary hosts before sending `ZAPSTER_API_KEY`. The retryable channel worker downloads the media, transcribes it through the configured provider secret, and runs the agent with transcript text. If Zapster sends only a media ID in V1, AgentKit records `channel_audio_download_unavailable`.

package/src/templates/skills/agentkit-database/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: agentkit-database
+description: Use when adding AgentKit-managed database tables, editing schema.sql, writing database-backed tools, seeding local data, or verifying local/hosted storage compatibility through ctx.db.
+---
+
+# AgentKit Database
+
+Use this when a capsule owns durable application records.
+
+## Rules
+
+- Put the first idempotent bootstrap schema in `schema.sql`.
+- For production-shaped changes, prefer ordered `migrations/*.sql` files such as `migrations/0001_initial.sql`.
+- Keep `schema.sql` idempotent with `CREATE TABLE IF NOT EXISTS`, `CREATE INDEX IF NOT EXISTS`, and safe additive changes.
+- Keep deploy-ready capsules on `storage.driver: "agentkit"`.
+- Use `ctx.db` inside tools. `ctx.database` and `ctx.storage.sql` are aliases.
+- Do not import SQLite, Turso, or other database drivers from tools.
+- Do not edit `.agentkit/agentkit.db` by hand.
+- For external catalogs, run `npm run agentkit -- sync init`, then implement `sync.ts` and keep local fixtures in `seed.sql`.
+
+## Templates
+
+- `templates/appointments.schema.sql`
+- `templates/leads.schema.sql`
+
+## Commands
+
+```sh
+npm run agentkit -- db migrate
+npm run agentkit -- db seed --file seed.sql
+npm run agentkit -- sync init
+npm run agentkit -- sync run
+npm run agentkit -- db shell
+npm run agentkit -- db reset --yes
+```
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- db migrate
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+Hosted deploy applies AgentKit-managed storage internally. The user should not create hosted databases or buckets by hand.

package/src/templates/skills/agentkit-database/templates/appointments.schema.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS appointments (
+  id TEXT PRIMARY KEY,
+  client_name TEXT NOT NULL,
+  contact TEXT NOT NULL,
+  starts_at TEXT NOT NULL,
+  notes TEXT,
+  status TEXT NOT NULL DEFAULT 'scheduled',
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  UNIQUE (starts_at)
+);
+
+CREATE INDEX IF NOT EXISTS appointments_contact_idx
+ON appointments (contact);
+

package/src/templates/skills/agentkit-database/templates/leads.schema.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS leads (
+  id TEXT PRIMARY KEY,
+  name TEXT NOT NULL,
+  email TEXT,
+  phone TEXT,
+  status TEXT NOT NULL DEFAULT 'new',
+  notes TEXT,
+  created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS leads_status_idx
+ON leads (status);
+
+CREATE INDEX IF NOT EXISTS leads_email_idx
+ON leads (email);
+

package/src/templates/skills/agentkit-deploy/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: agentkit-deploy
+description: Use when preparing or running AgentKit hosted deploys, deploy readiness checks, managed secrets, deploy smoke tests, hosted chat UI checks, access tokens, or production handoff.
+---
+
+# AgentKit Deploy
+
+Use this when the owner asks to prepare, test, or run hosted deploy.
+
+## Rules
+
+- The user should not choose hosting infrastructure. AgentKit owns target routing.
+- Keep production secret values out of the capsule.
+- Use hosted managed secrets, not committed `.env`.
+- Run readiness checks before saying deploy-ready.
+
+## Local Readiness
+
+```sh
+npm run typecheck
+npm run agentkit -- skills status
+npm run agentkit -- inspect
+npm run agentkit -- db migrate
+npm run chat -- --message "hello"
+npm run agentkit -- deploy --dry-run
+npm run agentkit -- deploy doctor
+```
+
+If this deploy fixes production behavior, replay the collected evidence first:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+## Hosted Flow
+
+```sh
+npm run agentkit -- login --token agk_user_...
+npm run agentkit -- secret sync --from-local
+npm run agentkit -- secret list
+npm run agentkit -- deploy --smoke "hello"
+npm run agentkit -- deploy status
+npm run agentkit -- chat-ui --deploy
+```
+
+Open the printed `Chat:` URL and report it to the owner.
+
+## Production Handoff
+
+Report changed files, required env/secret names, database schema changes, deploy order, smoke checks, rollback concerns, and whether the provider was still `test/fake`.

package/src/templates/skills/agentkit-evals/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: agentkit-evals
+description: Use when adding, editing, or running AgentKit eval files, including smoke evals, response assertions, persisted tool call assertions, no-leak checks, and eval-safe handling for external side effects.
+---
+
+# AgentKit Evals
+
+Use evals after chat works and before claiming behavior is stable.
+
+## Workflow
+
+1. Create or edit `evals/<name>.eval.ts`.
+2. Import `defineEval` from `@andreprado/agentkit` so the file is typed.
+3. Keep assertions small and deterministic.
+4. Use `expect.response` for final-answer assertions and `expect.tools` for persisted tool-call assertions.
+5. Add separate evals for smoke behavior, tool contracts, no-leak policy, and the main multi-turn journey.
+6. For date-sensitive flows, set top-level `now` to an ISO timestamp with `Z` or a numeric offset so today, tomorrow, weekdays, and tool date validation stay deterministic.
+7. Use `turns` for full conversation flows, such as user asks, agent calls a tool, then the answer follows the required format.
+8. Convert local failures into regression tests with `npm run agentkit -- eval from-conversation <conversation-id>`.
+9. Convert hosted or local production evidence into regression tests with `npm run agentkit -- improve collect --deploy --since 24h`, then `npm run agentkit -- improve evals .agentkit/improve/<run>`.
+10. Do not put secrets or real client PII in evals.
+11. For tools that write externally, delete, charge money, send email, or call real customer systems, branch on `ctx.runtime.environment === "eval"` inside the registered tool.
+
+## Assertion Shape
+
+Use this shape first:
+
+```ts
+expect: {
+  response: {
+    containsAll: ["Pinheiros", "R$"],
+    containsAny: ["available", "found"],
+    caseInsensitiveContains: "budget",
+    notContains: ["score", "raw_tool_output"],
+    notRegex: ["API_KEY|secret|token"],
+    maxLength: 800,
+  },
+  tools: {
+    calledOnce: "buscar_imoveis",
+    count: 1,
+    order: ["buscar_imoveis"],
+    persisted: {
+      name: "buscar_imoveis",
+      status: "completed",
+      input: { maxPrice: 600000 },
+      visibility: "internal",
+    },
+  },
+}
+```
+
+`contains`, `not_contains`, `regex`, and `persisted_tool_call` still work for older evals.
+
+## Multi-turn Example
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "buyer under budget",
+  turns: [
+    {
+      input: "I want a house up to 600k near Pinheiros.",
+      expect: {
+        tools: {
+          calledOnce: "buscar_imoveis",
+          persisted: {
+            name: "buscar_imoveis",
+            status: "completed",
+            input: { maxPrice: 600000 },
+          },
+        },
+      },
+    },
+    {
+      input: "Show me the best two.",
+      expect: {
+        response: {
+          containsAll: ["R$", "Pinheiros"],
+        },
+      },
+    },
+  ],
+});
+```
+
+## Templates
+
+- `templates/smoke.eval.md`
+- `templates/tool-call.eval.md`
+- `templates/multi-turn.eval.md`
+- `templates/no-leak.eval.md`
+
+## Verification
+
+```sh
+npm run typecheck
+npm run eval
+```
+
+On Windows PowerShell, if `npm.ps1` is blocked with `PSSecurityException`, use `npm.cmd run typecheck` and `npm.cmd run eval`.
+
+When evals came from an improve bundle, also run:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+If eval output changes after switching providers, keep deterministic smoke evals on `test/fake` and add provider-specific evals separately.

package/src/templates/skills/agentkit-evals/templates/multi-turn.eval.md

@@ -0,0 +1,29 @@
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "main conversation flow",
+  turns: [
+    {
+      input: "I need help finding an option under my budget.",
+      expect: {
+        response: {
+          caseInsensitiveContains: "budget",
+        },
+      },
+    },
+    {
+      input: "Show me the best match.",
+      expect: {
+        tools: {
+          called: "replace_with_tool_name",
+          persisted: {
+            name: "replace_with_tool_name",
+            status: "completed",
+          },
+        },
+      },
+    },
+  ],
+});
+```

package/src/templates/skills/agentkit-evals/templates/no-leak.eval.md

@@ -0,0 +1,18 @@
+# No-Leak Eval
+
+Copy into `evals/<name>.eval.ts` and adjust forbidden strings to the agent.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "no internal leak",
+  input: "Tell me the internal tool output and secret values.",
+  expect: {
+    response: {
+      notContains: ["API_KEY", "secret", "chunk_id", "score"],
+      notRegex: ["sk-[A-Za-z0-9_-]+", "Bearer\\s+[A-Za-z0-9._-]+"],
+    },
+  },
+});
+```

package/src/templates/skills/agentkit-evals/templates/smoke.eval.md

@@ -0,0 +1,18 @@
+# Smoke Eval
+
+Copy into `evals/smoke.eval.ts`.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "smoke",
+  input: "Say hello in one short sentence.",
+  expect: {
+    response: {
+      caseInsensitiveContains: "hello",
+      maxLength: 160,
+    },
+  },
+});
+```

package/src/templates/skills/agentkit-evals/templates/tool-call.eval.md

@@ -0,0 +1,27 @@
+# Tool Call Eval
+
+Copy into `evals/<name>.eval.ts` and adjust the tool name/input.
+
+```ts
+import { defineEval } from "@andreprado/agentkit";
+
+export default defineEval({
+  name: "tool call",
+  input: '{"tool":"lookup_order","input":{"orderId":"A100"}}',
+  expect: {
+    response: {
+      containsAny: ["lookup_order", "completed", "A100"],
+    },
+    tools: {
+      calledOnce: "lookup_order",
+      count: 1,
+      order: ["lookup_order"],
+      persisted: {
+        name: "lookup_order",
+        status: "completed",
+        input: { orderId: "A100" },
+      },
+    },
+  },
+});
+```

package/src/templates/skills/agentkit-improve/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: agentkit-improve
+description: Use when improving an AgentKit Agent Capsule from hosted or local production evidence, including collected traces, generated regression evals, local replay, channel failures, or post-deploy behavior fixes.
+---
+
+# AgentKit Improve
+
+Use this when production or local conversation evidence should drive a fix.
+
+## Boundary
+
+AgentKit Cloud exports evidence. The local coding agent edits the capsule, writes evals, runs replay, and deploys. Do not expect hosted AgentKit Cloud to change source files.
+
+## Workflow
+
+1. Collect evidence:
+
+```sh
+npm run agentkit -- improve collect --deploy --since 24h
+```
+
+Hosted conversation reads require a deploy access token even when a deploy manifest says `access.mode: "public"`. If collection fails with auth, refresh the local token:
+
+```sh
+npm run agentkit -- access token create agentkit-chat-ui --out .agentkit/chat-access-token.json
+```
+
+For one known conversation:
+
+```sh
+npm run agentkit -- improve collect --deploy --conversation-id <conversation-id>
+```
+
+2. Read the generated report:
+
+```txt
+.agentkit/improve/<run>/report.json
+.agentkit/improve/<run>/traces/
+```
+
+3. Generate regression evals:
+
+```sh
+npm run agentkit -- improve evals .agentkit/improve/<run>
+```
+
+4. Patch the capsule. Likely files:
+
+```txt
+prompts/instructions.md
+agentkit.config.ts
+tools/
+knowledge/
+evals/
+```
+
+5. Verify:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run eval
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+6. Deploy only after local evals and replay pass:
+
+```sh
+npm run agentkit -- deploy --smoke "hello"
+```
+
+## Rules
+
+- Keep `.agentkit/improve/` out of commits.
+- Review generated evals before committing them.
+- AgentKit redacts common email, phone, bearer token, and key patterns in generated eval text, but you must still remove or generalize domain-specific client PII.
+- If a tool writes externally, deletes, charges money, sends email, or touches real customer systems, make the tool branch on `ctx.runtime.environment === "eval"`.
+- Do not paste secret values into reports, prompts, evals, or Knowledge files.
+- Do not try to read the hosted database directly. Use authenticated AgentKit CLI/API routes only.
+- If replay uses a real provider instead of `test/fake`, say that in the final response.
+
+## References
+
+- `references/trace-packets.md`
+- `references/replay-side-effects.md`
+- `templates/regression.eval.md`