@andreprado/agentkit 0.1.0-alpha.23 → 0.1.0-alpha.24

package/docs/guides/add-channel.md

@@ -6,7 +6,7 @@ Add a hosted messaging channel to an Agent Capsule, create the hosted channel re
 
 ## When To Use It
 
-Use this when the agent should receive messages from website chat, Telegram, WhatsApp, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure.
+Use this when the agent should receive messages from website chat, Telegram, WhatsApp, Discord, Slack, or a generic webhook through AgentKit-owned channel infrastructure, or when an inbound channel should reply through another configured channel.
 
 ## Commands
 
@@ -34,16 +34,17 @@ Use `--api <url>` only when the owner gives you a non-default AgentKit Cloud API
 
 ## Files Created Or Edited
 
-- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, or `webhookChannel`.
+- `agentkit.config.ts`: declare channel config with `websiteChannel`, `telegramChannel`, `whatsappChannel`, `discordChannel`, `slackChannel`, `webhookChannel`, or `webhookOutputChannel`.
 - `.agentkit/deploy.json`: written by `agentkit deploy`; used by `agentkit channels ...`.
 - No user Turso tables: AgentKit owns channel resources, dedupe, identities, queue state, and delivery logs.
 - Website channel clients must send `AGENTKIT_WEBSITE_CHANNEL_TOKEN` as `Authorization: Bearer <token>` or `X-AgentKit-Channel-Token`.
-- Generic webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
+- Generic inbound webhook clients must send `AGENTKIT_WEBHOOK_SECRET` as `Authorization: Bearer <token>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature: sha256=<hmac>`.
+- Generic outbound webhook channels send replies to an HTTPS URL stored in a managed secret such as `CRM_CALLBACK_URL`.
 
 ## Minimal Working Example
 
 ```ts
-import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, webhookOutputChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -62,6 +63,7 @@ export default defineAgent({
     discordChannel({ name: "server-discord", mode: "bot" }),
     slackChannel({ name: "support-slack" }),
     webhookChannel({ name: "n8n-webhook" }),
+    webhookOutputChannel({ name: "crm-callback", urlSecret: "CRM_CALLBACK_URL" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -151,7 +153,92 @@ For HMAC auth, compute `HMAC-SHA256(raw JSON body, AGENTKIT_WEBHOOK_SECRET)` and
 X-AgentKit-Webhook-Signature: sha256=<hex digest>
 ```
 
