eve 0.85.0 → 0.86.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +7 -4
- package/dist/CHANGELOG.md +38 -0
- package/dist/src/cli/commands/agent-prompt/collect-intent.md +2 -1
- package/dist/src/cli/commands/agent-prompt/scaffold.md +1 -2
- package/dist/src/cli/dev/tui/runner.d.ts +1 -1
- package/dist/src/cli/dev/tui/runner.js +1 -1
- package/dist/src/cli/run.js +1 -1
- package/dist/src/compiled/.vendor-stamp.json +4 -4
- package/dist/src/compiled/@vercel/schedules/index.d.ts +45 -6
- package/dist/src/compiled/@vercel/schedules/index.js +2 -2
- package/dist/src/execution/dynamic-workflow/tool.js +1 -1
- package/dist/src/execution/proxied-deliver-step.js +1 -1
- package/dist/src/execution/session/active-turn.js +1 -1
- package/dist/src/execution/session/answer-caller.d.ts +9 -5
- package/dist/src/execution/session/answer-caller.js +1 -1
- package/dist/src/execution/session/principal.d.ts +8 -0
- package/dist/src/execution/session/principal.js +1 -1
- package/dist/src/execution/session/program.js +1 -1
- package/dist/src/execution/session/turn-step.js +1 -1
- package/dist/src/execution/session/turn.js +1 -1
- package/dist/src/execution/session-callback-request.js +1 -1
- package/dist/src/execution/tools/agent-router-workflow.js +1 -1
- package/dist/src/harness/attachment-staging.d.ts +2 -2
- package/dist/src/harness/attachment-staging.js +1 -1
- package/dist/src/internal/application/stamped-package-version.js +1 -1
- package/dist/src/internal/nitro/routes/schedule-collection-consumer.js +1 -1
- package/dist/src/public/schedules/providers/vercel.d.ts +2 -0
- package/dist/src/public/schedules/providers/vercel.js +1 -1
- package/dist/src/runtime/subagents/workflow.js +1 -1
- package/dist/src/setup/scaffold/create/project.js +1 -1
- package/dist/src/tools/provided/ask-question-workflow.js +1 -1
- package/dist/src/tools/provided/sleep-workflow.js +1 -1
- package/docs/channels/eve.mdx +1 -5
- package/docs/concepts/project-structure.mdx +1 -1
- package/docs/concepts/security-model.md +4 -0
- package/docs/concepts/upgrade-to-v27-events.md +68 -0
- package/docs/getting-started.mdx +2 -0
- package/docs/guides/auth-and-route-protection.md +1 -0
- package/docs/guides/client/streaming.mdx +1 -1
- package/docs/guides/deployment/self-hosting.md +1 -1
- package/docs/guides/frontend/meta.json +1 -0
- package/docs/guides/frontend/nextjs.mdx +329 -121
- package/docs/guides/frontend/overview.mdx +115 -335
- package/docs/guides/frontend/tanstack.mdx +1 -1
- package/docs/guides/frontend/use-eve-agent-svelte.mdx +5 -5
- package/docs/guides/frontend/use-eve-agent-vue.mdx +5 -5
- package/docs/guides/frontend/use-eve-agent.mdx +385 -0
- package/docs/guides/hooks.md +1 -1
- package/docs/guides/remote-agents.md +4 -2
- package/docs/guides/self-modification.md +6 -0
- package/docs/reference/cli.md +1 -2
- package/docs/sandbox/index.mdx +1 -1
- package/package.json +13 -21
- package/CHANGELOG.md +0 -3106
- package/dist/src/self-modification/agent.d.ts +0 -12
- package/dist/src/self-modification/agent.js +0 -1
|
@@ -1,46 +1,97 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: "Next.js"
|
|
3
|
-
description: "
|
|
3
|
+
description: "Add an eve chat to a Next.js app, from setup and authentication to saved conversations and deployment."
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
|
|
6
|
+
Your Next.js app and your eve agent run side by side on the same domain. Pages go to Next.js, and requests to `/eve/v1/*` go to the agent. The agent runs as its own service, never inside the Next.js server. Your React code is the same whichever setup you pick below.
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
## Choose a setup
|
|
9
9
|
|
|
10
|
-
|
|
10
|
+
There are two ways to connect the app and the agent. Both deploy as one Vercel project.
|
|
11
11
|
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
12
|
+
| | Vercel services (recommended) | Next.js hosts the agent |
|
|
13
|
+
| ------------ | ------------------------------ | ----------------------------- |
|
|
14
|
+
| What you add | A root `vercel.ts` | A wrapper in `next.config.ts` |
|
|
15
|
+
| Run locally | `vercel dev --local` | `next dev` |
|
|
16
|
+
| Self-host | Run the app and agent yourself | `next start` runs both |
|
|
15
17
|
|
|
16
|
-
|
|
18
|
+
Start with **Vercel services**. Choose Next.js hosting when Next.js should run everything, for example when you add an agent to an existing Next.js app that deploys from the project root.
|
|
17
19
|
|
|
18
|
-
|
|
20
|
+
## Create a chat app
|
|
21
|
+
|
|
22
|
+
From your agent project, run the Web Chat installer:
|
|
19
23
|
|
|
20
24
|
```bash
|
|
21
25
|
eve add channel/web
|
|
22
26
|
```
|
|
23
27
|
|
|
24
|
-
|
|
28
|
+
It asks three questions:
|
|
25
29
|
|
|
26
|
-
|
|
27
|
-
|
|
30
|
+
1. **Framework:** choose **Next.js**.
|
|
31
|
+
2. **Hosting:** choose **Vercel services**, or **Next.js** to have Next.js host the agent.
|
|
32
|
+
3. **Authentication:** choose **Sign in with Vercel**, or set it up yourself. See [Authenticate users](#authenticate-users).
|
|
33
|
+
|
|
34
|
+
In a project with several agents, add `--agent <name>` to pick the one the chat talks to.
|
|
35
|
+
|
|
36
|
+
The installer creates a Next.js app in `apps/web/`:
|
|
37
|
+
|
|
38
|
+
```text
|
|
39
|
+
project/
|
|
40
|
+
├── agent/
|
|
41
|
+
│ └── channels/eve.ts # who can call the agent from a browser
|
|
42
|
+
├── apps/web/
|
|
43
|
+
│ ├── app/
|
|
44
|
+
│ │ ├── _components/ # the chat UI
|
|
45
|
+
│ │ ├── page.tsx # landing page
|
|
46
|
+
│ │ └── s/ # conversation pages
|
|
47
|
+
│ └── next.config.ts
|
|
48
|
+
├── package.json # dependencies and scripts
|
|
49
|
+
└── vercel.ts # Vercel services only
|
|
28
50
|
```
|
|
29
51
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
52
|
+
Start it with the command the installer prints:
|
|
53
|
+
|
|
54
|
+
| Command | Starts |
|
|
55
|
+
| ----------------- | ------------------------------------------------------ |
|
|
56
|
+
| `npm run dev:all` | The app and the agent together (Vercel services) |
|
|
57
|
+
| `npm run dev:web` | The app. With Next.js hosting, it starts the agent too |
|
|
58
|
+
| `npm run dev` | The agent alone, in the eve terminal UI |
|
|
59
|
+
|
|
60
|
+
`dev:all` needs Vercel CLI 59.16.0 or newer, but not a linked project.
|
|
61
|
+
|
|
62
|
+
Before you deploy, replace the placeholder auth the installer generates. Until then, production browser requests get `401`. See [Authenticate users](#authenticate-users).
|
|
36
63
|
|
|
37
|
-
|
|
64
|
+
## Add eve to an existing app
|
|
38
65
|
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
66
|
+
### With Vercel services
|
|
67
|
+
|
|
68
|
+
Leave `next.config.ts` alone. Add a `vercel.ts` at the project root that tells Vercel where your app lives:
|
|
69
|
+
|
|
70
|
+
```ts title="vercel.ts"
|
|
71
|
+
import { withEve } from "eve/vercel";
|
|
72
|
+
|
|
73
|
+
export default await withEve({
|
|
74
|
+
services: {
|
|
75
|
+
web: {
|
|
76
|
+
framework: "nextjs",
|
|
77
|
+
root: "apps/web",
|
|
78
|
+
buildCommand: "node ../../node_modules/next/dist/bin/next build",
|
|
79
|
+
},
|
|
80
|
+
},
|
|
81
|
+
routes: [{ src: "^(.*)$", destination: { type: "service", service: "web" } }],
|
|
82
|
+
});
|
|
83
|
+
```
|
|
42
84
|
|
|
43
|
-
|
|
85
|
+
`withEve` adds your agents and their routes for you: `/eve/v1/*` for one agent, or `/eve/<name>/v1/*` for each agent in a workspace.
|
|
86
|
+
|
|
87
|
+
- Install `eve` in the root `package.json`.
|
|
88
|
+
- Remove any `vercel.json`.
|
|
89
|
+
|
|
90
|
+
See [Compose agents with other Vercel services](../deployment/vercel#compose-agents-with-other-vercel-services) for more options.
|
|
91
|
+
|
|
92
|
+
### With Next.js hosting
|
|
93
|
+
|
|
94
|
+
Wrap your Next.js config:
|
|
44
95
|
|
|
45
96
|
```ts title="next.config.ts"
|
|
46
97
|
import type { NextConfig } from "next";
|
|
@@ -51,162 +102,319 @@ const nextConfig: NextConfig = {};
|
|
|
51
102
|
export default withEve(nextConfig);
|
|
52
103
|
```
|
|
53
104
|
|
|
54
|
-
|
|
105
|
+
`withEve` looks for your agent next to `next.config.ts`. If the agent lives somewhere else, point to it:
|
|
55
106
|
|
|
56
|
-
|
|
107
|
+
```ts title="apps/web/next.config.ts"
|
|
108
|
+
export default withEve(nextConfig, { eveRoot: "../.." });
|
|
109
|
+
```
|
|
57
110
|
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
111
|
+
This setup needs Next.js 16 and React 19. See [`withEve` options](#witheve-options) for the rest.
|
|
112
|
+
|
|
113
|
+
## Build the chat UI
|
|
114
|
+
|
|
115
|
+
Call `useEveAgent` from a Client Component:
|
|
116
|
+
|
|
117
|
+
```tsx title="apps/web/app/_components/chat.tsx"
|
|
118
|
+
"use client";
|
|
119
|
+
|
|
120
|
+
import { useEveAgent } from "eve/react";
|
|
121
|
+
|
|
122
|
+
export function Chat() {
|
|
123
|
+
const agent = useEveAgent();
|
|
124
|
+
const isResuming = agent.status === "resuming";
|
|
125
|
+
|
|
126
|
+
return (
|
|
127
|
+
<form
|
|
128
|
+
onSubmit={(event) => {
|
|
129
|
+
event.preventDefault();
|
|
130
|
+
const message = String(new FormData(event.currentTarget).get("message") ?? "").trim();
|
|
131
|
+
if (message.length > 0 && !isResuming) {
|
|
132
|
+
void agent.send(message);
|
|
133
|
+
}
|
|
134
|
+
}}
|
|
135
|
+
>
|
|
136
|
+
{agent.messages.map((message) => (
|
|
137
|
+
<article key={message.id}>
|
|
138
|
+
<header>{message.role}</header>
|
|
139
|
+
{message.parts.map((part, index) =>
|
|
140
|
+
part.type === "text" ? <p key={part.id ?? index}>{part.text}</p> : null,
|
|
141
|
+
)}
|
|
142
|
+
</article>
|
|
143
|
+
))}
|
|
144
|
+
<input disabled={isResuming} name="message" />
|
|
145
|
+
<button disabled={isResuming} type="submit">
|
|
146
|
+
Send
|
|
147
|
+
</button>
|
|
148
|
+
</form>
|
|
149
|
+
);
|
|
150
|
+
}
|
|
62
151
|
```
|
|
63
152
|
|
|
64
|
-
|
|
153
|
+
A real chat also needs to show tool calls, approvals, questions, and sign-ins. Without them, a turn that waits on the user can't continue. The generated chat handles all of these. To build your own, see [Human-in-the-loop prompts](./overview#human-in-the-loop-prompts) and [Sign-ins](./overview#sign-ins-and-other-interactions).
|
|
65
154
|
|
|
66
|
-
|
|
155
|
+
## Give each conversation a URL
|
|
67
156
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
157
|
+
The generated chat gives every conversation its own address:
|
|
158
|
+
|
|
159
|
+
| URL | Shows |
|
|
160
|
+
| ---------------- | ----------------------------------------------------------- |
|
|
161
|
+
| `/` | The landing page |
|
|
162
|
+
| `/s` | A new, empty conversation |
|
|
163
|
+
| `/s/[sessionId]` | A saved conversation, including any reply still in progress |
|
|
164
|
+
|
|
165
|
+
The conversation page passes its session ID to the hook:
|
|
166
|
+
|
|
167
|
+
```tsx title="apps/web/app/s/[sessionId]/page.tsx"
|
|
168
|
+
import { SessionChat } from "@/app/_components/session-chat";
|
|
169
|
+
|
|
170
|
+
export default async function SessionPage({
|
|
171
|
+
params,
|
|
172
|
+
}: {
|
|
173
|
+
readonly params: Promise<{ readonly sessionId: string }>;
|
|
174
|
+
}) {
|
|
175
|
+
const { sessionId } = await params;
|
|
176
|
+
return <SessionChat key={sessionId} sessionId={sessionId} />;
|
|
177
|
+
}
|
|
79
178
|
```
|
|
80
179
|
|
|
81
|
-
|
|
180
|
+
```tsx title="apps/web/app/_components/session-chat.tsx"
|
|
181
|
+
"use client";
|
|
82
182
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
183
|
+
import { useEveAgent } from "eve/react";
|
|
184
|
+
|
|
185
|
+
export function SessionChat({ sessionId }: { readonly sessionId: string }) {
|
|
186
|
+
const agent = useEveAgent({
|
|
187
|
+
initialSession: { sessionId, streamIndex: 0 },
|
|
188
|
+
resume: true,
|
|
189
|
+
});
|
|
190
|
+
// Render agent.messages as in the basic chat.
|
|
191
|
+
}
|
|
86
192
|
```
|
|
87
193
|
|
|
88
|
-
|
|
194
|
+
Three things to get right:
|
|
89
195
|
|
|
90
|
-
|
|
196
|
+
- **Change the URL without the router.** Once `/s` creates a session, switch the address to `/s/{sessionId}` with the browser's own `replaceState`. Next.js patches `window.history`, and going through its router would remount the page and cut off the reply:
|
|
91
197
|
|
|
92
|
-
|
|
198
|
+
```ts
|
|
199
|
+
History.prototype.replaceState.call(
|
|
200
|
+
window.history,
|
|
201
|
+
window.history.state,
|
|
202
|
+
"",
|
|
203
|
+
`/s/${encodeURIComponent(sessionId)}`,
|
|
204
|
+
);
|
|
205
|
+
```
|
|
93
206
|
|
|
94
|
-
|
|
207
|
+
- **Use a `key` to switch conversations.** Keying the chat on the session ID gives each conversation a fresh hook.
|
|
208
|
+
- **Disable input while loading.** While `status` is `"resuming"`, show the messages but don't accept new ones.
|
|
95
209
|
|
|
96
|
-
|
|
97
|
-
| -------------------- | --------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
98
|
-
| `eveRoot` | `string` | Next.js app root | Eve project root, relative to the Next.js app root unless absolute. It may contain either one `agent/` or an `agents/` workspace. Do not combine with `agents`. |
|
|
99
|
-
| `agents` | `Record<string, ...>` | inferred for a workspace | Named eve agents to mount under `/eve/<name>/v1/*`. `withEve()` discovers project-level `agents/<name>/` members when `agents` and `eveRoot` are unset; otherwise each value is a root string or `{ root, buildCommand?, servicePrefix? }`. |
|
|
100
|
-
| `eveBuildCommand` | `string` | generated | Build command for generated eve Vercel services. In multi-agent mode this is the default for agents without their own `buildCommand`. |
|
|
101
|
-
| `servicePrefix` | `string` | `"/_eve_internal/eve"` | Private route namespace for legacy manual Vercel service configs and non-Vercel production proxying. Named agents derive unique defaults from this prefix. |
|
|
102
|
-
| `devServerTimeoutMs` | `number` | `180000` | Maximum time to wait for each eve development server to become available. |
|
|
210
|
+
## Authenticate users
|
|
103
211
|
|
|
104
|
-
|
|
212
|
+
The browser calls the agent on your own domain, so it sends your app's cookies along. The agent checks them in `agent/channels/eve.ts`.
|
|
105
213
|
|
|
106
|
-
|
|
107
|
-
import type { NextConfig } from "next";
|
|
108
|
-
import { withEve } from "eve/next";
|
|
214
|
+
Replace the generated `placeholderAuth()` with a function that reads your app's session:
|
|
109
215
|
|
|
110
|
-
|
|
216
|
+
```ts title="agent/channels/eve.ts"
|
|
217
|
+
import { type AuthFn, localDev, vercelOidc } from "eve/channels/auth";
|
|
218
|
+
import { eveChannel } from "eve/channels/eve";
|
|
219
|
+
import { getSession } from "@/lib/auth";
|
|
111
220
|
|
|
112
|
-
|
|
113
|
-
|
|
221
|
+
const appSession: AuthFn<Request> = async (request) => {
|
|
222
|
+
const session = await getSession(request);
|
|
223
|
+
if (!session) return null;
|
|
224
|
+
return {
|
|
225
|
+
authenticator: "app",
|
|
226
|
+
principalId: session.userId,
|
|
227
|
+
principalType: "user",
|
|
228
|
+
attributes: {},
|
|
229
|
+
};
|
|
230
|
+
};
|
|
231
|
+
|
|
232
|
+
export default eveChannel({
|
|
233
|
+
auth: [appSession, vercelOidc(), localDev()],
|
|
114
234
|
});
|
|
115
235
|
```
|
|
116
236
|
|
|
117
|
-
|
|
237
|
+
eve tries each entry in order:
|
|
118
238
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
239
|
+
- `appSession` accepts your signed-in users.
|
|
240
|
+
- `vercelOidc()` accepts your own server code and the eve terminal UI.
|
|
241
|
+
- `localDev()` accepts requests during local development only.
|
|
242
|
+
|
|
243
|
+
For a public demo, `none()` from `eve/channels/auth` lets anyone in. Don't use it for private data. See [Authentication](../auth-and-route-protection) for more.
|
|
244
|
+
|
|
245
|
+
If your app uses tokens instead of cookies, pass them to the hook:
|
|
246
|
+
|
|
247
|
+
```tsx
|
|
248
|
+
const agent = useEveAgent({
|
|
249
|
+
auth: { bearer: async () => await getAccessToken() },
|
|
122
250
|
});
|
|
123
251
|
```
|
|
124
252
|
|
|
125
|
-
|
|
253
|
+
### Sign in with Vercel
|
|
126
254
|
|
|
127
|
-
|
|
255
|
+
Choose **Sign in with Vercel** in the installer to let members of your Vercel team sign in, with nothing to build. It needs a linked Vercel project. Local development skips sign-in. See [Web Chat with Sign in with Vercel](../../channels/eve#web-chat-with-sign-in-with-vercel) for details.
|
|
128
256
|
|
|
129
|
-
|
|
130
|
-
"use client";
|
|
257
|
+
## Save conversations
|
|
131
258
|
|
|
132
|
-
|
|
259
|
+
eve already keeps every conversation, so a URL with a session ID is enough to reopen one. Add your own database when you want a chat list, titles, or faster page loads.
|
|
260
|
+
|
|
261
|
+
Keep your chat record separate from the eve session. Your record holds the title and owner; eve holds the messages. Store the session and its events alongside your record:
|
|
133
262
|
|
|
134
|
-
|
|
135
|
-
|
|
136
|
-
|
|
263
|
+
```ts
|
|
264
|
+
type SavedChat = {
|
|
265
|
+
id: string;
|
|
266
|
+
ownerId: string;
|
|
267
|
+
session: ClientSessionState | null; // from onSessionChange
|
|
268
|
+
events: SessionStreamEvent[]; // from onEvent
|
|
269
|
+
};
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
Then:
|
|
273
|
+
|
|
274
|
+
1. **Create the chat record before the first message.** If the user reloads mid-reply, the page can still find the conversation.
|
|
275
|
+
2. **Save as things happen.** Save `session` in `onSessionChange` and each event in `onEvent`. Don't wait for the reply to finish: a turn waiting on the user hasn't finished.
|
|
276
|
+
3. **Load on the server.** Read the saved chat in a Server Component, and pass `events` and `session` to the Client Component as `initialEvents` and `initialSession`, with `resume: true`. Saved messages show at once, and the live reply picks up from there.
|
|
277
|
+
4. **Store `session` as eve gives it to you.** Don't compute the cursor from the number of events.
|
|
278
|
+
|
|
279
|
+
See [Resume a saved session](./use-eve-agent#resume-a-saved-session) for exactly how saved events and catch-up fit together. Upgrading saved chats from eve v26? See [Upgrade to v27 events](../../concepts/upgrade-to-v27-events).
|
|
280
|
+
|
|
281
|
+
## Call the agent from server code
|
|
282
|
+
|
|
283
|
+
Route Handlers, Server Actions, and cron jobs can call the agent with `Client` from `eve/client`. Point it at your own domain, and sign requests with your project's Vercel OIDC token:
|
|
284
|
+
|
|
285
|
+
```ts title="apps/web/app/api/summarize/route.ts"
|
|
286
|
+
import { getVercelOidcToken } from "@vercel/oidc";
|
|
287
|
+
import { Client } from "eve/client";
|
|
288
|
+
import { getSession } from "@/lib/auth";
|
|
289
|
+
|
|
290
|
+
export async function POST(request: Request) {
|
|
291
|
+
const session = await getSession(request);
|
|
292
|
+
if (!session) return new Response("Unauthorized", { status: 401 });
|
|
293
|
+
|
|
294
|
+
const client = new Client({
|
|
295
|
+
baseUrl: new URL(request.url).origin,
|
|
296
|
+
auth: { vercelOidc: { token: async () => await getVercelOidcToken() } },
|
|
297
|
+
redirect: "manual",
|
|
298
|
+
});
|
|
299
|
+
|
|
300
|
+
const { delivery } = await client.sessions.create({ message: "Summarize today's tickets." });
|
|
301
|
+
const result = await delivery.result();
|
|
302
|
+
return Response.json({ status: result.status });
|
|
137
303
|
}
|
|
138
304
|
```
|
|
139
305
|
|
|
140
|
-
|
|
306
|
+
- Check who's calling before you call the agent, as above. The OIDC token gives your code the app's own access, so an unchecked route would let anyone use it.
|
|
307
|
+
- Install `@vercel/oidc`, and run `eve link` once so the token works locally.
|
|
308
|
+
- The token identifies your app, not a user. To act as the signed-in user, forward their cookie in `headers` instead.
|
|
309
|
+
- Without an incoming request, as in a cron job, use `https://${process.env.VERCEL_URL}` as the domain.
|
|
310
|
+
|
|
311
|
+
See [Client SDK](../client/overview) for more.
|
|
141
312
|
|
|
142
|
-
|
|
313
|
+
## Use multiple agents
|
|
143
314
|
|
|
144
|
-
|
|
315
|
+
With several agents, each one gets its own path, such as `/eve/support/v1/*`. Pick one in the hook:
|
|
145
316
|
|
|
146
317
|
```tsx
|
|
147
|
-
const
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
318
|
+
const support = useEveAgent({ agent: "support" });
|
|
319
|
+
```
|
|
320
|
+
|
|
321
|
+
- Give each chat page one agent, and include the agent name in its URLs.
|
|
322
|
+
- Remount the chat when switching agents.
|
|
323
|
+
- Set up authentication for each agent.
|
|
324
|
+
|
|
325
|
+
Both setups find the agents in your project automatically. With Next.js hosting, you can also list agents that live elsewhere:
|
|
326
|
+
|
|
327
|
+
```ts title="next.config.ts"
|
|
328
|
+
export default withEve(nextConfig, {
|
|
329
|
+
agents: {
|
|
330
|
+
support: "./apps/support-agent",
|
|
331
|
+
billing: { root: "./apps/billing-agent", buildCommand: "pnpm build:billing-agent" },
|
|
332
|
+
},
|
|
151
333
|
});
|
|
152
334
|
```
|
|
153
335
|
|
|
154
|
-
|
|
336
|
+
Use either `eveRoot` or `agents`, not both.
|
|
155
337
|
|
|
156
|
-
##
|
|
338
|
+
## Run, build, and deploy
|
|
157
339
|
|
|
158
|
-
|
|
340
|
+
### Run locally
|
|
159
341
|
|
|
160
|
-
-
|
|
161
|
-
-
|
|
162
|
-
- `/s/[sessionId]` attaches to that durable session, replays its transcript, and follows an in-flight turn.
|
|
342
|
+
- **Vercel services:** `npm run dev:all`.
|
|
343
|
+
- **Next.js hosting:** `npm run dev:web`. Next.js starts the agent for you. To use an agent you already started, set `EVE_BASE_URL` to its address.
|
|
163
344
|
|
|
164
|
-
|
|
345
|
+
### Deploy to Vercel
|
|
165
346
|
|
|
166
|
-
|
|
347
|
+
From the project root:
|
|
167
348
|
|
|
168
|
-
|
|
349
|
+
```bash
|
|
350
|
+
eve link
|
|
351
|
+
eve deploy
|
|
352
|
+
```
|
|
169
353
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
354
|
+
The app and each agent deploy together as one Vercel project. See [Deploy to Vercel](../deployment/vercel) for credentials and sandboxes.
|
|
355
|
+
|
|
356
|
+
<Callout type="warning" title="Next.js hosting from apps/web">
|
|
357
|
+
When the installer puts a Next.js-hosted app in `apps/web/`, Vercel doesn't build it by default.
|
|
358
|
+
In your Vercel project settings, set the Build Command to `npm run build:web` and the Output
|
|
359
|
+
Directory to `apps/web/.next`.
|
|
360
|
+
</Callout>
|
|
361
|
+
|
|
362
|
+
### Run a production build locally
|
|
363
|
+
|
|
364
|
+
With Next.js hosting, `next start` runs the built agent too. Build both first:
|
|
365
|
+
|
|
366
|
+
```bash
|
|
367
|
+
eve build
|
|
368
|
+
npm run build:web
|
|
369
|
+
next start apps/web
|
|
175
370
|
```
|
|
176
371
|
|
|
177
|
-
|
|
372
|
+
The agent listens on port `4274`. Set `EVE_NEXT_PRODUCTION_PORT` to change it.
|
|
178
373
|
|
|
179
|
-
|
|
374
|
+
With several agents, a root `eve build` doesn't build them for `next start`. Run `eve build` in each `agents/<name>/` directory instead.
|
|
180
375
|
|
|
181
|
-
-
|
|
182
|
-
- **Vercel.** The web app and the eve runtime deploy as a single project. `withEve()` writes Build Output `services` for eve and `routes` that send `/eve/v1/**` to that service before filesystem routing; the Next.js app itself remains the default app. Vercel assembles authored [schedules](../../schedules) into the project config as Vercel Cron Jobs, including correctly prefixed jobs for named agents, while cron entries owned by the Next.js app are preserved. By default, generated services run the installed eve binary from the agent root, so the agent directory does not need its own `package.json`. When the agent needs its own build step, set `eveBuildCommand`:
|
|
376
|
+
### Self-host
|
|
183
377
|
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
eveBuildCommand: "npm run build:eve",
|
|
187
|
-
});
|
|
188
|
-
```
|
|
378
|
+
- **Vercel services:** run the app and each agent with your own process manager and proxy. See [Self-host eve](../deployment/self-hosting#run-workspace-members).
|
|
379
|
+
- **Next.js hosting:** `next start` runs the agent for you. To run the agent yourself instead, put it behind a proxy that serves it under the private path `/_eve_internal/eve` (the `servicePrefix` option), then set `EVE_NEXT_PRODUCTION_ORIGIN` to that proxy's address when you build and start Next.js.
|
|
189
380
|
|
|
190
|
-
|
|
381
|
+
## Troubleshooting
|
|
191
382
|
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
383
|
+
| You see | Fix |
|
|
384
|
+
| -------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
|
|
385
|
+
| `401` "Production auth is not configured" | Replace `placeholderAuth()`. See [Authenticate users](#authenticate-users) |
|
|
386
|
+
| "The Next.js output directory `.next` was not found" on deploy | Set the Build Command and Output Directory. See [Deploy to Vercel](#deploy-to-vercel) |
|
|
387
|
+
| The reply stops after the first message | Change the URL with `History.prototype.replaceState`. See [Give each conversation a URL](#give-each-conversation-a-url) |
|
|
388
|
+
| Messages repeat or vanish after a reload | Save `session` from `onSessionChange` as is |
|
|
389
|
+
| `next dev` times out waiting for the agent | Raise `devServerTimeoutMs` |
|
|
390
|
+
| A custom channel route returns `404` with Vercel services | Route it to the agent in `vercel.ts`. See [Compose agents](../deployment/vercel#compose-agents-with-other-vercel-services) |
|
|
196
391
|
|
|
197
|
-
|
|
392
|
+
## Reference
|
|
198
393
|
|
|
199
|
-
|
|
200
|
-
|
|
201
|
-
|
|
202
|
-
|
|
394
|
+
### `withEve` options
|
|
395
|
+
|
|
396
|
+
Options for `withEve` from `eve/next`. All are optional.
|
|
397
|
+
|
|
398
|
+
| Option | Default | Purpose |
|
|
399
|
+
| -------------------- | ------------------------ | -------------------------------------------------------------------------------------------------- |
|
|
400
|
+
| `eveRoot` | The Next.js app root | Where your agent project lives |
|
|
401
|
+
| `agents` | Found automatically | Agents to mount at `/eve/<name>/v1/*`. Each is a path or `{ root, buildCommand?, servicePrefix? }` |
|
|
402
|
+
| `eveBuildCommand` | Runs the installed `eve` | Command that builds each agent |
|
|
403
|
+
| `devServerTimeoutMs` | `180000` | How long `next dev` waits for each agent to start |
|
|
404
|
+
| `servicePrefix` | `"/_eve_internal/eve"` | Private route path for self-hosted proxying and hand-written Vercel services |
|
|
203
405
|
|
|
204
|
-
|
|
406
|
+
### Environment variables
|
|
205
407
|
|
|
206
|
-
|
|
408
|
+
| Variable | Purpose |
|
|
409
|
+
| ---------------------------- | ---------------------------------------------------------------------------------------------------------- |
|
|
410
|
+
| `EVE_BASE_URL` | Next.js hosting, development: use an agent you already started |
|
|
411
|
+
| `EVE_NEXT_PRODUCTION_PORT` | Next.js hosting: first port for agents that `next start` runs. Defaults to `4274` |
|
|
412
|
+
| `EVE_NEXT_PRODUCTION_ORIGIN` | Next.js hosting: address of a proxy serving your agents under `servicePrefix`. Turns off automatic startup |
|
|
413
|
+
| `EVE_PUBLIC_ROUTE_PREFIX` | Self-hosting: an agent's public path, such as `/eve/support`, so callback links work |
|
|
207
414
|
|
|
208
415
|
## What to read next
|
|
209
416
|
|
|
210
|
-
- [Frontend overview](./overview): the
|
|
211
|
-
- [
|
|
212
|
-
- [
|
|
417
|
+
- [Frontend overview](./overview): everything the chat hook can do
|
|
418
|
+
- [Authentication](../auth-and-route-protection): checking who's calling
|
|
419
|
+
- [Deploy to Vercel](../deployment/vercel): services, credentials, and sandboxes
|
|
420
|
+
- [Client SDK](../client/overview): calling the agent from server code
|