Building Durable AI Agents

AI agents are built on the primitive of LLM and tool-call loops, often with additional processes for data fetching, resource provisioning, or reacting to external events.

Workflow DevKit makes your agents production-ready, by turning them into durable, resumable workflows. It transforms your LLM calls, tool executions, and other async operations into retryable, scalable, and observable steps.

This guide walks you through converting a basic AI chat app into a durable AI agent using Workflow DevKit.

Why Durable Agents?

Aside from the usual challenges of getting your long-running tasks to be production-ready, building mature AI agents typically requires solving several additional challenges:

• Statefulness: Persisting chat sessions and turning LLM and tool calls into async jobs with workers and queues.
• Observability: Using services to collect traces and metrics, and managing them separately from your messages and user history.
• Resumability: Resuming streams requires not just storing your messages, but also storing streams, and piping them across services.
• Human-in-the-loop: Your client, API, and async job orchestration need to work together to create, track, route to, and display human approval requests, or similar webhook operations.

Workflow DevKit provides all of these capabilities out of the box. Your agent becomes a workflow, your tools become steps, and the framework handles interplay with your existing infrastructure.

Getting Started

To make an Agent durable, we first need an Agent, which we'll be setting up here. If you already have an app you'd like to follow along with, you can skip this section.

For our example, we'll need an app with a simple chat interface and an API route calling an LLM, so that we can add Workflow DevKit to it. We'll use the Flight Booking Agent example as a starting point, which comes with a chat interface built using Next.js, AI SDK, and Shadcn UI.

git clone https://github.com/vercel/workflow-examples -b plain-ai-sdk
cd workflow-examples/flight-booking-app

GATEWAY_API_KEY=...

npm i @ai-sdk/openai

OPENAI_API_KEY=...

// ...
import { openai } from "@workflow/ai/openai"; 

export async function POST(req: Request) {
  // ...
  const agent = new Agent({
    // This uses the OPENAI_API_KEY environment variable by default, but you
    // can also pass { apiKey: string } as an option.
    model: openai("gpt-5.1"), 
    // ...
  });

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();
  const agent = new Agent({ 
    model: gateway("bedrock/claude-4-5-haiku-20251001-v1"),
    system: FLIGHT_ASSISTANT_PROMPT,
    tools: flightBookingTools,
  });
  const modelMessages = convertToModelMessages(messages);
  const stream = agent.stream({ messages: modelMessages }); 
  return createUIMessageStreamResponse({
    stream: stream.toUIMessageStream(),
  });
}

import { tool } from "ai";
import { z } from "zod";

export const tools = {
  searchFlights: tool({
    description: "Search for flights",
    inputSchema: z.object({ query: z.string() }),
    execute: searchFlights,
  }),
};

async function searchFlights({ from, to, date }: { from: string; to: string; date: string }) {
  // ... generate some fake flights
}

"use client";

import { useChat } from "@ai-sdk/react";

export default function ChatPage() {
  const { messages, input, handleInputChange, handleSubmit } = useChat({ 
    // ... other options ...
  });

  // ... more UI logic

  return (
    <div>
      // This is a simplified example of the rendering logic
      {messages.map((m) => (
        <div key={m.id}>
          <strong>{m.role}:</strong>
          {m.parts.map((part, i) => {
            if (part.type === "text") { 
              return <span key={i}>{part.text}</span>;
            }
            if (part.type === "tool-searchFlights") { 
              // ... some special rendering for our tool results
            }
            return null;
          })}
        </div>
      ))}
      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={handleInputChange}
          placeholder="Type a message..."
        />
      </form>
    </div>
  );
}

Integrating Workflow DevKit

Now that we have a basic agent using AI SDK, we can modify it to make it durable.

npm i workflow @workflow/ai

import { withWorkflow } from "workflow/next";
import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  // ... rest of your Next.js config
};

export default withWorkflow(nextConfig);

import { DurableAgent } from "@workflow/ai/agent"; 
import { getWritable } from "workflow"; 
import { tools } from "@/ai/tools";
import { openai } from "@workflow/ai/openai";
import type { ModelMessage, UIMessageChunk } from "ai";

export async function chatWorkflow(messages: ModelMessage[]) {
  "use workflow"; 

  const writable = getWritable<UIMessageChunk>(); 

  const agent = new DurableAgent({ 

    // If using AI Gateway, just specify the model name as a string:
    model: "bedrock/claude-4-5-haiku-20251001-v1", 

    // ELSE if using a custom provider, pass the provider call as an argument:
    model: openai("gpt-5.1"), 

    system: FLIGHT_ASSISTANT_PROMPT,
    tools: flightBookingTools,
  });

  await agent.stream({ 
    messages,
    writable,
  });
}

import type { UIMessage } from "ai";
import { convertToModelMessages, createUIMessageStreamResponse } from "ai";
import { start } from "workflow/api";
import { chatWorkflow } from "@/workflows/chat/workflow";

export async function POST(req: Request) {
  const { messages }: { messages: UIMessage[] } = await req.json();
  const modelMessages = convertToModelMessages(messages);

  const run = await start(chatWorkflow, [modelMessages]); 

  return createUIMessageStreamResponse({
    stream: run.readable, 
  });
}

// ...

export async function searchFlights(
  // ... arguments
) {
  "use step"; 

  // ... rest of the tool code
}

export async function checkFlightStatus(
  // ... arguments
) {
  "use step"; 

  // ... rest of the tool code
}

export async function getAirportInfo(
  // ... arguments
) {
  "use step"; 

  // ... rest of the tool code
}

export async function bookFlight({
  // ... arguments
}) {
  "use step"; 

  // ... rest of the tool code
}

export async function checkBaggageAllowance(
  // ... arguments
) {
    "use step"; 

    // ... rest of the tool code
  }
}

That's all you need to do to convert your basic AI SDK agent into a durable agent. If you run your development server, and send a chat message, you should see your agent respond just as before, but now with added durability and observability.

Observability

In your app directory, you can open up the observability dashboard to see your workflow in action, using the CLI:

npx workflow web

This opens a local dashboard showing all workflow runs and their status, as well as a trace viewer to inspect the workflow in detail, including retry attempts, and the data being passed between steps.

Next Steps

Now that you have a basic durable agent, it's a only a short step to add these additional features:

Complete Example

A complete example that includes all of the above, plus all of the "next steps" features is available on the main branch of the Flight Booking Agent example.

Related Documentation

• Tools - Patterns for defining tools for your agent
• DurableAgent API Reference - Full API documentation
• Workflows and Steps - Core concepts
• Streaming - In-depth streaming guide
• Errors and Retries - Error handling patterns