-Generic webhooks are inbound-only in V1. The agent run is queued and delivery logs show the result; AgentKit does not call back into n8n unless the agent has a separate tool that does so.
+Without `replyTo`, generic webhooks are inbound-only: the agent run is queued and delivery logs show the result, but AgentKit does not call back into the source system.
+
+## Reply Through Another Channel
+
+Use `replyTo` when an inbound channel should receive on one transport and answer on another. The source channel still owns webhook validation, dedupe, and queueing; the target channel owns the outbound provider call.
+
+Receive from a generic webhook and answer on WhatsApp:
+
+```ts
+webhookChannel({
+  name: "lead-webhook",
+  replyTo: {
+    channel: "main-whatsapp",
+    recipientFrom: "phone",
+  },
+})
+
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+})
+```
+
+The inbound webhook payload must include the configured recipient field:
+
+```json
+{
+  "event_id": "evt_124",
+  "external_id": "lead_123",
+  "phone": "+15551234567",
+  "message": "please follow up"
+}
+```
+
+`recipientFrom` is a dotted JSON path such as `phone`, `customer.phone`, or `payload.customer.phone`. AgentKit reads it from the raw inbound payload, requires a non-empty scalar value, and formats it for the target channel. Do not use `recipientFrom` for Discord or Slack replies; those require provider-native source identities from their own inbound events.
+
+You can declare multiple webhook inputs by giving each `webhookChannel` a unique name:
+
+```ts
+webhookChannel({ name: "n8n-webhook" })
+webhookChannel({ name: "make-webhook" })
+webhookChannel({ name: "crm-webhook", replyTo: { channel: "main-whatsapp", recipientFrom: "phone" } })
+```
+
+## Generic Output Webhooks
+
+Use `webhookOutputChannel` when the agent should send the final answer to a generic callback URL, such as an internal CRM, n8n callback, Make webhook, or a custom API endpoint.
+
+```ts
+webhookOutputChannel({
+  name: "crm-callback",
+  urlSecret: "CRM_CALLBACK_URL",
+  auth: {
+    type: "bearer",
+    tokenSecret: "CRM_CALLBACK_TOKEN",
+  },
+})
+
+webhookChannel({
+  name: "n8n-webhook",
+  replyTo: {
+    channel: "crm-callback",
+    recipientFrom: "crm_id",
+  },
+})
+```
+
+Set `CRM_CALLBACK_URL` as a managed secret. It must be a public HTTPS URL; AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`, and all auth values come from managed secrets.
+
+Outbound generic webhook requests contain the agent's final text answer:
+
+```json
+{
+  "event_id": "webhook:generic:crm-callback:<conversation-id>",
+  "conversation_id": "<conversation-id>",
+  "channel_id": "crm-callback",
+  "external_identity": "webhook:generic:recipient:acct_123",
+  "message": {
+    "role": "assistant",
+    "content_type": "text",
+    "content": "Thanks, I can help with that."
+  }
+}
+```
+
+Generic output channels do not have public inbound webhook URLs. `agentkit channels test <output-name>` is unsupported because there is no inbound endpoint to smoke.
 
 ## Auto Transcribe Audio
 

package/docs/guides/channel-security.md

@@ -2,11 +2,11 @@
 
 ## Goal
 
-Configure website, Telegram, WhatsApp, Discord, Slack, and generic webhook channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
+Configure website, Telegram, WhatsApp, Discord, Slack, generic inbound webhook channels, and generic outbound webhook channels without leaking secrets, storing raw provider payloads, or treating public webhook URLs as authorization.
 
 ## When To Use It
 
-Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, or prepares a hosted deploy that receives provider webhooks.
+Use this when a coding agent adds or changes channels in an Agent Capsule, enables audio transcription, inspects deliveries, prepares a hosted deploy that receives provider webhooks, or routes replies through another channel.
 
 ## Commands
 
@@ -28,12 +28,15 @@ agentkit channels deliveries show <delivery-id>
 ## Safety Rules
 
 - Public webhook URLs are not permission grants.
-- Keep provider tokens, webhook secrets, bot tokens, transcription keys, and bearer tokens out of source files.
+- Keep provider tokens, webhook secrets, output webhook URLs, bot tokens, transcription keys, and bearer tokens out of source files.
 - Put secret names in `agentkit.config.ts`; put local values in ignored `.env`; upload production values with `agentkit secret set` or `agentkit secret sync`.
 - Do not store raw webhook bodies, raw audio, or provider secret values in tools, prompts, evals, fixtures, or delivery notes.
 - Do not expose Discord interaction tokens or bot tokens. Interaction tokens are reply tokens, not public identifiers.
 - Do not expose Slack bot tokens or signing secrets. Slack signing secrets authenticate webhook origin; Slack bot tokens authorize outbound replies.
 - Do not expose `AGENTKIT_WEBHOOK_SECRET`. Generic webhook clients must authenticate with bearer/header token auth or an HMAC signature over the exact raw body.
+- Do not put generic output webhook URLs or auth values in payloads, prompts, tools, fixtures, or `agentkit.config.ts`. Use `urlSecret` and output auth secret names only.
+- Keep generic output webhook URLs on public HTTPS origins. AgentKit rejects localhost, private network, link-local, and metadata-service hosts before sending.
+- Do not route replies to a channel name from the inbound payload. `replyTo.channel` must be static config, and `recipientFrom` may only select the recipient identifier.
 - Do not remove `EVOLUTION_WEBHOOK_TOKEN` from Evolution WhatsApp webhooks. Evolution provider docs expose webhook delivery setup but no webhook signing-secret contract, so AgentKit requires a secret token query parameter and rejects requests without it.
 - Keep `EVOLUTION_API_BASE_URL` on a public HTTPS origin. AgentKit rejects localhost, private network, link-local, and metadata-service hosts for Evolution outbound and media-download requests.
 - Inspect delivery IDs, hashes, redacted metadata, and statuses instead of raw provider payloads.
@@ -126,6 +129,35 @@ webhookChannel({
 
 AgentKit validates `Authorization: Bearer <secret>`, `X-AgentKit-Webhook-Secret`, or `X-AgentKit-Webhook-Signature` against the raw body before parsing business fields. Payloads must include `event_id` for replay protection. `external_id` is hashed before storage.
 
+Generic output webhooks use managed URL and auth secrets:
+
+```ts
+webhookOutputChannel({
+  name: "crm-callback",
+  urlSecret: "CRM_CALLBACK_URL",
+  auth: {
+    type: "hmac",
+    secret: "CRM_CALLBACK_SIGNING_SECRET",
+  },
+})
+```
+
+The output URL must be a public HTTPS URL stored in `CRM_CALLBACK_URL`. Supported auth modes are `none`, `bearer`, `header`, and `hmac`. For HMAC auth, AgentKit signs the exact JSON callback body and sends `sha256=<digest>` in `X-AgentKit-Webhook-Signature` unless a different `headerName` is configured.
+
+Cross-channel replies use static routing:
+
+```ts
+webhookChannel({
+  name: "lead-webhook",
+  replyTo: {
+    channel: "crm-callback",
+    recipientFrom: "crm_id",
+  },
+})
+```
+
+`replyTo.channel` must name another configured channel. `recipientFrom` is a dotted JSON path into the inbound payload and must resolve to a non-empty string, number, or boolean. It is for recipient identity only; never use inbound data to choose a callback URL, auth secret, or channel name.
+
 Evolution WhatsApp uses a self-hosted API key and an AgentKit webhook token:
 
 ```ts

