experimental library

Experimental Genkit APIs (agents, sessions, snapshots, live/bidi models).

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. Import them only if you accept that churn:

import 'package:genkit/genkit.dart';
import 'package:genkit/experimental.dart';

final ai = Genkit(plugins: [googleAI()]);
final agent = ai.defineAgent(name: 'weather', prompt: '...');

The browser-safe subset lives in package:genkit/experimental_client.dart and the dart:io extras in package:genkit/experimental_io.dart.

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

Agent<State>
A configured, registered agent.
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).
AgentFnOptions
Options handed to the handler of a custom agent.
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.
BidiModel<CustomOptions>
Experimental: lives behind package:genkit/experimental.dart.
BidiModelRef<CustomOptions>
Experimental: lives behind package:genkit/experimental.dart.
ClientTransform
Projects an agent's server-side data onto the view a client should see.
DetachedTask<State>
A handle to a background (detached) task.
GenerateBidiSession
Experimental: lives behind package:genkit/experimental.dart.
InMemorySessionStore
In-memory implementation of persistent session store.
Session<State>
State manager for a session turn, tracking messages, custom state, and artifacts.
SessionRunner<State>
Executor responsible for running turns over input streams and persisting state.
SessionStore
Interface for persistent session snapshot storage.
SnapshotChangeNotifier
Optional capability: a store may notify listeners when a snapshot's state changes (used by the detach/poll path).
SnapshotMetadataReader
Optional capability layered on SessionStore for answering a metadata-only read (GetSnapshotDataInput.metadataOnly) without loading the row's state.
TurnContext
Per-turn context handed to the handler passed to SessionRunner.run.
TurnResult
Result returned by a single turn handler passed to SessionRunner.run.

Extensions

GenkitAgents on Genkit
Experimental agent-authoring methods on Genkit.
GenkitBidi on GenkitAI
Experimental live-session method on GenkitAI.
GenkitBidiModel on Genkit
Experimental bi-directional authoring methods on Genkit.

Functions

applyPatch(Object? document, JsonPatch patch) → Object?
Applies an RFC 6902 JSON Patch to document, returning the new value.
bidiModelRef<CustomOptions>(String name, {SchemanticType<CustomOptions>? customOptions}) → BidiModelRef<CustomOptions>
Experimental: lives behind package:genkit/experimental.dart.
diff(Object? from, Object? to) → JsonPatch
Computes an RFC 6902 JSON Patch that transforms from into to.
generateUuidV4() → String
Generates a random RFC 4122 version-4 UUID.
getCurrentSession<State>() → Session<State>?
Returns the Session instance active in the current context, or null.
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.
reserveSnapshotId() → String
Mints a new snapshotId (a plain random UUID).
runWithSession<O>(Session session, O fn()) → O
Utility to execute a function bound to a Session instance context.
validateResumeAgainstHistory(AgentResume resume, List<Message> history) → void
Validates that every resume.restart and resume.respond entry references a tool request that actually exists in the session history.

Typedefs

AgentFn<State> = Future<AgentResult> Function(SessionRunner<State> sess, AgentFnOptions options)
Function handler definition for custom agent actions.
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?}.
SnapshotMutator = SessionSnapshot? Function(SessionSnapshot? current)
A function that receives the current snapshot and returns the updated snapshot to persist.
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.
SessionError
Error thrown during session execution.