The Open Framework for Building Agents
chore(docs) correct contradictions in delegation and workspace setup (#4518)
Colton Paddenebfa627f23b6
diff --git a/docs/extensions.md b/docs/extensions.mdindex ae80e84e5..fb5dab4a5 100644--- a/docs/extensions.md+++ b/docs/extensions.md@@ -178,7 +178,7 @@ A mount gives the extension's contributions a namespace. Updating the package up### Install the package-Install the extension with the package manager already used by the consumer's agent project. Fresh eve projects use pnpm:+Install the extension with the package manager already used by the consumer's agent project. For example, in a pnpm project:```bashpnpm add @acme/crmdiff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdxindex cc0aaaba3..d363d2e54 100644--- a/docs/guides/frontend/nextjs.mdx+++ b/docs/guides/frontend/nextjs.mdx@@ -11,21 +11,34 @@ Use this integration when Next.js owns the application's development and deploym- The `eve` package installed in your project (`npm install eve@latest`).- An existing eve agent directory. If you don't have one, start from [Getting Started](../../getting-started).-- A Next.js app, or a single-agent project where you want to generate one below.+- A Next.js app, or an eve project where you want to generate one below.## Add the generated Web Chat app-For a single-agent project, install the generated Next.js Web Chat app:+Install the generated Next.js Web Chat app from a standalone agent project:```basheve add channel/web```-The installer adds a Next.js application and wraps `next.config.ts` with `withEve()`. The generated chat calls the unnamed agent through same-origin `/eve/v1/*` routes.+For an agent workspace, select the member the chat should call:++```bash+eve add channel/web --agent support+```++The installer configures the chat for the selected agent. By default, it adds a shared Next.js+application under `apps/web`; if a root Web Chat app already exists, it configures that app instead.+For Next.js hosting, the installer wraps `next.config.ts` with `withEve()`. When setting up a new+app, choose **Next.js** to host the integration. The generated chat uses same-origin `/eve/v1/*`+routes for a standalone agent or `/eve/<name>/v1/*` routes for a workspace member. Running the+installer from a workspace root without selecting a member is not supported.Before accepting production browser traffic, replace the generated placeholder authorization policy. See [Authenticate browser requests](./overview#authenticate-browser-requests).-The Web Chat installer does not support eve agent workspaces. If you want Next.js to host the integration, create a root Next.js application and follow the steps below; `withEve(nextConfig)` discovers workspace members but does not generate a chat UI. To keep the frontend as a peer application instead, follow the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment).+To integrate an existing Next.js application without generating a chat UI, follow the steps below.+To deploy the frontend and agents as separate Vercel services, choose **Vercel services** during+setup instead; see the [workspace layout guidance](/docs/concepts/project-structure#configure-a-web-deployment).## Wrap the Next.js configdiff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdxindex dad58347b..46c515e74 100644--- a/docs/tools/overview.mdx+++ b/docs/tools/overview.mdx@@ -176,8 +176,8 @@ receive only the projected text.### Durable waits-Every tool call finishes before its turn continues. The definition decides whether the executor-can wait durably while the call is pending:+A tool call with an `execute` entry point finishes before the model continues. The definition+decides whether the executor can wait durably while the call is pending:| Definition | Durable waits inside `execute` | Result delivered to the model || -------------------- | -------------------------------------------------------- | ---------------------------------- |@@ -191,11 +191,15 @@ the call returns a receipt at once, and the workflow's output reaches the model[resumable task](/docs/tools/workflows#resumable-tasks-serve), which the model can send more callsby its `taskId`.+Built-in, declared local, and remote subagent tools run as resumable tasks: each call returns a+receipt at once, and the child's reply reaches the model later in a `task.result` message.+Inside an authored workflow, awaiting a [`ctx.agent` session's `response.result()`](/docs/tools/workflows#delegate-work-ctxagent)+waits for the child's turn to end instead.+The `TaskExec` argument and `task.postMessage` have been removed. Return the result. In a workflowbody, keep values needed after a wait in local variables; workflow replay reconstructs them acrossdurable waits. Use [`ctx.ask`](/docs/tools/workflows#ask-a-human-ctxask) when the body needs an-answer from the human. Built-in, declared local, and remote subagent calls also block: each call-returns the child's reply as its tool result.+answer from the human.### Yield and returndiff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdxindex 2874c5444..3a1502acb 100644--- a/docs/tools/workflows.mdx+++ b/docs/tools/workflows.mdx@@ -347,10 +347,14 @@ described in [Tasks](/docs/tools/tasks). What differs:share one identity, so don't keep per-person data for them. Any caller in the session cancontinue or cancel the task; see [Tasks](/docs/tools/tasks#ownership-and-limits).- **Agents belong to the call that opened them:** a session the body opens with `ctx.agent` while- serving a call is that call's child. Its `session.parent` names the call's `callId` and turn, and- its trace continues from the call's tool span. The session keeps that lineage for its later- messages, even after the task receives another call. Auth belongs to each message instead: a- message carries the auth of the call being served when it's sent.+ serving a call is that call's child. Its `session.parent` names the call's `callId` and turn.+ The first turn of a local child uses the call's tool span as its parent when trace context is+ available. A remote child starts its own trace; its first turn links to the call's tool span+ with `eve.link.type=agent.dispatch` when trace context is available. Later child turns start new+ traces. Parent session lineage stays tied to the opening call, even after the task receives+ another call; a remote receiver accepts that lineage only from a trusted forwarder. Each message+ uses the auth of the call being served; remote identity follows the+ [forwarding rules](../guides/remote-agents#forwarding-the-caller-identity).- **Results:** `ctx.reply(output)` settles every call received so far with `output`, all at once.Each settled call reports its own `task.settled`, and the model receives the reply once. The taskthen goes idle until its next call. A reply with@@ -541,9 +545,13 @@ client's `MessageResult` fields, plus `error` when the turn failed:| `error` | `{ message }` with the reason the turn failed, present only when `status` is `"failed"`. |Every `ctx.agent(name)` call returns a new session that only the workflow run can address. The model-does not see it; it sees what the tool returns. The session runs as the caller's principal with the-caller's capabilities, and a person answers its questions and sign-ins at the root session, as for-any subagent. The session ends when the run finishes, which cancels any turn still running.+does not see it; it sees what the tool returns. A local child runs as the caller's principal with the+caller's capabilities. A remote child does not inherit the caller's session principal by default;+the receiving deployment determines its identity from the outbound request. To forward the caller's+identity, set `forwardPrincipal: true` on the remote agent and configure the receiver's+`trustedForwarders` (see [Forwarding the caller identity](../guides/remote-agents#forwarding-the-caller-identity)).+A person answers the child's questions and sign-ins at the root session, as for any subagent.+The session ends when the run finishes, which cancels any turn still running.The parent stream announces each session with `agent.started`, which carries the `callId` and`turnId` of the tool call the run is serving when it opens the session (for a `serve` task, the