package/docs/guides/debug-channel.md

@@ -2,11 +2,11 @@
 
 ## Goal
 
-Diagnose website, Telegram, WhatsApp, Discord, Slack, or generic webhook channel setup, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
+Diagnose website, Telegram, WhatsApp, Discord, Slack, generic inbound webhook, generic outbound webhook, cross-channel reply routing, webhook validation, dedupe, buffering, outbound sends, and delivery failures from the Agent Capsule CLI.
 
 ## When To Use It
 
-Use this when a hosted channel is not responding, a provider is retrying messages, audio transcription is failing, or delivery status does not match the user's expectation.
+Use this when a hosted channel is not responding, a provider is retrying messages, audio transcription is failing, cross-channel replies are going to the wrong target, or delivery status does not match the user's expectation.
 
 ## Commands
 
@@ -20,6 +20,7 @@ agentkit transcribe smoke --provider groq
 agentkit channels test <name> --fixture ./fixtures/provider-event.json
 agentkit channels deliveries list <name> --since 24h
 agentkit channels deliveries show <delivery-id>
+agentkit channels deliveries list <reply-target-name> --since 24h
 agentkit channels buffers list <name>
 agentkit channels buffers show <conversation-id>
 agentkit channels buffers flush <conversation-id>
@@ -70,6 +71,8 @@ Expected `show` output includes signature status, dedupe key, queue/run state, o
 - Inspect delivery IDs, hashes, statuses, and redacted metadata rather than raw provider payloads.
 - Never paste provider secrets into fixtures or prompts.
 - Treat `adapter_stubbed` as "no outbound provider call happened", not proof that a client received a message. It can mean explicit dry-run mode or an inbound-only channel such as a generic webhook.
+- For `replyTo` routes, inspect the source channel delivery for validation, dedupe, buffer, queue, and agent-run state, then inspect the target channel delivery for the outbound provider result.
+- Generic output webhook channels do not have inbound endpoints. Use `agentkit channels doctor <name>` to inspect secret readiness and inspect target-channel deliveries after a source event triggers the route.
 - Before replaying or flushing buffered conversations, confirm the channel name and conversation ID.
 - Keep local `.env` values ignored and upload hosted production values through AgentKit secret commands.
 
@@ -117,10 +120,19 @@ The provider retried an already-processed event. No second agent run should be c
 The message is accepted and waiting inside a per-conversation channel buffer. It should move to `queued` after the quiet window, max wait, max message count, or max character count.
 
 `adapter_stubbed`:
-The adapter completed without calling an outbound provider. This can happen in explicit dry-run mode or for an inbound-only channel such as a generic webhook.
+The adapter completed without calling an outbound provider. This can happen in explicit dry-run mode or for an inbound-only channel such as a generic webhook without `replyTo`.
 
 `provider_sent`:
