---
title: "Eve"
description: "Trace durable Eve agent turns with model usage, tool activity, asynchronous tasks, and parent-child session links."
canonical_url: "https://www.blyp.dev/docs/ai/eve"
markdown_url: "https://www.blyp.dev/docs/ai/eve.md"
last_updated: "1970-01-01"
x_farming_labs_generated_preamble: true
agent:
  task: "Add durable turn-level tracing to an Eve agent with the Blyp hook."
  outcome: "Each completed, failed, or cancelled turn emits one aggregated ai_trace through the configured Blyp destinations."
  appliesTo:
    package:
      - "@blyp/core"
      - "eve"
      - "ai"
  prerequisites:
    - "Node.js 24 or newer"
    - "Eve ~0.80.1"
    - "and Eve's AI SDK 7 peer are installed."
  files:
    - "agent/agent.ts"
    - "agent/hooks/blyp.ts"
    - "blyp.config.ts"
  commands:
    - "pnpm add @blyp/core@0.1.34 eve@~0.80.1 ai@^7.0.137"
  sideEffects:
    - "Enabled capture persists sanitized content in Eve durable state and configured Blyp destinations."
  verification:
    - "Complete a multi-step turn and confirm one ai_trace with sdk eve-sdk and operation eve.turn."
  rollback:
    - "Remove agent/hooks/blyp.ts and the Blyp-specific external dependency setting."
  failureModes:
    - symptom: "Agent build cannot resolve Blyp configuration dependencies."
      resolution: "Keep @blyp/core in build.externalDependencies in the agent configuration."
    - symptom: "A waiting turn has no final trace."
      resolution: "Resume and complete or cancel the turn; turn.waiting intentionally keeps its trace open."
---

# Eve
URL: /docs/ai/eve
LLM index: /llms.txt
Description: Trace durable Eve agent turns with model usage, tool activity, asynchronous tasks, and parent-child session links.
Related: /docs/ai/tracing, /docs/ai/privacy-and-capture, /docs/ai/better-agent

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Add durable turn-level tracing to an Eve agent with the Blyp hook.
Outcome: Each completed, failed, or cancelled turn emits one aggregated ai_trace through the configured Blyp destinations.

### Applies To

- Package: `@blyp/core`, `eve`, `ai`

### Prerequisites

- Node.js 24 or newer
- Eve ~0.80.1
- and Eve's AI SDK 7 peer are installed.

### Files

- `agent/agent.ts`
- `agent/hooks/blyp.ts`
- `blyp.config.ts`

### Commands

- `pnpm add @blyp/core@0.1.34 eve@~0.80.1 ai@^7.0.137`

### Side Effects

- Enabled capture persists sanitized content in Eve durable state and configured Blyp destinations.

### Verification

- Complete a multi-step turn and confirm one ai_trace with sdk eve-sdk and operation eve.turn.

### Rollback

- Remove agent/hooks/blyp.ts and the Blyp-specific external dependency setting.

### Failure Modes

- Agent build cannot resolve Blyp configuration dependencies. — Recovery: Keep @blyp/core in build.externalDependencies in the agent configuration.
- A waiting turn has no final trace. — Recovery: Resume and complete or cancel the turn; turn.waiting intentionally keeps its trace open.
<!-- farming-labs:agent-contract:end -->

# Eve

Use Node.js 24+, Eve `~0.80.1`, and AI SDK 7. Keep `@blyp/core` external in the agent build,
then default-export `blypHook()` from `agent/hooks/blyp.ts`. Install one hook per agent and
leave content capture disabled unless required. Complete a turn to verify its aggregated trace.

Use `@blyp/core/ai/eve` to emit one aggregated `ai_trace` for each Eve agent turn. Blyp follows model steps, tool calls, asynchronous tasks, waiting periods, and delegated sessions while retaining sanitized trace state across workflow boundaries and process restarts.

Added in `@blyp/core@0.1.34`, the integration uses Eve's hooks and durable context APIs. Register the hook in the agent that executes the turn.

## Install

Run Eve on **Node.js 24 or newer**, with Eve `~0.80.1` and its AI SDK 7 peer:

```bash
bun add @blyp/core@0.1.34 eve@~0.80.1 ai@^7.0.137
```

Eve tracing uses `eve/hooks` and `eve/context`. Blyp's separate [Vercel AI SDK adapter](/docs/ai/vercel-ai-sdk) targets AI SDK 6. Keep that integration separate from the Eve application's SDK 7 dependency.

## Quick start

### Keep Blyp external

