Durable iMessage AI Agent

Durable iMessage AI Agent is an open-source boilerplate template for building a production-ready iMessage AI agent: it receives texts sent to a Sendblue phone number, runs a retryable Vercel Workflow that calls an LLM and tools through the Vercel AI Gateway, and replies back over iMessage — all hosted on Nitro v3 and deployable to Vercel.

What is Durable iMessage AI Agent?

Durable iMessage AI Agent is a starter repository that wires a webhook from Sendblue to a Nitro server, uses the Chat SDK's onNewMention and onSubscribedMessage hooks to enqueue a Vercel Workflow, and executes two retryable steps: generateReply (LLM plus tools) and postReply (send via Sendblue). It takes inbound iMessage webhooks as input and produces outbound iMessage replies. The template runs on Nitro v3 and can be deployed to Vercel or any Node host that supports Nitro. It is written by HugoRCD and released under the Apache 2.0 license.

Key Features

This template bundles the core pieces needed for a durable iMessage agent: retryable workflows, a model gateway, tool support, webhook-based messaging, and structured logging.

• Durable workflow execution — Every inbound message is processed by a Vercel Workflow where the LLM call and the send call are separate retryable steps, so a transient error in either never drops the message.
• Model-agnostic LLM layer — Uses the Vercel AI SDK generateText with the AI Gateway; switching models is one constant change (examples include google/gemini-3-flash, anthropic/claude-sonnet-4.5, openai/gpt-4o-mini, and xai/grok-4).
• Tool support with step isolation — Tools defined in server/tools/index.ts with zod input schemas; each tool's execute function uses the 'use step' directive so tool calls are individually retryable and observable.
• Webhook-based iMessage connectivity — Sendblue forwards inbound iMessages as HTTPS webhooks to POST /api/webhooks/sendblue; no gateway listener, no Mac in production, no cron.
• Automatic observability — evlog wide events capture token usage, tool timing, msToFirstChunk, tokensPerSecond, and estimated cost for every AI step; drains are available for Axiom, OTLP, Sentry, PostHog, HyperDX, Datadog, and Better Stack.
• Environment-driven configuration — Five documented env vars (AI_GATEWAY_API_KEY, SENDBLUE_API_KEY, SENDBLUE_API_SECRET, SENDBLUE_FROM_NUMBER, SENDBLUE_WEBHOOK_SECRET) control gateway access, Sendblue credentials, and webhook validation.
• Local and production parity — Run the dev server with pnpm dev and expose it via ngrok for local testing; deploy to Vercel with pnpm dlx vercel and update the webhook URL for production.
• Extensible project layout — Clear separation between workflows/reply.ts (orchestration), server/utils/agent-steps.ts (step logic), server/tools/index.ts (tools), and server/plugins/imessage.ts (Chat SDK handlers).

Who is it for?

This template is aimed at developers who want a working, production-shaped iMessage AI agent without building the webhook, workflow, and logging plumbing from scratch.

• Developers building personal AI assistants — they can text their agent and get replies with tools like the included getCurrentTime example.
• Teams prototyping iMessage-based products — the template provides an end-to-end pipeline on the free Sendblue tier before committing to a dedicated number.
• Developers evaluating Vercel Workflow — the project is a minimal, clear example of 'use workflow' and 'use step' orchestration with retryable units.
• Open-source contributors — the repo welcomes contributions to add tools, steps, or observability drains, with contributing guidelines.

What can you do with it?

With the template running, you can text your agent, extend it with tools, swap messaging adapters, and compare models using one constant.

• Build a textable AI assistant — deploy the template, set up the Sendblue webhook, and get an agent that answers iMessages with LLM-generated replies enhanced by tools.
• Extend with custom tools — add a description plus zod inputSchema plus execute function to the tools map, and the agent automatically discovers it on the next message.
• Route messages through Chat SDK adapters — swap chat-adapter-sendblue for chat-adapter-imessage (Photon Enterprise) or chat-adapter-blooio if your messaging provider differs.
• Experiment with model costs — change the single MODEL constant to any AI Gateway-supported model and compare output quality, latency, and evlog-estimated cost.

How does it work?

The message flow: a user texts the Sendblue number → Sendblue posts a webhook to the Nitro endpoint → chat.webhooks.sendblue(request) dispatches to Chat SDK handlers → start(replyToMessage, [thread.id, message.text]) enqueues a workflow → generateReply runs an LLM plus tools loop capped at five steps → postReply sends the final text through Sendblue. Each step is independent and retryable; workflow orchestration stays in a thin 'use workflow' function because workflow functions cannot import Node-only packages like evlog directly.

Pricing

The template is free and open source under Apache 2.0. Running it requires a Sendblue account: the free tier with a shared line supports webhooks, replies to verified contacts, and 10 contact slots; the paid AI Agent plan ($100/mo) provides a dedicated number with higher inbound volume.

FAQ

Do I need a Mac or a gateway listener for this iMessage agent?

No. Sendblue hosts the phone line in the cloud and forwards inbound iMessages as HTTPS webhooks. The template runs on any Node/Nitro host, and production on Vercel requires no persistent listener, no Mac, and no cron.

How do I switch the AI model?

Edit the single MODEL constant in server/utils/agent-steps.ts. Any AI Gateway-supported model slug works, including google/gemini-3-flash, anthropic/claude-sonnet-4.5, openai/gpt-4o-mini, and xai/grok-4. The AI SDK reads AI_GATEWAY_API_KEY from the environment automatically.

What does the free Sendblue tier include?

The free tier provides a shared line with webhook support, replies to verified contacts, and 10 contact slots — enough to demo this template. A paid AI Agent plan ($100/mo) is required for a dedicated number with higher inbound volume.

Can I add custom tools?

Yes. Register a new tool in server/tools/index.ts with a description, a zod inputSchema, and an execute function annotated with 'use step'. The agent picks it up automatically on the next generateText call.

What observability is built in?

Every webhook and workflow step emits a structured evlog wide event. The AI SDK integration automatically captures inputTokens, outputTokens, toolCalls, per-tool timing, msToFirstChunk, tokensPerSecond, and estimatedCost. Events print to the console by default, and you can plug in drains like Axiom, OTLP, Sentry, PostHog, HyperDX, Datadog, or Better Stack.