Client Overview

Purpose and Scope

The eve client is the TypeScript entrypoint for applications that want to talk to an eve agent through the default HTTP session API without implementing the wire protocol themselves. It is intended for scripts, server-to-server integrations, tests, evals, backend jobs, and custom interfaces that need durable conversations, streaming output, and typed error handling. In the documentation spine, it sits between high-level frontend hooks and low-level route calls: it gives developers direct control over sessions while still hiding the repetitive POST request and newline-delimited stream handling that every raw integration would otherwise need to reproduce.

Sources: docs/guides/client/overview.mdx

Use this page when you are deciding whether to call eve from application code with the TypeScript SDK, a browser hook, or raw HTTP. Browser chat surfaces usually start with the frontend integration layer, while route-level diagnostics and custom clients can study the sessions and streaming contract directly. The client overview is the bridge: it explains how to bind a host, verify agent availability, inspect a development agent, provide credentials, and create independent session objects for separate conversations. That makes it useful for both production service calls and local automation around an agent.

Sources: docs/guides/client/overview.mdx

Relevant Source Files

• docs/guides/client/overview.mdx - First-party guide for the eve/client TypeScript SDK, including client construction, health checks, agent inspection, authentication, headers, redirect policy, and session creation.

Core Primitives

The main primitive is Client, imported from the client entrypoint. A client instance binds the origin where eve routes are mounted together with an authentication policy, an optional header policy, and the stream reconnection budget described by the guide. The host can be a full local or deployed URL for scripts and backend services, or an empty same-origin value for browser-adjacent integrations. Treat a client as a configured transport object rather than a single conversation: it knows how to reach the agent and how to attach credentials, but it does not by itself represent a durable dialogue.

Sources: docs/guides/client/overview.mdx

A ClientSession is the conversation primitive. Create one with the client session factory whenever an application begins a separate user or workflow conversation. Each session tracks its own session identifier, continuation token, and stream cursor, so one configured client can safely own many active sessions at once. This separation matters in multi-user interfaces, test suites, and backend jobs that run several conversations in parallel. The guide demonstrates separate session objects for different accounts, which clarifies that state belongs to the session object, not to the shared client configuration.

Sources: docs/guides/client/overview.mdx

Basic Client Setup

A minimal setup imports the client and points it at the local development server or a deployed agent origin. The host should be the origin where the eve routes are mounted. For local development, the documented example uses a loopback URL; for same-origin deployments, an empty origin can be appropriate because requests resolve against the current site. Keeping the host explicit in scripts is usually clearer because scheduled jobs, eval runners, and server-to-server integrations may run outside the web app that proxies frontend traffic.

import { Client } from "eve/client";
 
const client = new Client({
  host: "http://127.0.0.1:3000",
});

The client also exposes lightweight inspection calls before a session is created. Use the health check when an automation script should fail early if the agent route is unavailable or unhealthy. Non-successful responses are represented as client errors carrying the HTTP status and response body, which lets callers distinguish route failures from a completed agent turn that produced an application-level result. The info call is aimed at development inspection: it validates the full response before returning agent metadata such as the configured name and model identity.

Sources: docs/guides/client/overview.mdx

const health = await client.health();
console.log(health.status, health.workflowId);
 
const info = await client.info();
console.log(info.agent.name, info.agent.model.id);

Sessions, Messages, and Output

After constructing a client, create a session for each conversation and send turns through that session. A fresh session starts when the first message is sent, and follow-up turns continue the same conversation when the session is waiting for another message. The message guide describes plain text sends as the simplest shape and full turn payloads when callers need additional client context, attachments, headers, or human-in-the-loop responses. The response returned by a send contains handles such as the session identifier and continuation token before the stream has been fully consumed.

Sources: docs/guides/client/overview.mdx

const session = client.session();
 
const response = await session.send("What is the weather in Brooklyn?");
console.log(response.sessionId, response.continuationToken);
 
const result = await response.result();
console.log(result.status, result.message);

Consuming agent output is intentionally a two-step process. The POST that starts or resumes a turn can return metadata quickly, while the final result requires reading the event stream until the turn reaches a waiting, completed, or failed state. The higher-level result helper collects observed events and exposes the final assistant message when one completed. When a turn fails inside the session stream, the result status can reflect that failure instead of throwing; transport errors and route errors remain exceptional. This distinction helps application code separate agent execution outcomes from network or authorization problems.

Authentication and Headers

Credential handling is part of the client configuration because every health check, info request, session creation call, and stream reconnection may need the same policy. The guide documents bearer authentication, basic authentication, and a Vercel OIDC mode. Bearer values and basic passwords can be static strings or functions, and functions are evaluated before every HTTP call. That makes rotating credentials and short-lived access tokens practical without rebuilding the client object for each request. For Vercel OIDC-protected deployments, the token resolver is used per request and sent in the required credential positions.

Sources: docs/guides/client/overview.mdx

const client = new Client({
  host: "https://agent.example.com",
  auth: {
    bearer: async () => await getAccessToken(),
  },
});

Headers are separate from authentication so callers can attach route-specific data such as protection bypass tokens, tenant hints, request identifiers, or other deployment metadata. The overview allows static or dynamic header policies at the client level, and individual turns can also include per-request headers. For credential-bearing clients, the redirect policy is an important security setting. Setting redirects to manual or error prevents fetch from forwarding custom authorization headers to another origin during inspection requests, custom fetches, session creation, or event stream requests.

Sources: docs/guides/client/overview.mdx

const client = new Client({
  host: "https://agent.example.com",
  headers: async () => ({
    "x-vercel-protection-bypass": await getBypassToken(),
  }),
  redirect: "manual",
});
 
const response = await client.session().send({
  message: "Run the check.",
  headers: { "x-request-id": requestId },
});
 
await response.result();

System-to-Code Mapping

The client overview document maps public SDK tasks to the concrete reader workflow. Client construction maps to route origin selection and shared request policy. Health checks map to early failure detection for automation. Agent inspection maps to development-time verification of the running agent and its model configuration. Authentication maps to route protection for the eve HTTP channel, including credentials that may change between requests. Session creation maps to durable conversations, where separate session objects preserve independent handles and cursors. This organization is task-oriented rather than file-oriented, so readers can start with the operation they need and then move deeper into message or continuation details.

Sources: docs/guides/client/overview.mdx

The same mapping also clarifies boundaries. The client is not the preferred first stop for a standard browser chat component, because frontend hooks provide rendering-oriented behavior above it. It is also not the raw protocol reference, because sessions, runs, event names, continuation tokens, and stream reconnection details are documented in the lower-level concepts page. In practice, use the SDK when TypeScript code needs programmatic control, repeatable tests, eval setup, or a custom user interface that still wants a supported abstraction over the default eve route family.

Next Steps

Start with a minimal client pointed at your local development host, call the health endpoint, and then create one session per conversation you need to drive. Add authentication only after the unprotected local flow is working, then tighten redirect handling before sending real credentials to deployed routes. If you are building a chat UI, compare this SDK flow with the frontend guide before hand-rolling rendering behavior. If you need resumability, typed outputs, or detailed stream rendering, continue into the messages, continuations, output schema, and sessions-and-streaming pages.

Sources: docs/guides/client/overview.mdx