Merge `@blyp/core` into your existing agent's `build.externalDependencies`. Preserve the agent's model, other settings, and any existing external dependencies:

```ts
// agent/agent.ts — excerpt from your existing defineAgent configuration
build: {
  externalDependencies: ["@blyp/core"],
},
```

This preserves the dependency-relative package paths used by Blyp's configuration loader when Eve builds authored modules.

### Register the hook

Create a hook file in the agent's hooks directory. Eve discovers its default export automatically:

```ts
// agent/hooks/blyp.ts
import { blypHook } from "@blyp/core/ai/eve";

export default blypHook();
```

The hook uses the active request-scoped Blyp logger when available, otherwise the root logger. Pass `logger` to use an explicit logger. Traces flow through that logger's configured destinations; configure those in [blyp.config.ts](/docs/configuration).

Content capture is disabled by default. Usage, timing, outcomes, and available session and tool identities remain useful without recording prompts or payloads.

### Verify a turn

Run your existing Eve agent through a turn containing more than one model step or a tool call. After the turn completes, inspect your Blyp output for one `ai_trace` with:

- `ai.sdk: "eve-sdk"`
- `ai.provider: "eve"`
- `ai.operation: "eve.turn"`
- `ai.method: "agent.turn"`
- session and turn IDs in `ai.metadata`
- aggregated usage when Eve reports it

A waiting turn remains open. Resume it to completion, fail it, or cancel it before expecting a final trace. When testing a short-lived process with an explicit logger, await that logger's flush before exiting.

## Turn lifecycle

| Eve activity | Blyp behavior |
| --- | --- |
| Turn starts | Initializes durable trace state and resolves turn metadata. |
| Model steps | Tracks step counts, reported model identity, usage, and finish reason. |
| Tool calls | Records tool identity, status, timing, and optionally inputs and outputs. |
| `turn.waiting` | Keeps the turn open and records waiting information. |
| Interim assistant messages | Updates the turn without finalizing it. |
| `task.settled` | Finalizes the associated asynchronous tool result. |
| `turn.completed` | Emits the completed turn's trace. |
| `turn.failed` | Emits a failed trace at error severity. |
| `turn.cancelled` | Emits an informational trace with outcome `cancelled` and finish reason `abort`. |
| Session completes or fails with an outstanding turn | Finalizes the trace with `incompleteEnd: true`. |

Timing comes from Eve event timestamps and includes time spent waiting. When tracing starts after a turn has already begun, the trace records `incompleteStart: true`.

Tool partial outputs replace earlier previews. An asynchronous task receipt does not finish the tool; its result settles on `task.settled`. When output capture is enabled, structured results take precedence over assistant text.

## Options

The entrypoint exports `blypHook`, `BlypEveOptions`, and `BlypEveTurnResolver`:

```ts
import {
  blypHook,
  type BlypEveOptions,
  type BlypEveTurnResolver,
} from "@blyp/core/ai/eve";
```

| Option | Behavior |
| --- | --- |
| `logger` | Explicit Blyp logger; otherwise inherits request context or uses the root logger. |
| `provider` | Provider label; defaults to `"eve"`. |
| `model` | Optional model override. Otherwise uses the reported step model ID, or `"unknown"` before a model step. |
| `operation` | Operation name; defaults to `"eve.turn"`. |
| `metadata` | Custom metadata merged into the trace. |
| `stateKey` | Durable state key; defaults to `"blyp.ai.eve.v1"`. |
| `resolveTurn` | Synchronous or asynchronous resolver for per-turn identity and metadata. |
| `capture` | Opt-in input, output, tool payload, reasoning, and stream capture. Raw provider payloads are unavailable. |
| `exclude` | Request, response, and metadata path exclusions, plus tool-name exclusions. |
| `limits` | Content, event, and tool-call limits. |
| `hooks` | Shared Blyp `onStart`, `onEvent`, `onFinish`, and `onError` callbacks. |

Blyp callbacks receive normalized tracing context; `onEvent` receives normalized Blyp AI events. Resolver and callback failures do not stop the agent.

### Resolve turn metadata

Use `resolveTurn` to label turns from the agent and session identity. The resolver receives `sessionId`, `turnId`, `agentName`, and optional `channelKind`, `parentSessionId`, `parentTurnId`, `parentCallId`, and `rootSessionId`.

```ts
// agent/hooks/blyp.ts
import { blypHook } from "@blyp/core/ai/eve";

export default blypHook({
  operation: "support.turn",
  metadata: { team: "support" },
  resolveTurn: ({ agentName, parentSessionId }) => ({
    operation: `support.${agentName}`,
    metadata: {
      workflow: agentName,
      delegated: Boolean(parentSessionId),
    },
  }),
});
```

