The Open Framework for Building Agents
docs: clarify workflows as tools (#2931)
Casey Gowriedc08cbfc7628
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdxindex 1f89a66dc..6dc4ee578 100644--- a/docs/tools/overview.mdx+++ b/docs/tools/overview.mdx@@ -79,12 +79,12 @@ Later task-triggered parent turns receive fresh state for the same cohort. The mto keep related intermediate results silent while any task remains pending. Once every relatedtask is terminal, the state includes their outputs so the model can combine the useful results.-### Durable tools+### Workflows as tools-A tool whose `execute` starts with `"use workflow"` runs as a durable Workflow run instead of-inside the model step. It can wait for a person, a webhook, or a timer for as long as it takes, with-nothing running in between, and its return value still settles the tool call. See-[Durable tools](/docs/tools/workflows).+Put `"use workflow"` at the start of a tool's `execute` function to run each call as a durable+Workflow run. The tool can wait for a person, webhook, or timer without holding compute, then return+its result to the model. See [Workflows as tools](/docs/tools/workflows) for the authoring rules and+examples.### The `ctx` parameterdiff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdxindex 89f5b24f8..728e43852 100644--- a/docs/tools/workflows.mdx+++ b/docs/tools/workflows.mdx@@ -1,26 +1,33 @@----title: "Durable Tools"-description: "Write a tool as a workflow so it can wait for a person, a webhook, or a timer for as long as it takes, with nothing running in between."+title: "Workflows as Tools"+description: "Define durable workflow tools that wait for people, webhooks, or timers without holding compute."url: /tools/workflows----A tool's `execute` may be a workflow. eve starts one durable run per tool call and, by default,-waits for it: the run's return value is the tool result, however long it takes. While the run waits-on a person, a webhook, or a sleep, the turn is parked and nothing is running. Mark the same tool-`execution: "background"` and the model gets a receipt instead; eve wakes the agent with the return-value when the run ends.+A workflow tool is an authored tool whose `execute` function starts with `"use workflow"`. Each+call starts a durable Workflow run. Use one when a tool must wait for a person, webhook, or timer,+delegate work to subagents, or coordinate retryable steps over a long period.-Inside the tool, everything is the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`,-`"use step"`, `createHook`, `createWebhook`, `sleep`, retries, replay. eve adds `ask` from-`eve/workflow` — a question the human on the session's channel answers — and `agent` for delegating-from a workflow tool. eve treats each `yield` as a durable progress report.+By default, the model's tool call waits for the run's return value. While the run is suspended, the+turn is parked and holds no compute. Set `execution: "background"` when the conversation should+continue; the model receives a task receipt, and eve wakes the agent with the result when the run+ends.-## Write one+Workflow tools use the [Workflow SDK](https://workflow-sdk.dev): `"use workflow"`, `"use step"`,+`createHook`, `createWebhook`, `sleep`, retries, and replay. eve adds `ask` from `eve/workflow` for+questions answered through the session's channel and `agent` for durable subagent delegation. Each+`yield` becomes a durable progress report.++A workflow tool runs code you wrote and appears to the model under its path-derived tool name, such+as `deploy`.++## Define a workflow tool```ts title="agent/tools/deploy.ts"import { defineTool } from "eve/tools";import { ask } from "eve/workflow";import { z } from "zod";+import { computePlan, runDeploy, type DeployPlan } from "../lib/deploy";export default defineTool({description: "Deploy a service to production. Pauses for a human to approve the plan.",@@ -85,8 +92,8 @@ or days later, the run resumes, deploys, and returns. The model sees one tool re| cancel | cancelling the turn cancels the run | `task_cancel`, or the session ending |Wait when the model needs the answer to continue. Go background when the wait may outlive the-conversation or the user should keep talking in the meantime. Background tools require-`experimental.tasks` on the root agent, like every background tool.+conversation or the user should keep talking in the meantime. Background tools need no root-agent+flag.## Ask a human: `ask`@@ -186,7 +193,7 @@ as cancelled whether or not it did. A body parked on a hook or a `sleep` does noit is abandoned when the grace period ends. Steps that received the signal are how you clean upfirst.-## Flows+## Workflow tool examples### Approve with a deadline and an escalation@@ -214,8 +221,11 @@ and returning withdraws the request.### Wait for an external system to call back-```ts+```ts title="agent/tools/render_video.ts"+import { defineTool } from "eve/tools";import { createWebhook, FatalError } from "workflow";+import { z } from "zod";+import { submitRender } from "../lib/render";export default defineTool({description: "Render a video. Returns the URL once the render farm finishes.",@@ -239,8 +249,11 @@ system posts to it when it is done. Nothing runs in between.### Ask now, act when answered-```ts+```ts title="agent/tools/refund_order.ts"+import { defineTool } from "eve/tools";import { ask } from "eve/workflow";+import { z } from "zod";+import { issueRefund } from "../lib/refunds";export default defineTool({description: "Request approval to refund an order, then issue the refund once approved.",@@ -269,8 +282,10 @@ on the channel. When it is answered, the refund runs and the agent is woken with### Remind me later-```ts+```ts title="agent/tools/remind.ts"+import { defineTool } from "eve/tools";import { sleep } from "workflow";+import { z } from "zod";export default defineTool({description: "Remind the user about something after a delay.",