-The provider API accepted the outbound request and returned a provider message ID.
+The provider API accepted the outbound request and returned a provider message ID. For cross-channel replies, this status appears on the reply target channel, such as WhatsApp or a generic output webhook.
+
+`channel_reply_target_missing`:
+The source channel has `replyTo.channel`, but the hosted channel resource for that target does not exist in the same deploy. Create or reconnect the target channel, then retry the source event.
+
+`channel_reply_recipient_missing`:
+The route needs a destination identity but `recipientFrom` was missing, resolved to an empty value, or the source identity cannot be reused by the target channel. Check the inbound payload and the configured dotted JSON path.
+
+`channel_reply_target_invalid`:
+The route points to an invalid target, such as an inbound-only generic webhook, or tries to use `recipientFrom` for a provider that requires native source identities such as Discord or Slack.
 
 `channel_limit_exceeded`:
 Backpressure skipped the message before queueing.

package/docs/llms-full.txt

@@ -372,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, webhookChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
+import { defineAgent, discordChannel, slackChannel, telegramChannel, webhookChannel, webhookOutputChannel, whatsappChannel, websiteChannel } from "@andreprado/agentkit";
 
 export default defineAgent({
   name: "support-agent",
@@ -390,6 +390,7 @@ export default defineAgent({
     discordChannel({ name: "server-discord", mode: "bot" }),
     slackChannel({ name: "support-slack" }),
     webhookChannel({ name: "n8n-webhook" }),
+    webhookOutputChannel({ name: "crm-callback", urlSecret: "CRM_CALLBACK_URL" }),
   ],
   access: { mode: "public" },
   storage: { driver: "agentkit" },
@@ -405,6 +406,8 @@ Rules:
 - Do not store channel plumbing in the user's Turso database.
 - Use `buffer.mode: "debounce"` when a channel should coalesce rapid client messages into one agent run.
 - Buffered deliveries show `buffered`, then flush to one `queued` run after `quietWindowMs`, `maxWaitMs`, `maxMessages`, or `maxChars`.
+- Use `replyTo` when an inbound channel should receive on one transport and answer on another configured channel.
+- Use `webhookOutputChannel` when the reply target is a generic HTTPS callback URL stored in a managed secret.
 
 Channel buffer example:
 
@@ -495,6 +498,56 @@ Generic webhook payloads should be canonical JSON:
 
 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`.
 
+Without `replyTo`, generic webhooks are inbound-only and do not call back into the source system. To receive on one channel and answer on another, add a static `replyTo` route:
+
+```ts
+webhookChannel({
+  name: "lead-webhook",
+  replyTo: {
+    channel: "main-whatsapp",
+    recipientFrom: "phone",
+  },
+})
+
+whatsappChannel({
+  name: "main-whatsapp",
+  provider: "evolution",
+})
+```
+
+`recipientFrom` is a dotted JSON path such as `phone`, `customer.phone`, or `payload.customer.phone`. It must resolve to a non-empty scalar in the inbound payload. Do not use `recipientFrom` for Discord or Slack replies because those transports need provider-native source identities.
+
+Multiple webhooks are multiple named channels:
+
+```ts
+webhookChannel({ name: "n8n-webhook" })
+webhookChannel({ name: "make-webhook" })
+webhookChannel({ name: "crm-webhook", replyTo: { channel: "main-whatsapp", recipientFrom: "phone" } })
+```
+
+Generic output webhook channels send the final agent answer to an HTTPS callback URL:
+
+```ts
+webhookOutputChannel({
+  name: "crm-callback",
+  urlSecret: "CRM_CALLBACK_URL",
+  auth: {
+    type: "bearer",
+    tokenSecret: "CRM_CALLBACK_TOKEN",
+  },
+})
+
+webhookChannel({
+  name: "n8n-webhook",
+  replyTo: {
+    channel: "crm-callback",
+    recipientFrom: "crm_id",
+  },
+})
+```
+
+`CRM_CALLBACK_URL` and output auth values are managed secrets only. The URL must be public HTTPS; AgentKit rejects localhost, private network, link-local, and metadata-service hosts. Supported output auth modes are `none`, `bearer`, `header`, and `hmac`. Generic output channels do not have public inbound webhook URLs, so `agentkit channels test <output-name>` is unsupported.
+
 Common channel verification:
 
 ```sh

package/docs/llms.txt

@@ -19,6 +19,7 @@ Task guides:
 - 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`
@@ -28,6 +29,7 @@ Task guides:
 - 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:

package/package.json

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

package/src/cli/commands/channels.ts

@@ -18,11 +18,15 @@ type CloudChannel = {
   type: "website" | "telegram" | "whatsapp" | "discord" | "slack" | "webhook";
   provider: "agentkit" | "telegram" | "zapster" | "meta" | "uazapi" | "evolution" | "discord" | "slack" | "generic";
   mode?: "interactions" | "bot";
+  direction?: "inbound" | "outbound";
   status: string;
   webhook_url: string;
   required_secrets: Array<{ name: string; status: string }>;
   buffer?: AgentChannel["buffer"];
   audio?: AgentChannel["audio"];
+  reply_to?: Extract<AgentChannel, { replyTo?: unknown }>["replyTo"];
+  url_secret?: string;
+  auth?: Extract<AgentChannel, { type: "webhook"; direction: "outbound" }>["auth"];
 };
 
 type CloudDelivery = {
@@ -247,6 +251,12 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     }
 
     if (channel.type === "webhook") {
+      if (channel.direction === "outbound") {
+        console.log("Outbound webhook: configured");
+        console.log(`Next human step: make sure ${channel.url_secret ?? "the webhook URL secret"} is set as a managed secret.`);
+        return;
+      }
+
       const smoke = await runConnectSmoke(() => runChannelSmoke(channel, args.flags.api, args.flags.message));
       printGenericWebhookHumanNextStep(channel);
       if (!smoke) {
@@ -318,7 +328,11 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     } else if (channel.type === "slack") {
       printSlackHumanNextStep(channel);
     } else if (channel.type === "webhook") {
-      printGenericWebhookHumanNextStep(channel);
+      if (channel.direction === "outbound") {
+        console.log("Outbound webhook endpoint: configured from managed secrets.");
+      } else {
+        printGenericWebhookHumanNextStep(channel);
+      }
     } else {
       console.log(`Website endpoint: ${channel.webhook_url}`);
       console.log("Use this endpoint from the AgentKit website client or a signed server-to-server test.");
@@ -361,6 +375,9 @@ export async function handleChannelsCommand(args: ParsedArgs): Promise<void> {
     }
 
     const channel = await resolveCloudChannelByName(first, args.flags.api);
+    if (channel.type === "webhook" && channel.direction === "outbound") {
+      throw new Error("Outbound webhook channels do not have an inbound test endpoint. Test them through a source channel that routes replies to this channel.");
+    }
     const apiUrl = parseCloudApiUrl(args.flags.api);
     const signed = channel.type === "whatsapp" && channel.provider === "evolution" && !args.flags.fixture
       ? await runServerGeneratedChannelTest(channel, apiUrl, args.flags.message)
@@ -511,6 +528,7 @@ async function createHostedChannel(
     ...(localChannel?.limits ? { limits: channelLimitsForApi(localChannel.limits) } : {}),
     ...(localChannel?.buffer ? { buffer: localChannel.buffer } : {}),
     ...(localChannel?.audio ? { audio: localChannel.audio } : {}),
+    ...channelExtraConfigForApi(localChannel),
   };
 
   return cloudPost<{ channel: CloudChannel }>(
@@ -890,6 +908,9 @@ function printChannelStatus(channel: CloudChannel): void {
   if (channel.type === "discord") {
     console.log(`Mode: ${channel.mode ?? "interactions"}`);
   }
+  if (channel.type === "webhook" && channel.direction) {
+    console.log(`Direction: ${channel.direction}`);
+  }
   console.log(`Status: ${channel.status}`);
   if (channel.webhook_url) {
     console.log(`Webhook URL: ${channel.webhook_url}`);
@@ -1230,6 +1251,19 @@ function defaultChannelSecretsForCli(type: string, provider: string, mode?: "int
   return [];
 }
 
+function channelExtraConfigForApi(channel: AgentChannel | null): Record<string, unknown> {
+  if (!channel) {
+    return {};
+  }
+
+  return {
+    ...("direction" in channel && channel.direction ? { direction: channel.direction } : {}),
+    ...(channel.replyTo ? { reply_to: channel.replyTo } : {}),
+    ...("urlSecret" in channel && channel.urlSecret ? { url_secret: channel.urlSecret } : {}),
+    ...("auth" in channel && channel.auth ? { auth: channel.auth } : {}),
+  };
+}
+
 async function readLocalChannelConfig(
   cwd: string,
   type: string,