The resolver can return `provider`, `model`, `operation`, and `metadata`. Resolved values override static options, and resolved metadata is merged over static metadata. Blyp's session identity and outcome fields take precedence over user metadata.

## Usage and trace fields

Blyp sums usage from reported `step.completed` model calls. It does not add session totals, which already include delegated usage. Missing usage stays absent.

| Reported value | Trace field |
| --- | --- |
| Input tokens | `ai.usage.inputTokens` |
| Output tokens | `ai.usage.outputTokens` |
| Cache read tokens | `ai.usage.cachedInputTokens` |
| Cost in USD | `ai.metadata.costUsd` |
| Cache write tokens | `ai.metadata.cacheWriteTokens` |

Trace metadata also includes agent name, session/turn IDs, available parent/root links, channel kind, step and failure counts, waiting information, child-session links, and outcome.

Runtime error messages and details are omitted. Failed traces retain the runtime error code with a generic failure message.

### Delegated agents

Install the hook separately in each child agent to trace its turns. The parent hook records delegation links; child turns need their own hook.

Install one hook per agent. If an agent deliberately uses independent Blyp hooks, assign a distinct `stateKey` to each to keep their accumulators separate.

## Privacy and durable state

Input, output, reasoning, tool payloads, and stream content are disabled by default. Enable only the fields needed for your workflow:

```ts
// agent/hooks/blyp.ts
import { blypHook } from "@blyp/core/ai/eve";

export default blypHook({
  capture: {
    input: true,
    output: true,
    toolInputs: false,
    toolOutputs: false,
    reasoning: false,
    streamEvents: false,
  },
  exclude: {
    requestPaths: ["parts.0.url"],
    responsePaths: ["private"],
    metadataPaths: ["internal"],
    toolNames: ["private_lookup"],
  },
  limits: {
    maxContentBytes: 16_384,
    maxEvents: 200,
    maxToolCalls: 50,
  },
});
```

Enabled content is redacted, excluded, and bounded **before it enters Eve's durable per-session state**, then sanitized again for logging. The accumulator shares one content budget; custom metadata has a separate budget of the same size. Recent block and tool details replace older details at their limits while aggregate usage continues. Dropped data sets `ai.metadata.truncated`.

Incomplete streamed tool-input JSON is not persisted. Validated tool inputs come from `actions.requested`. Raw provider payload capture is unsupported; `exclude.providerOptions` has no effect because this hook does not serialize provider options.

Captured content remains in Eve's durable state until the turn ends and is subject to Eve's storage and retention policies. Configured Blyp destinations have their own retention. See [AI Privacy & Capture](/docs/ai/privacy-and-capture) for shared controls.

## Recovery and delivery

Blyp restores a bounded, sanitized accumulator across Eve workflow boundaries and process restarts. Recovery preserves observed turn state; it does not ingest historical streams.

Delivery through Blyp destinations is best effort. Log emission and Eve's state checkpoint are separate operations. A crash between them can duplicate a trace, using the same persisted trace ID where available.

A retried model step can emit new events with the same turn and step coordinates without an attempt identifier. Usage therefore describes observed reported calls, including retries, rather than only the attempt that eventually succeeded. Durable state does not provide exactly-once log delivery.

## Troubleshooting

- **The hook does not load:** confirm Node.js 24+, Eve `~0.80.1`, AI SDK 7, and `@blyp/core@0.1.34` or newer. Default-export the hook from the agent's hooks directory.
- **Agent build fails inside Blyp configuration loading:** merge `@blyp/core` into `build.externalDependencies` and rebuild the agent.
- **No trace appears while the agent waits:** complete or cancel the turn. Waiting and interim messages keep it open.
- **Model is `unknown`:** no model step has reported its identity yet. Supply `model` or a resolver override if you need a fixed label.
- **Child turns are missing:** install the hook in each child agent as well as the parent.
- **Content is absent or truncated:** check capture flags, exclusions, and limits. These apply before durable storage, so discarded content cannot be recovered later.
- **Duplicate traces appear after a crash:** checkpoint and log emission are not atomic. Use trace IDs when investigating duplicate delivery.

For Eve's lifecycle and persistence contracts, see [hooks](https://eve.dev/docs/guides/hooks), [durable state](https://eve.dev/docs/concepts/state), and [session lifecycle](https://eve.dev/docs/concepts/sessions-runs-and-streaming).

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).