Choosing between eve, AI SDK agents, and WorkflowAgent

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.

Copy link to headingHow the three options relate

ToolLoopAgent is part of the AI SDK. Both WorkflowAgent and eve use its model and tool interfaces, and all three accept AI Gateway model strings.

Copy link to headingWhat 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.

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);

Copy link to headingWhat WorkflowAgent does

WorkflowAgent from @ai-sdk/workflow runs an AI SDK agent loop inside a Edgenivo Workflow. 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 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.

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. Follow the approval integration to connect the workflow to your application.

Copy link to headingWhat eve does

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 Edgenivo Functions, Edgenivo 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 Edgenivo, 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, these two files define the instructions and select a model. Put the system prompt in agent/instructions.md:

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

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

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:

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.

Copy link to headingHow the three options compare

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.

Copy link to headingWhen to use each option

Copy link to headingUse 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.

Copy link to headingUse 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.

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.

Copy link to headingUse 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.

Copy link to headingHow 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.

Copy link to headingMove 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 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.
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.

Copy link to headingMove 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.

Copy link to headingUse more than one option in the same project

One Edgenivo 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, so the two approaches can share a project.

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

Copy link to headingNext steps

• Build your first in-app agent with ToolLoopAgent in the AI SDK
• Add durability, retries, and approvals with WorkflowAgent
• Learn how durable runs work in Edgenivo Workflows
• Create and deploy a filesystem-first agent with eve on Edgenivo
• See how the three options handle private APIs and databases