---
title: Choosing between eve, AI SDK agents, and `WorkflowAgent`
description: Compare eve, `ToolLoopAgent`, and `WorkflowAgent` by durability, approvals, channels, and setup to choose an agent framework for your TypeScript application.
url: "https://vercel.com/kb/guide/eve-vs-ai-sdk-agents-vs-workflowagent"
published: 2026-11-02
last_updated: 2026-11-02
authors: Ben Sabic
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

For an agent that can restart after a failed request, `ToolLoopAgent` provides the model-and-tool loop inside your TypeScript application. `WorkflowAgent` adds durable execution for work that must survive interruptions.

eve packages durable sessions with channels, a sandbox, approvals, and evals. Choose it when you want those parts supplied by a framework configured through Markdown and TypeScript files.

## How the three options relate

`ToolLoopAgent` is part of the [AI SDK](https://ai-sdk.dev/docs/agents/overview). Both `WorkflowAgent` and [eve](https://ai-sdk.dev/docs/agents/eve) use its model and tool interfaces, and all three accept AI Gateway model strings.

### What `ToolLoopAgent` does

`ToolLoopAgent` runs a model-and-tool loop inside your application. You supply a model, instructions, and tools; it calls the model, executes tools that are ready to run, and sends their results back for another model call.

It returns when the model no longer requests executable tools, when approval or external tool handling is needed, or when a stop condition is met. The default `stopWhen` setting allows up to 20 steps.

`ToolLoopAgent` does not persist execution checkpoints. If the process crashes or times out, your app handles recovery using any messages or results it saved.

This order-status agent uses one tool and sets a 10-step limit. The tool returns a fixed response; replace it with a lookup in your order system.

```typescript
import { ToolLoopAgent, isStepCount, tool } from 'ai';
import { z } from 'zod';

export const supportAgent = new ToolLoopAgent({
  model: 'anthropic/claude-opus-5.5',
  instructions: 'You answer questions about order status.',
  tools: {
    getOrderStatus: tool({
      description: 'Look up the status of an order by order number.',
      inputSchema: z.object({ orderNumber: z.string() }),
      execute: async ({ orderNumber }) => ({ orderNumber, status: 'shipped' }),
    }),
  },
  stopWhen: isStepCount(10),
});

const result = await supportAgent.generate({
  prompt: 'Where is order ORD-104233?',
});
console.log(result.text);
```

### What `WorkflowAgent` does

`WorkflowAgent` from `@ai-sdk/workflow` runs an AI SDK agent loop inside a [Vercel Workflow](https://vercel.com/docs/workflows). Model calls run as durable steps, and tools gain checkpointing and retries when their `execute` function is marked `'use step'`. Failed steps retry up to three times by default, for four attempts total.

Setting `needsApproval` produces an approval request without executing the tool. The agent call then returns, and your application submits the decision with the conversation history in a later workflow invocation. Use a [workflow hook](https://workflow-sdk.dev/docs/foundations/hooks) if the same run must suspend until a decision arrives.

`WorkflowAgent` replaces `DurableAgent` from the Workflow SDK and requires Workflow 5.1 or later. It writes output to a workflow `writable` stream. Its `stream()` method has no default step limit, so set `stopWhen` to limit model calls.

This workflow requests approval before calling the refund tool. The tool is a placeholder; replace its return value with an idempotent call to your payments API.

```typescript
import {
  WorkflowAgent,
  type ModelCallStreamPart,
} from '@ai-sdk/workflow';
import {
  convertToModelMessages,
  isStepCount,
  tool,
  type UIMessage,
} from 'ai';
import { getWritable } from 'workflow';
import { z } from 'zod';

async function refundOrderStep(input: { orderNumber: string }) {
  'use step';
  // Call your payments API here with an idempotency key
  return { orderNumber: input.orderNumber, refunded: true };
}

export async function supportWorkflow(messages: UIMessage[]) {
  'use workflow';

  const agent = new WorkflowAgent({
    model: 'anthropic/claude-opus-5.5',
    instructions: 'You handle refund requests.',
    tools: {
      refundOrder: tool({
        description: 'Refund an order by order number.',
        inputSchema: z.object({ orderNumber: z.string() }),
        needsApproval: true,
        execute: refundOrderStep,
      }),
    },
  });

  const result = await agent.stream({
    messages: await convertToModelMessages(messages),
    writable: getWritable<ModelCallStreamPart>(),
    stopWhen: isStepCount(10),
  });

  return { messages: result.messages };
}
```

The caller must display the approval request, authorize the reviewer's decision, and start a new invocation with the updated message history. For client-supplied approval history, configure [signed approvals](https://ai-sdk.dev/docs/agents/workflow-agent#signed-tool-approvals). Follow the [approval integration](https://ai-sdk.dev/docs/agents/workflow-agent#approval-round-trips-without-streaming) to connect the workflow to your application.

### What eve does

[eve](https://vercel.com/docs/eve) is an open-source, filesystem-first framework for durable backend agents. You define an agent as files under an `agent/` directory, and eve compiles them into an application that runs on Vercel Functions, Vercel Workflows, and AI Gateway.

Instructions and skills are Markdown, tools are TypeScript files whose filenames become tool names, and channels, connections, subagents, and schedules each have their own folder.

eve sessions are durable by default. On Vercel, Workflows checkpoints progress between steps and suspends sessions awaiting approval or user input, with no separate database or queue to configure.

The framework also ships with a sandbox for shell and file tools, built-in channels for platforms such as Slack and GitHub, and an eval runner. Its current release, 1.0.0-rc.1, is a release candidate for version 1.0.

In an [initialized eve project](https://eve.dev/docs/getting-started), these two files define the instructions and select a model. Put the system prompt in `agent/instructions.md`:

```markdown
You answer questions about order status. Use tools when they are available.
```

The optional `agent/agent.ts` file selects an AI Gateway model:

```typescript
import { defineAgent } from 'eve';

export default defineAgent({
  model: 'anthropic/claude-opus-5.5',
});
```

Define each tool in a file under `agent/tools/`. eve exposes `get_order_status.ts` to the model as `get_order_status` without separate registration:

```typescript
import { defineTool } from 'eve/tools';
import { z } from 'zod';

export default defineTool({
  description: 'Look up the status of an order by order number.',
  inputSchema: z.object({ orderNumber: z.string() }),
  async execute({ orderNumber }) {
    return { orderNumber, status: 'shipped' };
  },
});
```

To require a person's sign-off before a tool runs, add `approval: always()` to its definition and import `always` from `eve/tools/approval`. When `approval` is omitted, eve runs the tool without asking.

eve controls session usage through `limits.sessionUsage` in `agent/agent.ts`. The default threshold is 40,000,000 new input tokens per usage window, excluding cached reads. You can set a threshold using token counts or reported model cost.

Once the threshold is reached, eve asks permission to continue before another model call and starts a new window if the user agrees. Sessions without a human input path, such as Markdown schedules, fail that model call instead.

## How the three options compare

| Attribute        | `ToolLoopAgent`                             | `WorkflowAgent`                                                 | eve                                              |
| ---------------- | ------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------ |
| Definition       | Agent class in app code                     | Agent class in a workflow                                       | Files in an agent directory                      |
| Execution state  | In memory                                   | Persisted workflow steps                                        | Persisted sessions                               |
| Interrupted work | App handles recovery                        | Uses saved step results                                         | Resumes the session                              |
| Tool errors      | App handles retries                         | Durable steps retry up to 3 times                               | Errors return to the model                       |
| Approval         | App handles the decision and continuation   | Decision arrives in a later invocation; hooks can suspend a run | Session waits for a decision                     |
| Default limit    | 20 steps                                    | Streaming has no step cap; generation has 20                    | Usage-window threshold                           |
| Channels         | App integrates them                         | App integrates them                                             | Built-in integrations                            |
| Sandbox          | Optional integration                        | Optional integration                                            | Included by default                              |
| Release          | AI SDK 7                                    | Package 2.x with Workflow 5.1+                                  | 1.0 release candidate                            |
| Best fit         | Short agent tasks with app-managed recovery | Durable orchestration in your app                               | Agents needing sessions, channels, and schedules |

For resumable web streams, `WorkflowChatTransport` connects WorkflowAgent output to your UI. Both SDK agent classes support `experimental_sandbox` when you supply a sandbox implementation.

In eve, ordinary tool errors return to the model, which can request another call. Add safe retries inside the tool when needed; authored workflow steps have their own retry behavior. The session's usage-window threshold is separate from a step limit.

## When to use each option

### Use `ToolLoopAgent` when the agent finishes within one request

Choose `ToolLoopAgent` when the work fits within one invocation and your application can handle a retry after failure. Its context can hold non-serializable values, such as database or SDK clients, for the life of the process.

Support chatbots that look up an order and answer in one response fit this model, as do AI features streamed to a Next.js UI with `useChat` and internal demos where losing an interrupted run is acceptable.

### Use `WorkflowAgent` when an agent in your app must survive interruptions

`WorkflowAgent` adds durable execution to an agent in your application. Use it when completed model calls and tool results must survive an interruption, or when orchestration spans hours or days.

Use a workflow hook to wait for approval within the same run. The suspended workflow consumes no compute, but its retained state can incur [storage charges](https://vercel.com/docs/workflows/pricing).

Examples include:

- Refund or configuration-change agents that wait for a reviewer's approval
  
- Research agents that must preserve dozens of tool results across timeouts
  
- Agents that call internal APIs, where each mutating call needs automatic retries and an idempotency key
  

You own the routes, UI, and storage, but context must be serializable so the workflow can persist and replay it across steps.

### Use eve for agents with built-in channels and schedules

eve combines durable sessions with approvals, a sandbox, channels, schedules, and an eval runner. You define the agent in the `agent/` directory and keep evals alongside it. Because instructions and skills are Markdown, people outside engineering can read and edit the agent's behavior.

Use eve for agents such as:

- Slack or Microsoft Teams agents that answer in threads and wait for approval before running tools that change data
  
- GitHub agents that review pull requests or prepare draft fixes
  
- Scheduled agents that send a daily digest or run a weekly sweep
  
- Agents that delegate work to specialist subagents
  

For a single AI feature inside an app, or when you want full control over the agent loop, `ToolLoopAgent` or `WorkflowAgent` adds less framework.

## How to move between options as your agent grows

All three accept AI Gateway model strings and Zod schemas for tool inputs. You can reuse both in a durable workflow or eve's file-based project structure.

### Move from `ToolLoopAgent` to `WorkflowAgent`

Move to `WorkflowAgent` when you need execution checkpoints across interruptions. The model, instructions, and tool schemas can carry over; the main changes are workflow setup, execution, and how your application handles results:

1. Install `@ai-sdk/workflow` with a compatible Workflow 5.1+ release and follow the [framework setup](https://workflow-sdk.dev/docs/getting-started) for your application.
   
2. Create `WorkflowAgent` from `@ai-sdk/workflow` in a `'use workflow'` function. Start that function with `start()` from `workflow/api` in your route.
   
3. Pass a workflow writable stream to `agent.stream()`. Return the run's readable output to the client using the [WorkflowAgent streaming integration](https://ai-sdk.dev/docs/agents/workflow-agent#end-to-end-example).
   
4. Make each tool retryable by marking its `execute` function with `'use step'`. Use idempotency keys for writes that may repeat.
   
5. Keep approval requirements on the tools. Have the caller submit approved or denied decisions with message history in a later workflow invocation, or use a hook to suspend the same run.
   
6. Set `stopWhen` to give the streaming loop a step limit.
   
7. Pass serializable context into the workflow and create database or SDK clients inside the step that uses them.
   

If you already use `DurableAgent` from the Workflow SDK, follow the [migration guide](https://ai-sdk.dev/docs/agents/workflow-agent#migrating-from-durableagent).

### Move from the AI SDK to eve

Move to eve when you find yourself rebuilding a Slack integration, an approval queue, a cron wrapper, and a sandbox for each new agent. Your model string carries over to `agent/agent.ts`, your system prompt becomes `agent/instructions.md`, and each tool becomes a file in `agent/tools/` that you define with `defineTool`.

eve accepts any AI SDK `LanguageModel` as well as AI Gateway model strings, so provider-specific setups keep working. To add eve to an existing app, run `pnpm dlx eve@latest init .` from the project root before creating any `agent/` files.

### Use more than one option in the same project

One Vercel project can combine an eve agent for work across channels with `ToolLoopAgent` for a short in-app feature such as a search assistant. eve supports [integration with an existing app](https://eve.dev/docs/guides/frontend), so the two approaches can share a project.

Workflow and route code run as Vercel Functions. Commands executed in a sandbox run in that sandbox's environment and need their own configuration.

## Next steps

- Build your first in-app agent with [ToolLoopAgent](https://ai-sdk.dev/docs/agents/building-agents) [in the AI SDK](https://ai-sdk.dev/docs/agents/building-agents)
  
- Add durability, retries, and approvals with [`WorkflowAgent`](https://ai-sdk.dev/docs/agents/workflow-agent)
  
- Learn how durable runs work in [Vercel Workflows](https://vercel.com/docs/workflows)
  
- Create and deploy a filesystem-first agent with [eve on Vercel](https://vercel.com/docs/frameworks/agents/eve)
  
- See how the three options handle [private APIs and databases](https://vercel.com/kb/guide/private-enterprise-agents-vercel)

## Related Documentation

- [eve](https://eve.dev/docs)
- [AI SDK](/docs/ai-sdk)
- [Vercel Workflows](/docs/workflow)

## More eve guides

- [How to add tools to your eve agent](/kb/guide/how-to-add-eve-tools): Add tools to an eve agent by creating a TypeScript file under agent/tools/ with defineTool, and gate sensitive ones on human approval with approval.
- [Running background workers on Vercel](/kb/guide/background-workers-on-vercel): Run background jobs on Vercel with waitUntil, Cron Jobs, Queues, Workflows, Daemons, or Sandbox. Compare the options and pick the right one for your workload.
- [Trace and debug eve agent runs](/kb/guide/trace-and-debug-eve-agent-runs): Inspect eve traces in Vercel Agent Runs, control captured content, export OpenTelemetry spans, and test fixes with regression evals.