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

package/src/templates/index.ts

@@ -1,4 +1,5 @@
 import { blankTemplate } from "./blank";
+import { dentistaTemplate } from "./dentista";
 import { supportTemplate } from "./support";
 
 export type TemplateFile = {
@@ -17,6 +18,7 @@ export type AgentTemplateContext = {
 
 const templates = new Map<string, AgentTemplate>([
   [blankTemplate.name, blankTemplate],
+  [dentistaTemplate.name, dentistaTemplate],
   [supportTemplate.name, supportTemplate],
 ]);
 

package/src/templates/skills/agentkit-build-agent/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: agentkit-build-agent
+description: Use when the owner gives a natural-language brief for a new or changed AgentKit agent and expects the coding agent to turn it into a working local capsule with prompts, tools, schema, evals, and verification.
+---
+
+# Build An AgentKit Agent
+
+Use this when the owner asks for an agent in plain language.
+
+## Workflow
+
+1. Read `agentkit.config.ts`, `prompts/instructions.md`, `schema.sql`, `evals/`, and existing `tools/`.
+2. If `AGENT_SPEC.md` does not exist, create it from the owner's plain-language request with `npm run agentkit -- spec init --brief "<owner request>"`. If it exists, update it directly before changing behavior.
+3. Infer the first useful local version from the owner's brief and the spec. Do not ask the owner to fill a form.
+4. Edit `prompts/instructions.md` for behavior, boundaries, intake questions, escalation rules, and tool-use policy.
+5. For scheduling, deadlines, reminders, or any relative-date behavior, set `timeZone` in `agentkit.config.ts` to the business/user timezone. AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime; do not hardcode today's date in prompts.
+6. Add tools only when the agent needs action, live data, authorization-sensitive data, or durable writes.
+7. Add database tables to `schema.sql` or ordered `migrations/*.sql` when the agent owns records.
+8. Add `sync.ts` and `seed.sql` with `npm run agentkit -- sync init` when the agent depends on external catalogs or recurring imports.
+9. Add or update evals for the main flow. Prefer multi-turn `turns` evals for real conversations.
+10. Keep the capsule runnable on `test/fake` unless the owner has chosen a real provider.
+
+## Templates
+
+Use these only when they match the brief:
+
+- `templates/support-agent.instructions.md`
+- `templates/appointment-intake.instructions.md`
+- `templates/sales-qualifier.instructions.md`
+
+For prompt-only work, use `skills/agentkit-prompts/SKILL.md`.
+For database-backed tools, use `skills/agentkit-database/SKILL.md`.
+
+## Verification
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+npm run eval
+npm run agentkit -- spec check
+```
+
+If a tool was added:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '<json>'
+```
+
+## Final Response
+
+Summarize the files changed, assumptions made, verification results, and whether the behavior was tested with `test/fake` or a real provider selected by the owner.

package/src/templates/skills/agentkit-build-agent/templates/appointment-intake.instructions.md

@@ -0,0 +1,21 @@
+You are an appointment and intake agent.
+
+Goal:
+- Collect the information needed to understand the request.
+- Offer available times only after checking availability through tools.
+- Confirm the exact date, time, name, and contact details before saving.
+
+Required intake:
+- Full name
+- Contact method
+- Reason for visit
+- Preferred date or time window
+- Any urgency or special constraints
+
+Rules:
+- Interpret today, tomorrow, weekdays, and vague time windows using the AgentKit runtime date context.
+- If the user's scheduling timezone may differ from the business timezone, confirm the timezone before booking.
+- Do not diagnose, promise outcomes, or provide emergency guidance beyond directing urgent cases to appropriate human or emergency support.
+- Do not create, change, or cancel an appointment without explicit user confirmation.
+- Do not invent availability.
+- Use the scheduling tools for availability and writes.

package/src/templates/skills/agentkit-build-agent/templates/sales-qualifier.instructions.md

@@ -0,0 +1,17 @@
+You are a sales qualification agent.
+
+Goal:
+- Understand the user's current situation, urgency, budget range, authority, and desired outcome.
+- Identify whether the lead is a fit for the configured offer.
+- Capture structured lead details through tools when available.
+
+Behavior:
+- Ask one focused question at a time.
+- Avoid pressure and exaggerated claims.
+- Be clear about what is known, unknown, and next.
+- Escalate to a human when the user asks for pricing exceptions, legal terms, procurement details, or custom commitments.
+
+Rules:
+- Do not invent pricing, discounts, case studies, or availability.
+- Do not expose internal lead scores or qualification labels.
+

package/src/templates/skills/agentkit-build-agent/templates/support-agent.instructions.md

@@ -0,0 +1,16 @@
+You are a focused support agent.
+
+Help users resolve the current issue clearly and efficiently.
+
+Behavior:
+- Ask for the minimum missing context needed to help.
+- Use tools when order, account, booking, or case status is needed.
+- Do not invent status, policy, price, or availability.
+- Explain next steps in plain language.
+- Escalate when the request involves billing disputes, safety, legal issues, account ownership, or anything outside the configured tools.
+
+Boundaries:
+- Do not claim to have changed anything unless a tool confirms it.
+- Do not expose internal tool output, IDs, scores, secrets, or logs.
+- If a tool fails, say what could not be verified and ask for a safe next step.
+

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

@@ -0,0 +1,70 @@
+---
+name: agentkit-capsule
+description: Use when working inside an AgentKit Agent Capsule, especially after detecting agentkit.config.ts or when the owner asks to build, change, test, or deploy an AgentKit agent. Routes to task-specific AgentKit skills while avoiding loading the full docs by default.
+---
+
+# AgentKit Capsule
+
+Use this first inside an AgentKit Agent Capsule.
+
+## Start
+
+1. Treat the directory containing `agentkit.config.ts` as the capsule root.
+2. Read `AGENTS.md` or `AGENTKIT.md` for capsule-specific rules.
+3. Run `npm run agentkit -- docs llms` for the lightweight docs router.
+4. Pick one task skill. Do not load `llms-full.txt` unless a task skill or ambiguous framework behavior requires the complete contract.
+
+## Task Routing
+
+- Build or reshape the agent from the owner's brief: `skills/agentkit-build-agent/SKILL.md`
+- Edit prompts: `skills/agentkit-prompts/SKILL.md`
+- Add actions or external data: `skills/agentkit-tools/SKILL.md`
+- Add AgentKit-managed integrations such as managed Composio: `skills/agentkit-integrations/SKILL.md`
+- Add database tables or database-backed tools: `skills/agentkit-database/SKILL.md`
+- Add docs, FAQs, prices, policies, or CSV facts: `skills/agentkit-knowledge/SKILL.md`
+- Switch from `test/fake` to a real model provider: `skills/agentkit-provider/SKILL.md`
+- Add or run evals: `skills/agentkit-evals/SKILL.md`
+- Improve from hosted or local production evidence: `skills/agentkit-improve/SKILL.md`
+- Prepare hosted deploy: `skills/agentkit-deploy/SKILL.md`
+- Work with secrets, external APIs, public access, channels, or real data: `skills/agentkit-security/SKILL.md`
+- Add or debug website, Telegram, WhatsApp, Discord, or Slack channels: `skills/agentkit-channels/SKILL.md`
+- Investigate command failures: `skills/agentkit-troubleshooting/SKILL.md`
+
+For a compact docs map, read `references/docs-router.md`.
+
+## Default Checks
+
+Run these before finishing ordinary capsule work:
+
+```sh
+npm run typecheck
+npm run agentkit -- inspect
+npm run chat -- --message "hello"
+```
+
+If you add a tool, also run:
+
+```sh
+npm run agentkit -- tool <tool_name> --input '{}'
+```
+
+If you change behavior, add or update an eval and run:
+
+```sh
+npm run eval
+```
+
+If the change fixes production behavior, also collect or use an improve bundle and run:
+
+```sh
+npm run agentkit -- replay .agentkit/improve/<run> --against local
+```
+
+## Rules
+
+- Keep `.env`, `.agentkit/`, and `node_modules/` out of commits.
+- Keep secret names in `.env.schema`; keep secret values in ignored `.env` or hosted managed secrets.
+- Keep the first useful version runnable with `test/fake` unless the owner explicitly chooses a real provider.
+- For scheduling or relative-date agents, set `timeZone` in `agentkit.config.ts`; AgentKit injects the current date, weekday, timestamp, and timezone dynamically at runtime.
+- Ask follow-up questions only when missing information blocks a safe local implementation.
+- Tell the owner when testing used `test/fake` instead of a real provider.

package/src/templates/skills/agentkit-capsule/references/docs-router.md

@@ -0,0 +1,15 @@
+# AgentKit Docs Router
+
+Prefer the narrowest source that covers the task.
+
+- Capsule creation and scaffold verification: `docs/guides/create-agent.md`
+- Tools, schemas, secrets, and direct tool tests: `docs/guides/add-tool.md`
+- Knowledge sources, indexing, search, and hosted sync: `docs/guides/add-knowledge.md`
+- Evals and deterministic side-effect guards: `docs/guides/run-evals.md`
+- Safe AgentKit product feedback drafts/submission: `docs/guides/send-feedback.md`
+- Real provider setup: `docs/guides/use-provider.md`
+- Deploy readiness, managed secrets, smoke checks, hosted UI: `docs/guides/prepare-deploy.md`
+- Channels: `docs/guides/add-channel.md`, `connect-discord.md`, `connect-slack.md`, `connect-telegram.md`, `connect-whatsapp-zapster.md`, `debug-channel.md`
+- Security: `docs/guides/security-rules.md`
+
+Use `npm run agentkit -- docs full` only for a complete-contract audit, framework internals, or a behavior not covered by the task guide.

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

@@ -0,0 +1,104 @@
+---
+name: agentkit-channels
+description: Use when adding, connecting, testing, buffering, transcribing audio, or debugging AgentKit website, Telegram, WhatsApp, Discord, or Slack channels, including channel config helpers, provider secrets, webhook setup, channel tests, delivery logs, burst-message buffers, and transcription provider secrets.
+---
+
+# AgentKit Channels
+
+Channels receive user messages. Tools let the agent call external systems. Keep them separate.
+
+## Workflow
+
+1. Add channel helpers in `agentkit.config.ts`.
+2. Keep `runtime: "edge"` and `storage.driver: "agentkit"`.
+3. Deploy before hosted channel creation.
+4. Configure provider secrets as managed secrets.
+5. Connect channel resources through the CLI.
+6. Test, doctor, and inspect delivery logs.
+
+## Audio Transcription
+
+Enable transcription at the agent level and opt in per channel with `audio.mode: "transcribe"`.
+
+```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" },
+    }),
+  ],
+});
+```
+
+V1 providers:
+
+- `openai`: `gpt-4o-mini-transcribe`, `gpt-4o-transcribe`, `whisper-1`; default secret `OPENAI_API_KEY`.
+- `groq`: `whisper-large-v3-turbo`, `whisper-large-v3`, `distil-whisper-large-v3-en`; default secret `GROQ_API_KEY`.
+
+Telegram voice notes are usually OGG/Opus, so use Groq for the default Telegram voice-note path in V1. Zapster audio needs a usable HTTPS Zapster media download URL in the webhook payload; arbitrary hosts are rejected before bearer auth is sent. Hosted channel creation requires the transcription secret automatically when the channel enables transcription. Webhooks only enqueue audio jobs; download and transcription run in the retryable channel worker before the agent run.
+
+Discord channels do not support audio in V1.
+
+## Buffering
+
+Enable `buffer.mode: "debounce"` when clients send several short messages in a row and the agent should answer once.
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Buffered deliveries show `buffered` until AgentKit flushes the conversation buffer into one queued run.
+
+## Commands
+
+```sh
+npm run agentkit -- inspect
+npm run agentkit -- deploy
+npm run agentkit -- channels list
+npm run agentkit -- channels add website website-chat
+npm run agentkit -- channels connect telegram support-telegram
+npm run agentkit -- channels add whatsapp support-whatsapp --provider zapster
+npm run agentkit -- channels connect discord support-discord
+npm run agentkit -- channels connect discord server-discord --mode bot
+npm run agentkit -- channels connect slack support-slack
+npm run agentkit -- channels doctor support-telegram
+npm run agentkit -- channels test support-telegram --message "hello"
+npm run agentkit -- channels test-audio support-telegram --fixture voice-note
+npm run agentkit -- transcribe smoke --provider groq
+npm run agentkit -- channels deliveries list support-telegram
+```
+
+## References
+
+- `references/discord.md`
+- `references/slack.md`
+- `references/telegram.md`
+- `references/whatsapp-zapster.md`
+- `references/channel-buffering.md`
+- `references/channel-debugging.md`
+
+## Safety
+
+Do not paste provider tokens into code, docs, fixtures, prompts, evals, or delivery logs. Webhook URLs are public transport endpoints; authenticity comes from provider validation or channel tokens.

package/src/templates/skills/agentkit-channels/references/channel-buffering.md

@@ -0,0 +1,65 @@
+# Channel Buffering
+
+Use buffering when a client sends several messages in a burst and the agent should answer once.
+
+Config:
+
+```ts
+telegramChannel({
+  name: "support-telegram",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+```ts
+whatsappChannel({
+  name: "support-whatsapp",
+  provider: "zapster",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 2500,
+    maxWaitMs: 12000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+Behavior:
+
+- Buffer scope is one channel conversation.
+- Provider validation and dedupe still run per webhook event.
+- `quietWindowMs` flushes after the client stops sending messages.
+- `maxWaitMs` guarantees a reply even if messages keep arriving.
+- `maxMessages` and `maxChars` cap prompt size and cost.
+- Omit `buffer` or set `buffer: { mode: "off" }` to run the agent once per inbound message.
+
+Debug:
+
+```sh
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
+agentkit channels deliveries list <name>
+agentkit channels deliveries show <delivery-id>
+```
+
+Expected delivery states:
+
+```txt
+buffered
+queued
+running
+agent_completed
+provider_request_built
+provider_sent
+adapter_stubbed
+```

package/src/templates/skills/agentkit-channels/references/channel-debugging.md

@@ -0,0 +1,66 @@
+# Channel Debugging
+
+Start with:
+
+```sh
+agentkit channels list
+agentkit channels status <name>
+agentkit channels doctor <name>
+agentkit channels test <name> --message "hello"
+agentkit channels test-audio <name> --fixture voice-note
+agentkit transcribe smoke --provider groq
+agentkit channels deliveries list <name> --since 24h
+agentkit channels deliveries show <delivery-id>
+agentkit channels buffers list <name>
+agentkit channels buffers show <conversation-id>
+agentkit channels buffers flush <conversation-id>
+agentkit channels buffers clear <conversation-id>
+agentkit channels buffers retry <conversation-id>
+```
+
+Common states:
+
+```txt
+webhook_received
+validated
+duplicate
+audio_received
+audio_downloaded
+transcribing
+transcribed
+buffered
+queued
+running
+agent_completed
+provider_request_built
+provider_sent
+adapter_stubbed
+delivered
+provider_failed
+synthetic_expected_failure
+dead_lettered
+skipped
+```
+
+Common errors:
+
+- `channel_not_found`: webhook URL points to an unknown channel. `channels test` is the official synthetic smoke and should resolve the current `.agentkit/deploy.json` channel.
+- `channel_secret_missing`: required hosted secret is not set.
+- `channel_signature_invalid`: webhook secret, token, origin header, or Discord public key mismatch.
+- Discord bot mode with no deliveries: confirm `--mode bot`, `DISCORD_BOT_TOKEN`, Message Content Intent, server install, and channel permissions for View Channel, Read Message History, and Send Messages.
+- `channel_payload_invalid`: malformed or unsupported provider payload.
+- `channel_event_duplicate`: provider retry; do not create a second run.
+- `audio_received`: audio message was accepted and normalized.
+- `audio_downloaded`: retryable channel worker downloaded provider media into memory.
+- `transcribing`: AgentKit is calling the configured transcription provider.
+- `transcribed`: transcript text was queued for the agent.
+- `channel_audio_download_unavailable`: provider audio payload did not include a usable download URL, or Zapster sent a non-HTTPS/non-Zapster media host.
+- `transcription_secret_missing`: managed transcription secret is missing.
+- `transcription_audio_too_large` or `transcription_audio_too_long`: audio exceeded configured limits.
+- `transcription_audio_format_unsupported`: provider does not accept this audio MIME type or extension.
+- `transcription_provider_unavailable`: retryable transcription provider failure.
+- `channel_limit_exceeded`: backpressure skipped the message.
+- `synthetic_expected_failure`: a synthetic test reached AgentKit, but the provider correctly rejected a fake test recipient.
+- `buffered` delivery state: message is waiting for the channel quiet window or max wait before one coalesced agent run is queued.
+- `adapter_stubbed`: explicit dry-run mode built a provider request but did not call the provider.
+- `provider_sent`: the provider accepted the outbound send and returned a provider message ID.

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

@@ -0,0 +1,93 @@
+# Discord Channel
+
+Discord supports two modes:
+
+- `interactions`: slash commands through the Discord Interactions Endpoint URL.
+- `bot`: normal server messages through a Discord Bot user and Gateway connection.
+
+Use bot mode when the owner asks for the agent to answer without slash commands.
+
+## Slash Commands
+
+Required secret:
+
+```txt
+DISCORD_PUBLIC_KEY
+```
+
+Config:
+
+```ts
+discordChannel({ name: "support-discord" })
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_PUBLIC_KEY --stdin
+agentkit channels connect discord support-discord
+agentkit channels test support-discord --message "hello"
+agentkit channels deliveries list support-discord
+```
+
+Paste the printed webhook URL into the application's Interactions Endpoint URL. Register a slash command with a string option named `message`, `text`, `prompt`, `question`, `query`, or `input`.
+
+## Bot Server Messages
+
+Required secret:
+
+```txt
+DISCORD_BOT_TOKEN
+```
+
+Config:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+})
+```
+
+Commands:
+
+```sh
+agentkit deploy
+agentkit secret set DISCORD_BOT_TOKEN --stdin
+agentkit channels connect discord server-discord --mode bot
+agentkit channels test server-discord --message "hello"
+agentkit channels deliveries list server-discord
+```
+
+In the Discord Developer Portal, open the Bot page, enable Message Content Intent, install the app into the server, and grant the bot `View Channel`, `Read Message History`, and `Send Messages` in the channels it should answer.
+
+Bot mode processes every readable non-bot text message Discord sends over the Gateway. Keep server permissions narrow if the agent should answer only in specific channels.
+
+## Buffering
+
+Buffer rapid Discord messages:
+
+```ts
+discordChannel({
+  name: "server-discord",
+  mode: "bot",
+  buffer: {
+    mode: "debounce",
+    quietWindowMs: 1500,
+    maxWaitMs: 8000,
+    maxMessages: 20,
+    maxChars: 8000,
+  },
+})
+```
+
+## Runtime Behavior
+
+Slash-command mode validates `X-Signature-Ed25519` and `X-Signature-Timestamp` against the raw body and `DISCORD_PUBLIC_KEY`, returns `type: 1` for Discord `PING`, acknowledges slash commands with a deferred response, then sends the final answer as an interaction follow-up.
+
+Bot mode connects to Discord Gateway with `DISCORD_BOT_TOKEN`, requests guild message and message-content intents, ignores bot-authored messages, normalizes `MESSAGE_CREATE`, and sends the final answer through `/channels/<channel_id>/messages`.
+
+All outbound Discord sends use `allowed_mentions: { parse: [] }`. Discord interaction tokens and bot tokens must not appear in delivery, queue, buffer, or doctor API responses.
+
+Discord audio is not supported in V1; do not configure `audio` on `discordChannel`.

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

@@ -0,0 +1,56 @@
+# Slack Channel
+
+Slack uses Events API webhooks.
+
+V1 supports:
+
+- `app_mention` in channels.
+- `message.im` direct messages.
+- Outbound replies through `chat.postMessage`.
+
+V1 does not support Socket Mode, files, audio transcription, app-management automation, or all-channel message listening.
+
+## Required Secrets
+
+```txt
+SLACK_BOT_TOKEN
+SLACK_SIGNING_SECRET
+```
+
+## Config
+
+```ts
+slackChannel({
+  name: "support-slack",
+})
+```
+
+## Commands
+
+```sh
+agentkit deploy
+agentkit secret set SLACK_BOT_TOKEN --stdin
+agentkit secret set SLACK_SIGNING_SECRET --stdin
+agentkit channels connect slack support-slack
+agentkit channels test support-slack --message "hello"
+agentkit channels deliveries list support-slack
+```
+
+## Slack Setup
+
+In Slack app configuration:
+
+1. Basic Information: copy Signing Secret into `SLACK_SIGNING_SECRET`.
+2. OAuth & Permissions: add bot scopes `app_mentions:read`, `im:history`, and `chat:write`.
+3. Install or reinstall the app to the workspace.
+4. Copy the Bot User OAuth Token into `SLACK_BOT_TOKEN`.
+5. Event Subscriptions: enable events and paste the AgentKit webhook URL.
+6. Subscribe to bot events `app_mention` and `message.im`.
+
+## Runtime Behavior
+
+AgentKit verifies `X-Slack-Signature` and `X-Slack-Request-Timestamp` against the raw body before processing events. It rejects stale timestamps, answers `url_verification` with the literal challenge, skips bot/subtype messages, maps channel mentions to Slack threads, maps DMs to the Slack DM channel and user, and replies with `chat.postMessage`.
+
+Outbound Slack text escapes Slack control mentions and disables link-name expansion and unfurls.
+
+Slack audio is not supported in V1; do not configure `audio` on `slackChannel`.

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.