experimental_client library

Browser-safe experimental Genkit client APIs (agent client, snapshots).

These APIs are NOT covered by the package's semantic-versioning stability guarantees. They may change or be removed in any MINOR release without a major version bump. This is the client counterpart to package:genkit/client.dart:

import 'package:genkit/client.dart';
import 'package:genkit/experimental_client.dart';

This is the canonical home for the browser-safe agent-client symbols. They are also re-exported from package:genkit/experimental.dart; naming this library (below) is what breaks the dartdoc canonicalization tie so the docs land here rather than emitting ambiguous-reexport warnings.

To opt out of the analyzer warning on this import (you have accepted the instability), add to your analysis_options.yaml:

analyzer:
  errors:
    experimental_member_use: ignore

Classes

AgentApi<State>

The transport-agnostic surface for talking to an agent. The same shape is returned by ai.defineAgent(...) on the server and by remoteAgent(...) on the client.

AgentChat<State>

A stateful conversation with an agent. Tracks state across turns so callers do not have to thread snapshotId/state by hand.

AgentChunk<State>

A streamed chunk. Mirrors GenerateResponseChunk and adds the agent fields (artifact, custom).

AgentInterrupt<Input, Output>

A single tool request a turn paused on. respond/restart are builders: they return the part to put into a resume payload; they do not send.

AgentResponse<State>

The completed result of a turn. Mirrors GenerateResponse and adds the agent fields (snapshotId, state, artifacts).

AgentSnapshot<State>

A generate-style, typed veneer over a raw SessionSnapshot. Mirrors how AgentResponse wraps an AgentOutput: it delegates the snapshot's scalar fields and surfaces the aggregates (messages, artifacts) and the typed custom state (custom), while keeping the untyped wire objects reachable via sessionState / raw.

AgentTransport

The pluggable backend the agent-client core runs over. Implementations exist for the in-process server agent (driving the agent action directly) and for the HTTP remoteAgent (driving stream/run calls).

AgentTurn<State>

A single in-flight turn — the analog of generateStream's {stream, response}, plus abort.

DetachedTask<State>

A handle to a background (detached) task.

Functions

applyPatch(Object? document, JsonPatch patch) → Object?

Applies an RFC 6902 JSON Patch to document, returning the new value.

diff(Object? from, Object? to) → JsonPatch

Computes an RFC 6902 JSON Patch that transforms from into to.

remoteAgent<State>({required String url, String? getSnapshotUrl, String? abortUrl, HeadersResolver? headers, AgentStateManagement? stateManagement, SchemanticType<State>? stateSchema, Client? httpClient}) → AgentApi<State>

Creates a typed client for talking to a Genkit agent over HTTP.

Typedefs

HeadersResolver = FutureOr<Map<String, String>?> Function()

Resolves request headers, either statically or per request.

JsonPatch = List<JsonPatchOperationMap>

An RFC 6902 JSON Patch: an ordered list of operations.

JsonPatchOperationMap = Map<String, dynamic>

A single RFC 6902 (JSON Patch) operation, as a plain JSON map: {op, path, from?, value?}.

TurnStream = ({Future<AgentOutput> output, Stream<AgentStreamChunk> stream})

The streamed result of a single turn: incremental stream chunks plus an output future for the final, non-throwing AgentOutput (failures resolve with finishReason: 'failed').

Exceptions / Errors

AgentError<State>

Thrown when a turn fails. Carries the last-good state so the session is recoverable.