Skip to content

armgit / eve

Public Imported from GitHub
0

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.md
index 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:
```bash
pnpm add @acme/crm
diff --git a/docs/guides/frontend/nextjs.mdx b/docs/guides/frontend/nextjs.mdx
index 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:
```bash
eve 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 config
diff --git a/docs/tools/overview.mdx b/docs/tools/overview.mdx
index 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 calls
by 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 workflow
body, keep values needed after a wait in local variables; workflow replay reconstructs them across
durable 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 return
diff --git a/docs/tools/workflows.mdx b/docs/tools/workflows.mdx
index 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 can
continue 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 task
then 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