---
title: useEveAgent (Svelte)
description: Svelte 5 binding that drives an Eve agent session from the browser.
---

# useEveAgent (Svelte)



`useEveAgent()` from `eve/svelte` is the browser side of an Eve session in a Svelte 5 app. Call it once for a long-lived session you can send turns to, with every stream event projected into rune-friendly reactive data. On SvelteKit, the [Vite plugin](./sveltekit) wires up the routes. The [frontend overview](./overview) covers the model shared across frameworks.

## Basic usage

Import from `eve/svelte` and read the reactive getters directly. No `$` prefix:

```svelte
<script lang="ts">
  import { useEveAgent } from "eve/svelte";

  const agent = useEveAgent();
</script>

{#each agent.data.messages as message}
  <p>{message.role}: {JSON.stringify(message.parts)}</p>
{/each}
```

## What it returns

| Property  | Type                                        | Description                                                               |
| --------- | ------------------------------------------- | ------------------------------------------------------------------------- |
| `data`    | `TData`                                     | Projected state. With the default reducer, `EveMessageData` (`messages`). |
| `status`  | `UseEveAgentStatus`                         | `"ready"`, `"submitted"`, `"streaming"`, or `"error"`.                    |
| `error`   | `Error \| undefined`                        | Last transport-level error.                                               |
| `events`  | `readonly HandleMessageStreamEvent[]`       | Raw server events for this session.                                       |
| `session` | `SessionState`                              | Snapshot of session state.                                                |
| `send`    | `(input: SendTurnPayload) => Promise<void>` | Send text or a full turn (multi-part, attachments, HITL responses).       |
| `stop`    | `() => void`                                | Abort the in-flight request.                                              |
| `reset`   | `() => void`                                | Clear state and start a new session.                                      |

These state fields are reactive getters, so read them straight from templates, `$derived`, or `$effect`. They are not stores, so don't prefix them with `$`.

## Send a message

```svelte
<script lang="ts">
  import { useEveAgent } from "eve/svelte";

  const agent = useEveAgent();
  let message = $state("");

  async function handleSubmit() {
    const text = message.trim();
    if (!text) return;
    message = "";
    await agent.send({ message: text });
  }
</script>

<form onsubmit={(event) => {
  event.preventDefault();
  void handleSubmit();
}}>
  <input bind:value={message} placeholder="Type a message..." />
  <button type="submit">Send</button>
</form>
```

When a turn is more than plain text, reach for `send()`. Attachments follow the AI SDK `UserContent` format. Send file data as a base64 `data:` URL so it survives the JSON transport:

```ts
const bytes = new Uint8Array(await file.arrayBuffer());
const base64 = btoa(String.fromCodePoint(...bytes));

await agent.send({
  message: [
    { type: "text", text: "Describe this image." },
    { type: "file", data: `data:${file.type};base64,${base64}`, mediaType: file.type },
  ],
});
```

## Human-in-the-loop prompts

A tool opts into approval with `needsApproval` ([Tools](../../tools)). When one fires, the pending request rides along on a `dynamic-tool` part of the latest message at `part.toolMetadata?.eve?.inputRequest`. Read it, then answer through the same session with `agent.send({ inputResponses })`:

```ts
import type { EveDynamicToolPart, EveMessagePart } from "eve/svelte";

const isDynamicToolPart = (part: EveMessagePart): part is EveDynamicToolPart =>
  part.type === "dynamic-tool";

const request = agent.data.messages
  .at(-1)
  ?.parts.filter(isDynamicToolPart)
  .map((part) => part.toolMetadata?.eve?.inputRequest)
  .find((value) => value !== undefined);

if (request) {
  await agent.send({
    inputResponses: [{ requestId: request.requestId, optionId: "approve" }],
  });
}
```

The find-and-answer flow is identical across frameworks. The [React hook reference](./overview) covers the longer walkthrough.

## Stop, reset, and resume

`stop()` aborts the in-flight stream. `reset()` wipes state and starts a fresh session. To resume across reloads, hand `initialSession` the state you saved earlier and use `onSessionChange` to persist the cursor as it advances:

```ts
const agent = useEveAgent({
  initialSession: savedSessionState,
  initialEvents: savedEvents,
  onSessionChange: (session) => {
    localStorage.setItem("eve-session", JSON.stringify(session));
  },
});
```

## Custom host and credentials

Point `host` at an Eve server on a different origin, and pass credentials through `auth` or `headers`. When you supply a function, it re-resolves before every request:

```ts
const agent = useEveAgent({
  host: "https://agent.example.com",
  headers: async () => ({
    authorization: `Bearer ${await getAccessToken()}`,
  }),
});
```

## Attach page context per turn

`clientContext` adds ephemeral context for the next model call and nothing more. Strings (or an array of strings) become user-role context messages; an object is JSON-serialized into one. It rides along with a message or HITL response, never dispatches a turn on its own, and never lands in durable session history. Pass it to `send()`:

```ts
await agent.send({
  message: "What should I do on this screen?",
  clientContext: { route: "/billing", plan: "pro", seatsUsed: 4 },
});
```

To attach the same context to every turn without threading it through each call site, pass `prepareSend`. It runs right before each send and returns the (possibly augmented) turn:

```ts
const agent = useEveAgent({
  prepareSend: (input) => ({
    ...input,
    clientContext: { route: location.pathname },
  }),
});
```

## Lifecycle callbacks

The binding takes a few per-turn callbacks:

* `onEvent(event)`: fires for each Eve stream event as it arrives.
* `onError(error)`: fires with the last `Error` when a turn fails.
* `onFinish(snapshot)`: fires with the final snapshot once a turn settles.
* `onSessionChange(session)`: fires when the session cursor advances. Persist it to resume across reloads.

```ts
const agent = useEveAgent({
  onEvent: (event) => console.debug(event.type),
  onError: (error) => console.error(error.message),
  onFinish: (snapshot) => console.log(snapshot.status),
});
```

Two more options tune turn behavior:

* `optimistic` (default `true`): projects submitted user messages into `data` before Eve confirms them with a `message.received` event. These are reducer-facing projection events only; `events` stays the authoritative Eve stream.
* `maxReconnectAttempts` (default `3`): stream reconnection budget per turn.

## Custom reducer

The default reducer projects events into `{ messages }` (`EveMessageData`). To shape `data` differently, pass a `reducer` implementing `EveAgentReducer<TData>`:

```ts
import { useEveAgent } from "eve/svelte";
import type { EveAgentReducer } from "eve/svelte";

interface ToolLog {
  readonly toolCalls: number;
}

const toolCounter: EveAgentReducer<ToolLog> = {
  initial: () => ({ toolCalls: 0 }),
  reduce: (data, event) =>
    event.type === "actions.requested" ? { toolCalls: data.toolCalls + 1 } : data,
};

const agent = useEveAgent({ reducer: toolCounter });
// agent.data is ToolLog
```

`reduce(data, event)` receives both authoritative Eve stream events and client projection events (`client.message.submitted`, `client.message.failed`, `client.input.responded`). Handle the client events too if you want optimistic and HITL state in your projection. Otherwise, return `data` unchanged for them.

## What to read next

* [SvelteKit](./sveltekit): Vite plugin setup
* [Frontend overview](./overview): the shared integration model
* [Sessions, runs & streaming](../../concepts/sessions-runs-and-streaming)


---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)