The Open Framework for Building Agents
issue: https://github.com/vercel/eve/issues/1084 status: implemented last_updated: "2026-09-10"
Tools as workflows
defineWorkflowTool is the authoring boundary for durable tools, and its executor context owns
agent and ask. The executor must explicitly start with "use workflow"; the definition
selects the eve tool contract and the directive marks the function's replay semantics.
Authoring API
import { defineWorkflowTool } from "eve/tools";
import { z } from "zod";
export default defineWorkflowTool({
description: "Review and deploy a service after approval.",
inputSchema: z.object({ service: z.string() }),
async execute({ service }, ctx) {
"use workflow";
const review = await ctx.agent("reviewer", {
message: `Review ${service} for deployment.`,
});
const answer = await ctx.ask({
prompt: `Deploy ${service}?\n${JSON.stringify(review)}`,
display: "confirmation",
options: [
{ id: "approve", label: "Deploy", style: "primary" },
{ id: "cancel", label: "Cancel" },
],
});
if (answer.optionId !== "approve") return { deployed: false };
return { deployed: true, service };
},
});
The executor receives WorkflowToolContext: session, callId, toolName, abortSignal,
agent(target, input), and ask(request). Ordinary ToolContext, channel contexts, and schedule contexts
have no agent or ask methods. Shared helpers can accept WorkflowToolContext explicitly.
The turn-owned getSandbox, getSkill, getToken, and requireAuth methods are absent from this
public type. Side effects and credential reads belong in top-level "use step" helpers.
Export defineWorkflowTool({ ... }) directly as the default export of a static tool module.
execute is an inline async function or async generator, or a reference to a top-level async
function in the same module or an imported application module. With execution: "background", the third executor argument is task; its postMessage method
creates a yielded message descriptor. Schemas, approvals, and model-output projections have
the same meaning as for the existing workflow tool runtime.
Compilation boundary
The source pass validates directive placement and hoists inline executors into the shape consumed
by the Workflow transform. Definition validation checks the compiled executor's .workflowId,
so missing directives fail during compilation without recognizing the definer's import spelling.
Discovery filters candidate files by directive text, then uses the same AST validation as the
transform; directives can be the first statement on the function's opening line. Workflow IDs
derive from the declaring module's application-relative path and function name, so migrating the
wrapper does not rename an existing inline executor.
The definition carries a workflow-tool brand. Compilation requires both that brand and a compiled
executor workflow ID. An ordinary defineTool or bare object with a workflow executor fails the
build; an uncompiled defineWorkflowTool also fails instead of running inline. Channel and
schedule handlers cannot be workflow executors. Dynamic resolvers cannot return workflow tools.
Standalone Workflow SDK functions used by workflow helpers retain their SDK semantics.
The driver drops the definition and schema imports, then runs the registered executor with a
context reconstructed for that run. ctx.agent and ctx.ask bind the existing invocation and
input-request operations to that context. No callable helpers are serialized across the run
boundary. This replaces call-site analysis with an explicit definition boundary and context types.
Observable semantics
Each tool call starts one durable run. By default the turn parks and the eventual return value,
error, or cancellation resolves the model's tool call. With execution: "background", the model
receives a task receipt. Ordinary yields are stream-only progress; yielding
task.postMessage(message) wakes the owning agent, as does completion.
ctx.agent delegates to the visible subagent named by its first argument. eve derives a unique,
replay-stable invocation identity for each call from its durable reply hook, including repeated and
parallel calls to the same subagent. ctx.ask publishes an input request on the session's channel
and returns an awaitable answer. It can be raced against sleep; finishing or cancelling
the run withdraws pending requests. The existing owner hooks and message protocol stay internal.
An async generator's yield reports progress. ctx.abortSignal remains durable and supports
cleanup in steps after cancellation. Steps, retries, replay, and Workflow SDK primitives keep
their existing behavior.
Migration
- Replace
defineToolwithdefineWorkflowToolfor workflow tools and keep the executor's"use workflow"directive. - Replace
agent(ctx, input)withctx.agent(target, input)andask(ctx, request)withctx.ask(request). - Remove imports from
eve/workflow; that entry point is removed. ImportWorkflowToolContext,AgentInput,ToolInputRequest, andToolInputResponsefromeve/toolswhen needed.
This is a breaking public API change. The existing workflow-tool fixture migrates to the new API and continues to cover delegation, human answers, deadlines, progress, background execution, and cancellation. Compiler tests cover the new entry point and rejection of the old authoring shapes.