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.