Skip to content

API Reference

!!! note Full Genkit documentation is available at genkit.dev

genkit

Genkit: generation, tools, structured output, flows and agents for Python.

Register plugins, define flows and tools, and run generation.

Example

from genkit import Genkit from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

@ai.flow async def suggest_dish(cuisine: str) -> str: res = await ai.generate(prompt=f'Suggest one {cuisine} dish.') return res.text

async def main() -> None: print(await suggest_dish('Thai')) # => Green curry with chicken

if name == 'main': ai.run_main(main())

ToolChoice = Literal['auto', 'required', 'none'] module-attribute

Whether the model may call tools (auto), must call one (required), or must not (none).

Document

Bases: genkit._core._base.GenkitModel

Multi-part document that can be embedded, indexed, or retrieved.

Source code in packages/genkit/src/genkit/_core/_model.py
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
class Document(GenkitModel):
    """Multi-part document that can be embedded, indexed, or retrieved."""

    content: list[Part]
    metadata: dict[str, Any] | None = None

    @field_validator('content', mode='before')
    @classmethod
    def _wrap_parts(cls, v: object) -> object:
        return parts_from_inbound(v)

    def __init__(
        self,
        content: Sequence[Part],
        metadata: dict[str, Any] | None = None,
    ) -> None:
        """Initialize with content parts and optional metadata."""
        if isinstance(content, (Document, DocumentData)) or (
            isinstance(content, BaseModel) and not isinstance(content, Sequence)
        ):
            raise TypeError('Document(other) is gone; pass content= or use as_document')
        payload: dict[str, Any] = {'content': deepcopy(content), 'metadata': deepcopy(metadata)}
        BaseModel.__init__(self, **cast(Any, payload))

    @classmethod
    def from_text(cls, text: str, metadata: dict[str, Any] | None = None) -> Self:
        """Create a document from a text string. ``metadata`` goes on the document."""
        return cls(content=[Part.from_text(text)], metadata=metadata)

    @classmethod
    def from_media(
        cls,
        url: str,
        content_type: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> Self:
        """Create a document from a media URL. ``metadata`` goes on the document."""
        return cls(content=[Part.from_media(url, content_type)], metadata=metadata)

    @cached_property
    def text(self) -> str:
        """Concatenate all text parts."""
        texts = []
        for p in self.content:
            if isinstance(p.text, str):
                texts.append(p.text)
        return ''.join(texts)

    @cached_property
    def media(self) -> list[Media]:
        """All media parts."""
        return [part.media for part in self.content if part.media is not None]

media cached property

All media parts.

text cached property

Concatenate all text parts.

__init__(content, metadata=None)

Initialize with content parts and optional metadata.

Source code in packages/genkit/src/genkit/_core/_model.py
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
def __init__(
    self,
    content: Sequence[Part],
    metadata: dict[str, Any] | None = None,
) -> None:
    """Initialize with content parts and optional metadata."""
    if isinstance(content, (Document, DocumentData)) or (
        isinstance(content, BaseModel) and not isinstance(content, Sequence)
    ):
        raise TypeError('Document(other) is gone; pass content= or use as_document')
    payload: dict[str, Any] = {'content': deepcopy(content), 'metadata': deepcopy(metadata)}
    BaseModel.__init__(self, **cast(Any, payload))

from_media(url, content_type=None, metadata=None) classmethod

Create a document from a media URL. metadata goes on the document.

Source code in packages/genkit/src/genkit/_core/_model.py
1261
1262
1263
1264
1265
1266
1267
1268
1269
@classmethod
def from_media(
    cls,
    url: str,
    content_type: str | None = None,
    metadata: dict[str, Any] | None = None,
) -> Self:
    """Create a document from a media URL. ``metadata`` goes on the document."""
    return cls(content=[Part.from_media(url, content_type)], metadata=metadata)

from_text(text, metadata=None) classmethod

Create a document from a text string. metadata goes on the document.

Source code in packages/genkit/src/genkit/_core/_model.py
1256
1257
1258
1259
@classmethod
def from_text(cls, text: str, metadata: dict[str, Any] | None = None) -> Self:
    """Create a document from a text string. ``metadata`` goes on the document."""
    return cls(content=[Part.from_text(text)], metadata=metadata)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Embedding

Bases: genkit._core._base.GenkitModel

Model for embedding data.

Source code in packages/genkit/src/genkit/_core/_typing.py
325
326
327
328
329
330
331
332
class Embedding(GenkitModel):
    """Model for embedding data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    embedding: list[float] = Field(...)
    metadata: Metadata | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ErrorReason

Bases: genkit._core._compat.StrEnum

Why a failure happened, beyond its status.

Genkit sets a reason when it classifies its own failures, and plugins set one when they classify a provider failure (provider_error(reason=...)), so app code can match on it whichever plugin raised. Read it from GenkitError.reason or Failure.reason. It travels in details['reason']; the other SDKs don't have it.

Source code in packages/genkit/src/genkit/_core/_error.py
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
class ErrorReason(StrEnum):
    """Why a failure happened, beyond its status.

    Genkit sets a reason when it classifies its own failures, and plugins set
    one when they classify a provider failure (``provider_error(reason=...)``),
    so app code can match on it whichever plugin raised. Read it from
    ``GenkitError.reason`` or ``Failure.reason``. It travels in
    ``details['reason']``; the other SDKs don't have it.
    """

    INVALID_SCHEMA = 'INVALID_SCHEMA'
    INVALID_INPUT = 'INVALID_INPUT'
    INVALID_OUTPUT = 'INVALID_OUTPUT'
    ACTION_NOT_FOUND = 'ACTION_NOT_FOUND'
    MODEL_NOT_FOUND = 'MODEL_NOT_FOUND'
    TOOL_NOT_FOUND = 'TOOL_NOT_FOUND'
    MAX_TURNS_EXCEEDED = 'MAX_TURNS_EXCEEDED'
    TOOL_FAILED = 'TOOL_FAILED'
    UNSUPPORTED_BY_MODEL = 'UNSUPPORTED_BY_MODEL'
    INVALID_PART = 'INVALID_PART'
    UNRESOLVED_TOOL_REQUEST = 'UNRESOLVED_TOOL_REQUEST'
    INVALID_RESUME = 'INVALID_RESUME'
    SNAPSHOT_NOT_FOUND = 'SNAPSHOT_NOT_FOUND'
    SNAPSHOT_NOT_RESUMABLE = 'SNAPSHOT_NOT_RESUMABLE'
    SESSION_STORE_NOT_CONFIGURED = 'SESSION_STORE_NOT_CONFIGURED'
    SESSION_ID_REQUIRED = 'SESSION_ID_REQUIRED'
    INVALID_SESSION_ID = 'INVALID_SESSION_ID'
    INVALID_SNAPSHOT_ID = 'INVALID_SNAPSHOT_ID'
    CONNECTION_CLOSED = 'CONNECTION_CLOSED'
    # An on_chunk callback (the caller's or one middleware installed) raised; the model isn't retried.
    STREAM_CALLBACK_FAILED = 'STREAM_CALLBACK_FAILED'
    # The provider rejected the API key or credentials that were sent.
    INVALID_CREDENTIALS = 'INVALID_CREDENTIALS'

Failure

Bases: genkit._core._typing._RuntimeErrorWire

A failure value on response.error, Operation.error, AgentOutput.error, or SessionSnapshot.error.

Not an exception: generate and agents return failures as values. reason is set when the framework classified the failure.

response = await ai.generate(prompt='Refund order A-17.', tools=['refund_order'])
response.error.status   # => 'INTERNAL'
response.error.message  # => 'internal error'
Source code in packages/genkit/src/genkit/_core/_error.py
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
class Failure(_RuntimeErrorWire):
    """A failure value on ``response.error``, ``Operation.error``, ``AgentOutput.error``, or ``SessionSnapshot.error``.

    Not an exception: generate and agents return failures as values. ``reason``
    is set when the framework classified the failure.

        response = await ai.generate(prompt='Refund order A-17.', tools=['refund_order'])
        response.error.status   # => 'INTERNAL'
        response.error.message  # => 'internal error'
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(frozen=True)

    # A failure value isn't a set member or dict key, and dict details
    # can't hash anyway.
    __hash__ = None  # type: ignore[assignment]

    status: StatusName | None = None  # pyright: ignore[reportIncompatibleVariableOverride]  # pyrefly: ignore[bad-override]
    details: dict[str, Any] | None = None  # pyright: ignore[reportIncompatibleVariableOverride]  # pyrefly: ignore[bad-override]
    # Set when the failure came from a PublicError, so a served agent may send
    # its message. Not serialized, like Go's status.Error.Public: a failure
    # read back from a store or another process is redacted on the wire.
    _public: bool = PrivateAttr(default=False)
    # Set when generate already logged the underlying exception, so a prompt
    # agent re-raising response.error does not log it a second time.
    _logged: bool = PrivateAttr(default=False)

    @model_validator(mode='before')
    @classmethod
    def _from_wire(cls, value: object) -> object:
        # A session store built against the generated class still loads.
        if isinstance(value, _RuntimeErrorWire) and not isinstance(value, cls):
            value = value.model_dump(exclude_none=True)
        # A snapshot, operation, or remote agent written by another SDK or a
        # newer version can carry extra keys or a status this one doesn't know.
        # Load it rather than fail the read.
        if isinstance(value, Mapping):
            raw = {k: v for k, v in cast(Mapping[str, object], value).items() if k in _FAILURE_KEYS}
            status = raw.get('status')
            if isinstance(status, str) and status not in _STATUS_NAMES:
                raw['status'] = 'UNKNOWN'
            # JS GenkitError.toJSON writes details of any type. Wrap a
            # non-object value so the read succeeds and nothing is lost.
            details = raw.get('details')
            if details is not None and not isinstance(details, Mapping):
                raw['details'] = {'value': details}
            return raw
        return value

    @property
    def reason(self) -> ErrorReason | None:
        return error_reason(self.details)

    def __eq__(self, other: object) -> bool:
        # Private attrs (_public, _logged) live in __pydantic_private__, not
        # __dict__: res.error == Failure(...) and snapshot round-trip equality
        # compare all declared fields and ignore provenance.
        if not isinstance(other, Failure):
            return NotImplemented
        return self.__dict__ == other.__dict__

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

FinishReason

Bases: genkit._core._compat.StrEnum

FinishReason data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
class FinishReason(StrEnum):
    """FinishReason data type class."""

    STOP = 'stop'
    LENGTH = 'length'
    BLOCKED = 'blocked'
    ABORTED = 'aborted'
    FAILED = 'failed'
    INTERRUPTED = 'interrupted'
    OTHER = 'other'
    UNKNOWN = 'unknown'

    def is_abnormal(self) -> bool:
        """True when generation stopped abnormally (blocked, aborted, failed, interrupted, other)."""
        return self in (
            FinishReason.BLOCKED,
            FinishReason.ABORTED,
            FinishReason.FAILED,
            FinishReason.INTERRUPTED,
            FinishReason.OTHER,
        )

is_abnormal()

True when generation stopped abnormally (blocked, aborted, failed, interrupted, other).

Source code in packages/genkit/src/genkit/_core/_typing.py
100
101
102
103
104
105
106
107
108
def is_abnormal(self) -> bool:
    """True when generation stopped abnormally (blocked, aborted, failed, interrupted, other)."""
    return self in (
        FinishReason.BLOCKED,
        FinishReason.ABORTED,
        FinishReason.FAILED,
        FinishReason.INTERRUPTED,
        FinishReason.OTHER,
    )

Flow

Bases: genkit._core._action.Action[genkit._core._action.InputT, genkit._core._action.OutputT, genkit._core._action.ChunkT, None]

A typed, traced, streamable flow action.

@ai.flow constructs and registers a Flow on the Genkit instance. Constructing Flow(fn) directly builds a standalone (unregistered) flow.

Source code in packages/genkit/src/genkit/_core/_flow.py
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class Flow(Action[InputT, OutputT, ChunkT, None]):
    """A typed, traced, streamable flow action.

    ``@ai.flow`` constructs and registers a ``Flow`` on the ``Genkit`` instance.
    Constructing ``Flow(fn)`` directly builds a standalone (unregistered) flow.
    """

    # `(ctx, x: Any)` would match the (input, ctx) shape with the ctx as the
    # input; catch it first. InputT isn't bound here, so it defaults to Any.
    @overload
    def __init__(
        self,
        func: Callable[[FlowContext[ChunkT], object], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    # The defaulted-input shapes are self-typed to DefaultedFlow, so they
    # apply when define_flow builds one. Flow(fn) itself stays a Flow and
    # skips them. `(x = ..., ctx = None)` also fits (input, ctx); catch it first.
    @overload
    def __init__(
        self: DefaultedFlow[_FlowInputT, _FlowOutputT, _FlowChunkT],
        func: DefaultInputCtxFn[FlowContext[_FlowChunkT], _FlowInputT, _FlowOutputT],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        func: Callable[[InputT, FlowContext[ChunkT]], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: DefaultedFlow[_FlowInputT, _FlowOutputT, _FlowChunkT],
        func: CtxDefaultInputFn[FlowContext[_FlowChunkT], _FlowInputT, _FlowOutputT],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        func: Callable[[FlowContext[ChunkT], InputT], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        func: Callable[[FlowContext[ChunkT]], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: DefaultedFlow[_FlowInputT, _FlowOutputT, Any],
        func: DefaultInputFn[_FlowInputT, _FlowOutputT],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        func: Callable[[InputT], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        func: Callable[[], Awaitable[OutputT]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None: ...

    def __init__(
        self,
        func: Callable[..., Awaitable[Any]],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> None:
        """Initialize a ``Flow`` from ``func``.

        Args:
            func: Async flow handler taking at most one input and an optional
                ``FlowContext[ChunkT]`` parameter.
            name: Optional flow name. Defaults to ``func.__name__``.
            description: Optional description. Defaults to ``func.__doc__``.
        """
        if not inspect.iscoroutinefunction(func):
            raise TypeError(f'Flow must be async: {getattr(func, "__name__", repr(func))}')

        flow_name = name or getattr(func, '__name__', None) or 'unnamed_flow'
        super().__init__(
            kind=ActionKind.FLOW,
            name=flow_name,
            fn=func,
            description=get_func_description(func, description),
            span_metadata={'flow:name': flow_name},
            _strict_io=True,
        )

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

__init__(func, *, name=None, description=None)

__init__(
    func: Callable[
        [FlowContext[ChunkT], object], Awaitable[OutputT]
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: DefaultInputCtxFn[
        FlowContext[_FlowChunkT], _FlowInputT, _FlowOutputT
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: Callable[
        [InputT, FlowContext[ChunkT]], Awaitable[OutputT]
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: CtxDefaultInputFn[
        FlowContext[_FlowChunkT], _FlowInputT, _FlowOutputT
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: Callable[
        [FlowContext[ChunkT], InputT], Awaitable[OutputT]
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: Callable[
        [FlowContext[ChunkT]], Awaitable[OutputT]
    ],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: DefaultInputFn[_FlowInputT, _FlowOutputT],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: Callable[[InputT], Awaitable[OutputT]],
    *,
    name: str | None = None,
    description: str | None = None
) -> None
__init__(
    func: Callable[[], Awaitable[OutputT]],
    *,
    name: str | None = None,
    description: str | None = None
) -> None

Initialize a Flow from func.

Parameters:

Name Type Description Default
func collections.abc.Callable[..., collections.abc.Awaitable[typing.Any]]

Async flow handler taking at most one input and an optional FlowContext[ChunkT] parameter.

required
name str | None

Optional flow name. Defaults to func.__name__.

None
description str | None

Optional description. Defaults to func.__doc__.

None
Source code in packages/genkit/src/genkit/_core/_flow.py
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def __init__(
    self,
    func: Callable[..., Awaitable[Any]],
    *,
    name: str | None = None,
    description: str | None = None,
) -> None:
    """Initialize a ``Flow`` from ``func``.

    Args:
        func: Async flow handler taking at most one input and an optional
            ``FlowContext[ChunkT]`` parameter.
        name: Optional flow name. Defaults to ``func.__name__``.
        description: Optional description. Defaults to ``func.__doc__``.
    """
    if not inspect.iscoroutinefunction(func):
        raise TypeError(f'Flow must be async: {getattr(func, "__name__", repr(func))}')

    flow_name = name or getattr(func, '__name__', None) or 'unnamed_flow'
    super().__init__(
        kind=ActionKind.FLOW,
        name=flow_name,
        fn=func,
        description=get_func_description(func, description),
        span_metadata={'flow:name': flow_name},
        _strict_io=True,
    )

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

FlowContext

Bases: genkit._core._action.ActionContext[genkit._core._action.ChunkT]

Execution context passed to flow functions.

Provides ctx.send_chunk(chunk) for streaming ChunkT chunks and ctx.context for caller context data.

FlowContext and ToolContext are siblings, so neither annotation accepts the other. A helper shared by a flow and a tool takes the union:

# 1. Read the caller's uid from either context
def user_id(ctx: FlowContext | ToolContext) -> str:
    return ctx.context['auth']['uid']

# 2. Call it from a flow and from a tool
@ai.flow
async def reorder_last(dish: str, ctx: FlowContext) -> str:
    return f'{dish} for {user_id(ctx)}'

@ai.tool
async def check_allergies(dish: str, ctx: ToolContext) -> str:
    return f'{dish}: nut-free for {user_id(ctx)}'

# 3. Both see the same request context
await reorder_last('tartine', context={'auth': {'uid': 'diner-42'}})
# => 'tartine for diner-42'
await check_allergies('tartine', context={'auth': {'uid': 'diner-42'}})
# => 'tartine: nut-free for diner-42'
Source code in packages/genkit/src/genkit/_core/_action.py
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
class FlowContext(ActionContext[ChunkT]):
    """Execution context passed to flow functions.

    Provides ``ctx.send_chunk(chunk)`` for streaming ``ChunkT`` chunks and
    ``ctx.context`` for caller context data.

    ``FlowContext`` and ``ToolContext`` are siblings, so neither annotation
    accepts the other. A helper shared by a flow and a tool takes the union:

        # 1. Read the caller's uid from either context
        def user_id(ctx: FlowContext | ToolContext) -> str:
            return ctx.context['auth']['uid']

        # 2. Call it from a flow and from a tool
        @ai.flow
        async def reorder_last(dish: str, ctx: FlowContext) -> str:
            return f'{dish} for {user_id(ctx)}'

        @ai.tool
        async def check_allergies(dish: str, ctx: ToolContext) -> str:
            return f'{dish}: nut-free for {user_id(ctx)}'

        # 3. Both see the same request context
        await reorder_last('tartine', context={'auth': {'uid': 'diner-42'}})
        # => 'tartine for diner-42'
        await check_allergies('tartine', context={'auth': {'uid': 'diner-42'}})
        # => 'tartine: nut-free for diner-42'
    """

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

Genkit

The main entry point for building AI-powered applications.

Registers plugins, defines flows and tools, and runs generation. Both Genkit(model=...) and ai.generate(model=...) accept a typed ModelRef from a plugin constructor (recommended, e.g. GoogleAI.gemini('gemini-flash-latest')) or a plugin-prefixed string ('googleai/gemini-flash-latest'). Plugins resolve models lazily on demand when ai.generate() is called, without needing pre-registration or SDK updates.

Example

from genkit import Genkit from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

@ai.tool async def current_weather(city: str) -> str: return f'Sunny in {city}'

@ai.flow async def weather_report(prompt: str) -> str: res = await ai.generate(prompt=prompt, tools=[current_weather]) return res.text

async def main() -> None: print(await weather_report('Weather in Paris?')) # => It's sunny in Paris.

if name == 'main': ai.run_main(main())

Source code in packages/genkit/src/genkit/_ai/_aio.py
 205
 206
 207
 208
 209
 210
 211
 212
 213
 214
 215
 216
 217
 218
 219
 220
 221
 222
 223
 224
 225
 226
 227
 228
 229
 230
 231
 232
 233
 234
 235
 236
 237
 238
 239
 240
 241
 242
 243
 244
 245
 246
 247
 248
 249
 250
 251
 252
 253
 254
 255
 256
 257
 258
 259
 260
 261
 262
 263
 264
 265
 266
 267
 268
 269
 270
 271
 272
 273
 274
 275
 276
 277
 278
 279
 280
 281
 282
 283
 284
 285
 286
 287
 288
 289
 290
 291
 292
 293
 294
 295
 296
 297
 298
 299
 300
 301
 302
 303
 304
 305
 306
 307
 308
 309
 310
 311
 312
 313
 314
 315
 316
 317
 318
 319
 320
 321
 322
 323
 324
 325
 326
 327
 328
 329
 330
 331
 332
 333
 334
 335
 336
 337
 338
 339
 340
 341
 342
 343
 344
 345
 346
 347
 348
 349
 350
 351
 352
 353
 354
 355
 356
 357
 358
 359
 360
 361
 362
 363
 364
 365
 366
 367
 368
 369
 370
 371
 372
 373
 374
 375
 376
 377
 378
 379
 380
 381
 382
 383
 384
 385
 386
 387
 388
 389
 390
 391
 392
 393
 394
 395
 396
 397
 398
 399
 400
 401
 402
 403
 404
 405
 406
 407
 408
 409
 410
 411
 412
 413
 414
 415
 416
 417
 418
 419
 420
 421
 422
 423
 424
 425
 426
 427
 428
 429
 430
 431
 432
 433
 434
 435
 436
 437
 438
 439
 440
 441
 442
 443
 444
 445
 446
 447
 448
 449
 450
 451
 452
 453
 454
 455
 456
 457
 458
 459
 460
 461
 462
 463
 464
 465
 466
 467
 468
 469
 470
 471
 472
 473
 474
 475
 476
 477
 478
 479
 480
 481
 482
 483
 484
 485
 486
 487
 488
 489
 490
 491
 492
 493
 494
 495
 496
 497
 498
 499
 500
 501
 502
 503
 504
 505
 506
 507
 508
 509
 510
 511
 512
 513
 514
 515
 516
 517
 518
 519
 520
 521
 522
 523
 524
 525
 526
 527
 528
 529
 530
 531
 532
 533
 534
 535
 536
 537
 538
 539
 540
 541
 542
 543
 544
 545
 546
 547
 548
 549
 550
 551
 552
 553
 554
 555
 556
 557
 558
 559
 560
 561
 562
 563
 564
 565
 566
 567
 568
 569
 570
 571
 572
 573
 574
 575
 576
 577
 578
 579
 580
 581
 582
 583
 584
 585
 586
 587
 588
 589
 590
 591
 592
 593
 594
 595
 596
 597
 598
 599
 600
 601
 602
 603
 604
 605
 606
 607
 608
 609
 610
 611
 612
 613
 614
 615
 616
 617
 618
 619
 620
 621
 622
 623
 624
 625
 626
 627
 628
 629
 630
 631
 632
 633
 634
 635
 636
 637
 638
 639
 640
 641
 642
 643
 644
 645
 646
 647
 648
 649
 650
 651
 652
 653
 654
 655
 656
 657
 658
 659
 660
 661
 662
 663
 664
 665
 666
 667
 668
 669
 670
 671
 672
 673
 674
 675
 676
 677
 678
 679
 680
 681
 682
 683
 684
 685
 686
 687
 688
 689
 690
 691
 692
 693
 694
 695
 696
 697
 698
 699
 700
 701
 702
 703
 704
 705
 706
 707
 708
 709
 710
 711
 712
 713
 714
 715
 716
 717
 718
 719
 720
 721
 722
 723
 724
 725
 726
 727
 728
 729
 730
 731
 732
 733
 734
 735
 736
 737
 738
 739
 740
 741
 742
 743
 744
 745
 746
 747
 748
 749
 750
 751
 752
 753
 754
 755
 756
 757
 758
 759
 760
 761
 762
 763
 764
 765
 766
 767
 768
 769
 770
 771
 772
 773
 774
 775
 776
 777
 778
 779
 780
 781
 782
 783
 784
 785
 786
 787
 788
 789
 790
 791
 792
 793
 794
 795
 796
 797
 798
 799
 800
 801
 802
 803
 804
 805
 806
 807
 808
 809
 810
 811
 812
 813
 814
 815
 816
 817
 818
 819
 820
 821
 822
 823
 824
 825
 826
 827
 828
 829
 830
 831
 832
 833
 834
 835
 836
 837
 838
 839
 840
 841
 842
 843
 844
 845
 846
 847
 848
 849
 850
 851
 852
 853
 854
 855
 856
 857
 858
 859
 860
 861
 862
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875
 876
 877
 878
 879
 880
 881
 882
 883
 884
 885
 886
 887
 888
 889
 890
 891
 892
 893
 894
 895
 896
 897
 898
 899
 900
 901
 902
 903
 904
 905
 906
 907
 908
 909
 910
 911
 912
 913
 914
 915
 916
 917
 918
 919
 920
 921
 922
 923
 924
 925
 926
 927
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937
 938
 939
 940
 941
 942
 943
 944
 945
 946
 947
 948
 949
 950
 951
 952
 953
 954
 955
 956
 957
 958
 959
 960
 961
 962
 963
 964
 965
 966
 967
 968
 969
 970
 971
 972
 973
 974
 975
 976
 977
 978
 979
 980
 981
 982
 983
 984
 985
 986
 987
 988
 989
 990
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
2164
2165
2166
2167
2168
2169
2170
2171
2172
2173
2174
2175
2176
2177
2178
2179
2180
2181
2182
2183
2184
2185
2186
2187
2188
2189
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
2303
2304
2305
2306
2307
2308
2309
2310
2311
2312
2313
2314
2315
2316
2317
2318
2319
2320
2321
2322
2323
2324
2325
2326
2327
2328
2329
2330
2331
2332
2333
2334
2335
2336
2337
2338
2339
2340
2341
2342
2343
2344
2345
2346
2347
2348
2349
2350
2351
2352
2353
2354
2355
2356
2357
2358
2359
2360
2361
2362
2363
2364
2365
2366
2367
2368
2369
2370
2371
2372
2373
2374
2375
2376
2377
2378
2379
2380
2381
2382
2383
2384
2385
2386
2387
2388
2389
2390
2391
2392
2393
2394
2395
2396
2397
2398
2399
2400
2401
2402
2403
2404
2405
2406
2407
2408
2409
2410
2411
2412
2413
2414
2415
2416
2417
2418
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
2472
2473
2474
2475
2476
2477
2478
2479
2480
2481
2482
2483
2484
2485
2486
2487
2488
2489
2490
2491
2492
2493
2494
2495
2496
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
2529
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
2595
2596
2597
2598
2599
2600
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
2640
2641
2642
2643
2644
2645
2646
2647
2648
2649
2650
2651
2652
2653
2654
2655
2656
2657
2658
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
2702
2703
2704
2705
2706
2707
2708
2709
2710
2711
2712
2713
2714
2715
2716
2717
2718
2719
2720
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
2745
2746
2747
2748
2749
2750
2751
2752
2753
2754
2755
2756
2757
2758
2759
2760
2761
2762
2763
2764
2765
2766
2767
2768
2769
2770
2771
2772
2773
2774
2775
2776
2777
2778
2779
2780
2781
2782
2783
2784
2785
2786
2787
2788
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
class Genkit:
    """The main entry point for building AI-powered applications.

    Registers plugins, defines flows and tools, and runs generation. Both
    ``Genkit(model=...)`` and ``ai.generate(model=...)`` accept a typed
    ``ModelRef`` from a plugin constructor (recommended, e.g.
    ``GoogleAI.gemini('gemini-flash-latest')``) or a plugin-prefixed
    string (``'googleai/gemini-flash-latest'``). Plugins resolve models lazily
    on demand when ``ai.generate()`` is called, without needing pre-registration
    or SDK updates.

    Example:
        from genkit import Genkit
        from genkit_google_genai import GoogleAI

        ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

        @ai.tool
        async def current_weather(city: str) -> str:
            return f'Sunny in {city}'

        @ai.flow
        async def weather_report(prompt: str) -> str:
            res = await ai.generate(prompt=prompt, tools=[current_weather])
            return res.text

        async def main() -> None:
            print(await weather_report('Weather in Paris?'))
            # => It's sunny in Paris.

        if __name__ == '__main__':
            ai.run_main(main())
    """

    _registry: Registry
    _reflection_server_spec: ServerSpec | None
    _reflection_config: ReflectionConfig
    _reflection_ready: threading.Event
    _reflection_stopped: threading.Event
    _reflection_bound_addr: str | None

    if TYPE_CHECKING:

        def __init__(
            self,
            *,
            plugins: list[Plugin] | None = None,
            model: ModelArg | None = None,
            prompt_dir: str | Path | None = None,
        ) -> None: ...

    else:
        # Type checkers see the keyword-only signature above. Runtime still
        # accepts *args so we can raise a TypeError that names the keyword they
        # probably meant, instead of silently binding a model id as plugins.
        def __init__(  # noqa: D417
            self,
            *args: object,
            plugins: list[Plugin] | None = None,
            model: ModelArg | None = None,
            prompt_dir: str | Path | None = None,
        ) -> None:
            """Initialize a Genkit instance.

            Args:
                plugins: Plugins to register (e.g. ``[GoogleAI()]``). Plugins resolve
                    models lazily on demand when ``ai.generate()`` is called.
                model: Default model for ``ai.generate()``. Accepts a typed ``ModelRef``
                    (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``) or
                    a plugin-prefixed string (``'googleai/gemini-flash-latest'``).
                prompt_dir: Optional directory for loading ``.prompt`` files.
            """
            if args:
                raise TypeError(
                    f'Genkit() takes no positional arguments, got {len(args)}. '
                    f'Pass keyword arguments instead, e.g. {init_keyword_example(args[0])}.'
                )
            # Before anything that logs, so plugin initialization is covered too.
            configure_logging()
            self._registry = Registry()
            self._reflection_server_spec = None
            # The reflection API runs under GENKIT_ENV=dev, or in any environment
            # with GENKIT_REFLECTION_ENABLED=true. Resolving here keeps an invalid
            # setting a constructor-time error.
            self._reflection_config = resolve_reflection_config()
            self._reflection_ready = threading.Event()
            # Set when the reflection thread exits for any reason (v2 auth
            # rejection, server crash), so run_main stops waiting on nothing.
            self._reflection_stopped = threading.Event()
            # host:port the v1 socket is bound to, set in the constructor so
            # run_main can log it without waiting on the server thread.
            self._reflection_bound_addr = None
            self._initialize_registry(model, plugins)
            # Ensure the default generate action is registered for async usage.
            define_generate_action(self)
            self._register_plugin_middleware(plugins)
            maybe_inject_dev_instrumentation()
            # When reflection is on, start the server immediately in a background
            # daemon thread so it's available regardless of which web framework (or
            # none) the user chooses.
            if self._reflection_config.enabled:
                # SIGINT (Ctrl+C) always hits handle_signal. SIGTERM inside the
                # run_main wait loop is stolen by anyio (clean exit → atexit);
                # elsewhere SIGTERM also goes through handle_signal. Both paths
                # remove the runtime discovery files.
                setup_signal_handlers()
                self._start_reflection_background()

            # Load prompts
            load_path = prompt_dir
            if load_path is None:
                default_prompts_path = Path('./prompts')
                if default_prompts_path.is_dir():
                    load_path = default_prompts_path

            if load_path:
                load_prompt_folder(self, dir_path=load_path)

        # help(Genkit) should show the keyword-only constructor, not a phantom *args.
        __init__.__signature__ = inspect.signature(__init__).replace(
            parameters=[
                parameter
                for parameter in inspect.signature(__init__).parameters.values()
                if parameter.kind != inspect.Parameter.VAR_POSITIONAL
            ]
        )

    # -------------------------------------------------------------------------
    # Registry methods
    # -------------------------------------------------------------------------

    @overload
    def flow(
        self,
        name: str | None = None,
        *,
        description: str | None = None,
    ) -> _FlowDecorator: ...

    # Overload order matters; see _FlowDecorator.__call__ for why the
    # `object` shapes come before the context shapes.
    @overload
    def flow(
        self,
        func: Callable[[FlowContext[ChunkT], object], Awaitable[OutputT]],
        /,
    ) -> Flow[Any, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: DefaultInputCtxFn[FlowContext[ChunkT], InputT, OutputT],
        /,
    ) -> DefaultedFlow[InputT, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: Callable[[InputT, FlowContext[ChunkT]], Awaitable[OutputT]],
        /,
    ) -> Flow[InputT, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: CtxDefaultInputFn[FlowContext[ChunkT], InputT, OutputT],
        /,
    ) -> DefaultedFlow[InputT, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: Callable[[FlowContext[ChunkT], InputT], Awaitable[OutputT]],
        /,
    ) -> Flow[InputT, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: Callable[[object], Awaitable[OutputT]],
        /,
    ) -> Flow[Any, OutputT]: ...

    @overload
    def flow(
        self,
        func: Callable[[FlowContext[ChunkT]], Awaitable[OutputT]],
        /,
    ) -> Flow[None, OutputT, ChunkT]: ...

    @overload
    def flow(
        self,
        func: DefaultInputFn[InputT, OutputT],
        /,
    ) -> DefaultedFlow[InputT, OutputT]: ...

    @overload
    def flow(
        self,
        func: Callable[[InputT], Awaitable[OutputT]],
        /,
    ) -> Flow[InputT, OutputT]: ...

    @overload
    def flow(
        self,
        func: Callable[[], Awaitable[OutputT]],
        /,
    ) -> Flow[None, OutputT]: ...

    def flow(
        self,
        name: str | Callable[..., Awaitable[Any]] | None = None,
        *,
        description: str | None = None,
    ) -> _FlowDecorator | Flow[Any, Any, Any]:
        """Decorator to register an async function as a flow.

        Can be used bare (``@ai.flow``) or with arguments (``@ai.flow()``,
        ``@ai.flow('custom_name', description='...')``).

        A flow takes at most one input. To read the request context or stream
        chunks, add a parameter annotated ``FlowContext``, in any position.
        Any other second parameter raises ``TypeError`` when the flow is defined.

        Args:
            name: Optional name for the flow (or the function itself when used
                as ``@ai.flow``). Defaults to the function name.
            description: Optional description for the flow.

        Example:
            from genkit import FlowContext, Genkit
            from genkit_google_genai import GoogleAI

            ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

            @ai.flow
            async def my_flow(prompt: str) -> str:
                res = await ai.generate(prompt=prompt)
                return res.text

            @ai.flow
            async def streaming_flow(x: int, ctx: FlowContext[str]) -> str:
                ctx.send_chunk('progress')
                return 'done'
        """
        if not isinstance(name, str) and name is not None:
            return _FlowDecorator(self._registry, None, description)(name)
        return _FlowDecorator(self._registry, name, description)

    def define_helper(self, name: str, fn: Callable[..., Any]) -> None:
        """Register a Handlebars helper for prompt templates.

        Dotprompt calls the helper as ``fn(params, options)``: ``params`` is a
        list of the positional arguments from the template, and ``options``
        carries the named arguments in ``options.hash``. A one-argument
        function such as ``lambda s: s.upper()`` raises ``TypeError`` at
        render time. Return a ``str``.

        Example:
            ```python
            # 1. Register a helper that takes one positional and one named argument
            def menu_item(params: list[Any], options: Any) -> str:
                dish = str(params[0])
                return dish.upper() if options.hash.get('loud') else dish


            ai.define_helper('menu_item', menu_item)

            # 2. Use it in a prompt template
            special = ai.define_prompt(
                name='special',
                model='googleai/gemini-flash-latest',
                prompt="Describe today's special, {{menu_item dish loud=true}}, in one line.",
            )

            # 3. Render to check the expanded text
            request = await special.render(input={'dish': 'smoked salmon tartine'})
            print(request.messages[0].content[0].text)
            # => Describe today's special, SMOKED SALMON TARTINE, in one line.
            ```
        """
        define_helper(self._registry, name, fn)

    def define_partial(self, name: str, source: str) -> None:
        """Register a Handlebars partial template."""
        define_partial(self._registry, name, source)

    def define_schema(self, name: str, schema: type[BaseModel]) -> type[BaseModel]:
        """Register a Pydantic schema for use in prompts."""
        define_schema(self._registry, name, schema)
        return schema

    def define_json_schema(self, name: str, json_schema: dict[str, object]) -> dict[str, object]:
        """Register a JSON schema for use in prompts."""
        self._registry.register_schema(name, json_schema)
        return json_schema

    def define_dynamic_action_provider(
        self,
        name: str,
        fn: DapFn,
        *,
        description: str | None = None,
        cache_ttl_millis: int | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> DynamicActionProvider:
        """Register a Dynamic Action Provider (DAP)."""
        return define_dap_block(
            self._registry,
            name,
            fn,
            description=description,
            cache_ttl_millis=cache_ttl_millis,
            metadata=metadata,
        )

    @overload
    def tool(
        self,
        name: str | None = None,
        *,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> _ToolDecorator: ...

    # Same order as Genkit.flow: the `object` shapes catch `(ctx, x: Any)` and
    # `(x: Any)` / `(x: object)` before a ctx shape can claim them.
    @overload
    def tool(
        self,
        func: Callable[[ToolContext[ChunkT], object], Awaitable[OutputT]],
        /,
    ) -> Tool[Any, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: DefaultInputCtxFn[ToolContext[ChunkT], InputT, OutputT],
        /,
    ) -> DefaultedTool[InputT, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: Callable[[InputT, ToolContext[ChunkT]], Awaitable[OutputT]],
        /,
    ) -> Tool[InputT, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: CtxDefaultInputFn[ToolContext[ChunkT], InputT, OutputT],
        /,
    ) -> DefaultedTool[InputT, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: Callable[[ToolContext[ChunkT], InputT], Awaitable[OutputT]],
        /,
    ) -> Tool[InputT, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: Callable[[object], Awaitable[OutputT]],
        /,
    ) -> Tool[Any, OutputT]: ...

    @overload
    def tool(
        self,
        func: Callable[[ToolContext[ChunkT]], Awaitable[OutputT]],
        /,
    ) -> Tool[None, OutputT, ChunkT]: ...

    @overload
    def tool(
        self,
        func: DefaultInputFn[InputT, OutputT],
        /,
    ) -> DefaultedTool[InputT, OutputT]: ...

    @overload
    def tool(
        self,
        func: Callable[[InputT], Awaitable[OutputT]],
        /,
    ) -> Tool[InputT, OutputT]: ...

    @overload
    def tool(
        self,
        func: Callable[[], Awaitable[OutputT]],
        /,
    ) -> Tool[None, OutputT]: ...

    def tool(
        self,
        name: str | Callable[..., Awaitable[Any]] | None = None,
        *,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> _ToolDecorator | Tool[Any, Any, Any]:
        """Decorator to register a function as a tool.

        Can be used bare (``@ai.tool``) or with arguments (``@ai.tool()``,
        ``@ai.tool('custom_name', description='...')``).

        The return annotation is what the model binds as ``outputSchema``.
        Awaiting the tool directly returns what the function returned.

        A tool takes at most one input, and that input's type is the schema the
        model fills in. For several fields, use one Pydantic model. To read the
        request context or interrupt, add a parameter annotated
        ``ToolContext``, in any position. Any other second parameter raises
        ``TypeError`` when the tool is defined.

        Example:
            @ai.tool
            async def current_weather(city: str) -> str:
                return f'Sunny in {city}'

            class Forecast(BaseModel):
                city: str
                days: int = 3

            @ai.tool
            async def forecast(input: Forecast, ctx: ToolContext) -> str:
                user = ctx.context.get('user_id')
                return f'{input.days}-day forecast for {input.city} ({user})'

            res = await ai.generate(prompt='Weather in Paris?', tools=['current_weather', 'forecast'])
        """
        if not isinstance(name, str) and name is not None:
            return _ToolDecorator(self._registry, None, description, input_schema)(name)
        return _ToolDecorator(self._registry, name, description, input_schema)

    def define_middleware(
        self,
        cls: type[MiddlewareT],
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> type[MiddlewareT]:
        """Register a middleware class on this app's registry."""
        desc = cls._middleware_metadata(name, description=description)
        self._registry.register_value('middleware', desc.name, desc)
        return cls

    @overload
    def middleware(
        self,
        cls: type[MiddlewareT],
    ) -> type[MiddlewareT]: ...

    @overload
    def middleware(
        self,
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> Callable[[type[MiddlewareT]], type[MiddlewareT]]: ...

    def middleware(
        self,
        cls: type[MiddlewareT] | None = None,
        *,
        name: str | None = None,
        description: str | None = None,
    ) -> type[MiddlewareT] | Callable[[type[MiddlewareT]], type[MiddlewareT]]:
        """Decorator that registers a custom middleware on this app's registry."""

        def decorator(target: type[MiddlewareT]) -> type[MiddlewareT]:
            return self.define_middleware(target, name=name, description=description)

        if cls is not None:
            return decorator(cls)
        return decorator

    def define_interrupt(
        self,
        name: str,
        *,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
        description: str | None = None,
    ) -> Tool[Any, NoReturn]:
        """Register an interrupt tool that always pauses for user input.

        Args:
            name: Tool name
            input_schema: Optional input schema (Pydantic model or JSON schema dict)
            description: Tool description

        Returns:
            The registered interrupt tool. Awaiting it directly raises ``Interrupt``.

        Example:
            ask_user = ai.define_interrupt(
                name='ask_user',
                input_schema=Question,
                description='Ask the user a question',
            )
        """
        return define_interrupt(
            self._registry,
            name,
            description=description,
            input_schema=input_schema,
        )

    def define_evaluator(
        self,
        name: str,
        fn: EvaluatorFn[Any],
        *,
        display_name: str,
        definition: str,
        is_billed: bool = False,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
    ) -> Evaluator:
        """Register an evaluator that scores one dataset row at a time.

        Example:
            ```python
            # 1. Score whether the answer mentions the expected dish
            async def mentions_dish(row: BaseDataPoint, options: object | None) -> EvaluatorResponse:
                hit = row.reference.lower() in str(row.output).lower()
                return EvaluatorResponse(test_case_id=row.test_case_id or '', evaluation=[Score(score=hit)])


            # 2. Register it under a name
            ai.define_evaluator(
                'mentions_dish',
                mentions_dish,
                display_name='Mentions dish',
                definition='Whether the answer names the expected dish.',
            )

            # 3. Run it over a dataset
            rows = await ai.evaluate(evaluator='mentions_dish', dataset=dataset)
            # => [EvaluatorResponse(test_case_id='...', evaluation=[Score(score=True)]), ...]
            ```
        """
        return define_evaluator(
            self._registry,
            name=name,
            display_name=display_name,
            definition=definition,
            fn=fn,
            is_billed=is_billed,
            config_schema=config_schema,
            metadata=metadata,
            description=description,
        )

    def define_batch_evaluator(
        self,
        name: str,
        fn: BatchEvaluatorFn,
        *,
        display_name: str,
        definition: str,
        is_billed: bool = False,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
    ) -> BatchEvaluator:
        """Register a batch evaluator.

        The function takes one ``EvaluatorRequest`` and returns ``list[EvaluatorResponse]``.
        Read options from ``req.options``. A second parameter raises ``TypeError`` when defined.
        """
        return define_batch_evaluator(
            self._registry,
            name=name,
            display_name=display_name,
            definition=definition,
            fn=fn,
            is_billed=is_billed,
            config_schema=config_schema,
            metadata=metadata,
            description=description,
        )

    # define_model and define_embedder: the first overload takes the request
    # and an optional context after it, so `lambda req: ...` infers req as the
    # request. The second takes the context first. See CtxFirstModelFn.
    @overload
    def define_model(
        self,
        name: str,
        fn: ModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> Model: ...

    @overload
    def define_model(
        self,
        name: str,
        fn: CtxFirstModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> Model: ...

    def define_model(
        self,
        name: str,
        fn: ModelFn | CtxFirstModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> Model:
        """Register a custom model action."""
        return define_model(self._registry, name, fn, config_schema, metadata, info, description)

    def define_background_model(
        self,
        name: str,
        *,
        start: StartModelOpFn,
        check: CheckModelOpFn,
        cancel: CancelModelOpFn | None = None,
        info: ModelInfo | None = None,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
    ) -> BackgroundModel:
        """Register a background model for long-running AI operations."""
        return define_background_model(
            registry=self._registry,
            name=name,
            start=start,
            check=check,
            cancel=cancel,
            info=info,
            config_schema=config_schema,
            metadata=metadata,
            description=description,
        )

    @overload
    def define_embedder(
        self,
        name: str,
        fn: EmbedderFn,
        *,
        info: EmbedderInfo | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> Embedder: ...

    @overload
    def define_embedder(
        self,
        name: str,
        fn: CtxFirstEmbedderFn,
        *,
        info: EmbedderInfo | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> Embedder: ...

    def define_embedder(
        self,
        name: str,
        fn: EmbedderFn | CtxFirstEmbedderFn,
        *,
        info: EmbedderInfo | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> Embedder:
        """Register a custom embedder action.

        The options class comes from ``config_schema`` or the fn's
        ``EmbedRequest[Cfg]`` annotation; given both, they must be the same class.
        """
        return define_embedder(self._registry, name, fn, info, metadata, description, config_schema=config_schema)

    def define_format(self, formatter: Formatter) -> None:
        """Register a custom output format. See `genkit.formats.Formatter`."""
        self._registry.register_value('format', formatter.name, formatter)

    async def lookup_model(self, name: str) -> Action[ModelRequest, ModelResponse, ModelResponseChunk] | None:
        """Return the model action registered under ``name``, or None.

        Plugin models that haven't been used yet are resolved through the
        plugin, so ``'googleai/gemini-flash-latest'`` works before any
        generate call. Background models aren't included; they run through
        ``generate_operation``.
        """
        action = await self._registry.resolve_action(ActionKind.MODEL, name)
        return cast(Action[ModelRequest, ModelResponse, ModelResponseChunk], action) if action is not None else None

    async def lookup_tool(self, name: str) -> Tool | None:
        """Return the tool registered under ``name``, or None.

        The same handle ``@ai.tool`` returns, so a tool defined in one module
        can be called or passed in ``tools=[...]`` from another without
        importing it.

        Example:
            ```python
            # 1. Define a tool in one module
            @ai.tool
            async def menu_price(dish: str) -> float:
                return 14.5


            # 2. Find it by name somewhere else
            price_tool = await ai.lookup_tool('menu_price')
            response = await ai.generate(prompt='How much is the ramen?', tools=[price_tool])
            print(response.text)
            # => The ramen is $14.50.
            ```
        """
        action = await self._registry.resolve_action(ActionKind.TOOL, name)
        if action is None:
            return None
        return Tool.from_action(action)

    def lookup_value(self, *, kind: str, name: str) -> object | None:
        """Return the value defined under ``kind`` and ``name``, or None."""
        return self._registry.lookup_value(kind, name)

    def define_value(self, *, kind: str, name: str, value: object) -> None:
        """Store ``value`` under ``kind`` and ``name`` for later ``lookup_value``.

        Defining the same kind and name again replaces the value, so a
        re-run notebook cell does not fail.

        Raises:
            ValueError: ``kind`` is one Genkit owns (use ``define_middleware``,
                ``define_format``, or ``Genkit(model=...)``), or ``value`` is None.
        """
        if kind in _CORE_VALUE_KINDS:
            raise ValueError(f'define_value kind {kind!r} is reserved; use {_CORE_VALUE_KINDS[kind]} instead.')
        if value is None:
            raise ValueError('define_value value must not be None; lookup_value returns None for "not defined".')
        self._registry.register_value(kind, name, value, allow_overwrite=True)

    # Overload 1: Both input_schema and output_schema typed -> Prompt[InputT, OutputT]
    # No config: any ref, including one picked between providers.
    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[Any] | Action | str | None = None,
        config: None = None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: type[OutputT],
    ) -> Prompt[InputT, OutputT]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelConfigDict,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: type[OutputT],
    ) -> Prompt[InputT, OutputT]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: type[OutputT],
    ) -> Prompt[InputT, OutputT]: ...

    # Overload 2: Only input_schema typed -> Prompt[InputT, Any]
    # No config: any ref, including one picked between providers.
    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[Any] | Action | str | None = None,
        config: None = None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: dict[str, object] | str | None = None,
    ) -> Prompt[InputT, Any]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelConfigDict,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: dict[str, object] | str | None = None,
    ) -> Prompt[InputT, Any]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type[InputT],
        output_schema: dict[str, object] | str | None = None,
    ) -> Prompt[InputT, Any]: ...

    # Overload 3: Only output_schema typed -> Prompt[Any, OutputT]
    # No config: any ref, including one picked between providers.
    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[Any] | Action | str | None = None,
        config: None = None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: dict[str, object] | str | None = None,
        output_schema: type[OutputT],
    ) -> Prompt[Any, OutputT]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelConfigDict,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: dict[str, object] | str | None = None,
        output_schema: type[OutputT],
    ) -> Prompt[Any, OutputT]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: dict[str, object] | str | None = None,
        output_schema: type[OutputT],
    ) -> Prompt[Any, OutputT]: ...

    # Overload 4: Neither typed -> Prompt[Any, Any]
    # No config: any ref, including one picked between providers.
    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[Any] | Action | str | None = None,
        config: None = None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type | dict[str, object] | str | None = None,
        output_schema: type | dict[str, object] | str | None = None,
    ) -> Prompt[Any, Any]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelConfigDict,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type | dict[str, object] | str | None = None,
        output_schema: type | dict[str, object] | str | None = None,
    ) -> Prompt[Any, Any]: ...

    @overload
    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type | dict[str, object] | str | None = None,
        output_schema: type | dict[str, object] | str | None = None,
    ) -> Prompt[Any, Any]: ...

    def define_prompt(
        self,
        name: str | None = None,
        *,
        variant: str | None = None,
        model: str | ModelRef[Any] | Action | None = None,
        config: Mapping[str, Any] | BaseModel | ModelConfigDict | None = None,
        description: str | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, object] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        input_schema: type | dict[str, object] | str | None = None,
        output_schema: type | dict[str, object] | str | None = None,
    ) -> Prompt[Any, Any]:
        """Register a prompt template.

        Example:
            joke = ai.define_prompt(name='joke', prompt='Tell a joke about {{topic}}.')
            res = await joke(input={'topic': 'cats'})
            print(res.text)
            # => Why did the cat sit on the keyboard? To keep an eye on the mouse.
        """
        executable_prompt = Prompt(
            self,
            variant=variant,
            model=model,
            config=config,
            description=description,
            input_schema=input_schema,
            system=system,
            prompt=prompt,
            messages=messages,
            output_format=output_format,
            output_content_type=output_content_type,
            output_instructions=output_instructions,
            output_schema=output_schema,
            output_constrained=output_constrained,
            max_turns=max_turns,
            return_tool_requests=return_tool_requests,
            metadata=metadata,
            tools=tools,
            tool_choice=tool_choice,
            use=use,
            docs=docs,
            name=name,
        )
        if name:
            register_prompt_actions(self._registry, executable_prompt, name, variant)
        return executable_prompt

    # Overload 1: Neither typed -> Prompt[Any, Any]
    @overload
    def prompt(
        self,
        name: str,
        *,
        variant: str | None = None,
        input_schema: None = None,
        output_schema: None = None,
    ) -> Prompt[Any, Any]: ...

    # Overload 2: Only input_schema typed
    @overload
    def prompt(
        self,
        name: str,
        *,
        variant: str | None = None,
        input_schema: type[InputT],
        output_schema: None = None,
    ) -> Prompt[InputT, Any]: ...

    # Overload 3: Only output_schema typed
    @overload
    def prompt(
        self,
        name: str,
        *,
        variant: str | None = None,
        input_schema: None = None,
        output_schema: type[OutputT],
    ) -> Prompt[Any, OutputT]: ...

    # Overload 4: Both input_schema and output_schema typed
    @overload
    def prompt(
        self,
        name: str,
        *,
        variant: str | None = None,
        input_schema: type[InputT],
        output_schema: type[OutputT],
    ) -> Prompt[InputT, OutputT]: ...

    def prompt(
        self,
        name: str,
        *,
        variant: str | None = None,
        input_schema: type[InputT] | None = None,
        output_schema: type[OutputT] | None = None,
    ) -> Prompt[InputT, OutputT] | Prompt[Any, Any]:
        """Look up a prompt by name and optional variant."""
        return Prompt(
            self,
            name=name,
            variant=variant,
            input_schema=input_schema,
            output_schema=output_schema,
        )

    # -------------------------------------------------------------------------
    # Server infrastructure methods
    # -------------------------------------------------------------------------

    @staticmethod
    def _bind_reflection_socket(host: str, port: int, *, pinned: bool) -> socket.socket:
        """Bind and listen on the v1 reflection socket.

        A pinned port is bound exactly. Otherwise the next free port at or above
        ``port`` is used. The address family follows ``host``, so IPv6 hosts
        such as ``::1`` work.

        Raises:
            OSError: If the pinned port is taken, or no port in the probe range
                is free.
        """
        candidates = [port] if pinned else range(port, min(port + 100, 65536))
        last: OSError | None = None
        for candidate in candidates:
            # Resolve per candidate: bind needs the family-specific sockaddr (an
            # IPv6 one is a 4-tuple). Prefer IPv4 when the host has both, so
            # 'localhost' keeps binding 127.0.0.1 rather than ::1.
            infos = socket.getaddrinfo(host, candidate, type=socket.SOCK_STREAM, flags=socket.AI_PASSIVE)
            family, socktype, proto, _, sockaddr = next((info for info in infos if info[0] == socket.AF_INET), infos[0])
            sock = socket.socket(family, socktype, proto)
            # POSIX: SO_REUSEADDR only allows rebinding a port in TIME_WAIT
            # (fast restarts). Windows: it allows binding a port that is
            # already in use, which would break probing and pinned-port
            # failure, so claim the port exclusively instead.
            if sys.platform == 'win32':
                sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1)
            else:
                sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
            try:
                sock.bind(sockaddr)
            except OSError as e:
                sock.close()
                last = e
                continue
            sock.listen(2048)
            return sock
        if pinned:
            raise last or OSError(f'port {port} is not available')
        # Each Genkit() with reflection on holds one port; a notebook that
        # re-runs `ai = Genkit(...)` exhausts the range.
        raise OSError(
            f'No free reflection port in {port}-{port + 99}. Each Genkit() instance with the Dev UI '
            'reflection server on (GENKIT_ENV=dev) holds one port; reuse one instance instead of '
            'creating a new one per cell or request.'
        ) from last

    def _start_reflection_background(self) -> None:
        """Start the Dev UI reflection server in a background daemon thread.

        If GENKIT_REFLECTION_V2_SERVER is set (the CLI launches the runtime in
        v2 mode and provides a WebSocket URL), run the v2 JSON-RPC client.
        Otherwise start the v1 HTTP server.

        Raises:
            OSError: If the v1 socket cannot be bound. It is bound here, on the
                calling thread, so a busy pinned port fails ``Genkit()`` rather
                than a background thread nobody is watching.
        """
        config = self._reflection_config
        quiet_log_export_logs()

        sock: socket.socket | None = None
        if config.mode == 'v1':
            sock = self._bind_reflection_socket(config.host, config.port, pinned=config.pinned)
            bound_host, bound_port = sock.getsockname()[:2]
            if ':' in bound_host:
                bound_host = f'[{bound_host}]'
            self._reflection_bound_addr = f'{bound_host}:{bound_port}'
            # Bound already, so the spec is known before the thread starts.
            # spec.url goes into the runtime file, so advertise a reachable,
            # URL-safe host (wildcard binds as loopback, IPv6 bracketed).
            host, port = sock.getsockname()[:2]
            self._reflection_server_spec = ServerSpec(scheme='http', host=advertised_reflection_host(host), port=port)
            quiet_reflection_logs()

        async def _run_server() -> None:
            if config.mode == 'v2':
                assert config.v2_url is not None
                logger.debug(f'Genkit Dev UI reflection v2 client connecting to {config.v2_url}')
                server_v2 = ReflectionServerV2(self._registry, config.v2_url, secret=config.secret)
                self._reflection_ready.set()
                await server_v2.run_forever()
                return

            assert sock is not None
            spec = self._reflection_server_spec
            assert spec is not None
            sockets = [sock]

            if not config.secret and not is_loopback_host(config.host):
                logger.warning(
                    'Reflection API is listening on %s without authentication. Anyone who can reach '
                    'this port can run any registered action. Set GENKIT_REFLECTION_SECRET_TOKEN, '
                    'or front it with your own auth.',
                    config.host,
                )

            app = create_reflection_asgi_app(registry=self._registry, secret=config.secret)
            # If the application configured uvicorn loggers, leave log_config
            # and log_level at None so uvicorn's Config doesn't re-apply
            # dictConfig or overwrite levels; ReflectionLogFilter filters
            # reflection records by thread. Otherwise, configure uvicorn with
            # debug level so records reach ReflectionLogFilter (which quiets
            # them under info and prints them under debug).
            if has_app_uvicorn_logging():
                uvicorn_config = uvicorn.Config(
                    app,
                    host=spec.host,
                    port=spec.port,
                    loop='asyncio',
                    log_config=None,
                    log_level=None,
                )
            else:
                uvicorn_config = uvicorn.Config(
                    app,
                    host=spec.host,
                    port=spec.port,
                    loop='asyncio',
                    log_level='debug',
                )
            server = ReflectionServer(uvicorn_config, ready=self._reflection_ready)
            # Dev only: the runtime file exists so a local CLI watching the
            # same filesystem can discover this runtime. Nothing is watching in
            # a container, and the working directory is frequently read-only.
            if not is_dev_environment():
                server_task = asyncio.create_task(server.serve(sockets=sockets))
                await asyncio.to_thread(self._reflection_ready.wait)
                if server.should_exit:
                    logger.warning(f'Reflection server at {spec.url} failed to start.')
                    return
                logger.debug(f'Genkit reflection server running at {spec.url}')
                await server_task
                return

            async with RuntimeManager(spec, lazy_write=True, secret=config.secret) as runtime_manager:
                server_task = asyncio.create_task(server.serve(sockets=sockets))
                await asyncio.to_thread(self._reflection_ready.wait)

                if server.should_exit:
                    logger.warning(f'Reflection server at {spec.url} failed to start.')
                    return

                runtime_manager.write_runtime_file()
                logger.debug(f'Genkit Dev UI reflection server running at {spec.url}')
                await server_task

        def _thread_main() -> None:
            try:
                asyncio.run(_run_server())
            finally:
                self._reflection_stopped.set()

        threading.Thread(
            target=_thread_main,
            daemon=True,
            name=REFLECTION_THREAD_NAME,
        ).start()

    def _initialize_registry(self, model: ModelArg | None, plugins: list[Plugin] | None) -> None:
        """Initialize the registry with default model and plugins."""
        if model:
            self._registry.register_value('defaultModel', 'defaultModel', model)
        for fmt in built_in_formats:
            self.define_format(fmt)

        if not plugins:
            logger.debug('No plugins provided to Genkit')
        else:
            for plugin in plugins:
                if isinstance(plugin, Plugin):  # pyright: ignore[reportUnnecessaryIsInstance]
                    self._registry.register_plugin(plugin)
                else:
                    raise ValueError(
                        f'Invalid {plugin=} provided to Genkit: must be a `genkit.plugin_api.Plugin` instance. '
                        'Middleware classes such as `genkit.middleware.Middleware` subclasses go in `use=[...]`; '
                        'register the `genkit_middleware.Middleware()` plugin in `plugins=[...]`.'
                    )

    def _register_plugin_middleware(self, plugins: list[Plugin] | None) -> None:
        """Register middleware classes returned by ``Plugin.list_middleware``."""
        if not plugins:
            return
        for plugin in plugins:
            for mw_cls in plugin.list_middleware():
                self.define_middleware(mw_cls)

    def run_main(self, coro: Coroutine[Any, Any, T]) -> T:
        """Run your ``main`` coroutine and return its result, like ``asyncio.run``.

        With reflection on (``GENKIT_ENV=dev``, which ``genkit start`` sets, or
        ``GENKIT_REFLECTION_ENABLED=true``), it keeps the process alive after
        ``main`` returns, so the Dev UI can keep running your flows, until
        Ctrl+C, SIGTERM, or the reflection server stops on its own. With
        reflection off, it returns as soon as ``main`` does.

        If ``main`` raises while reflection is on, the error is logged and the
        Dev UI stays up. The error is raised once the process stops. Ctrl+C
        after a successful ``main`` raises ``KeyboardInterrupt``, and SIGTERM
        returns ``main``'s result.

        Example:
            ```python
            from genkit import Genkit
            from genkit_google_genai import GoogleAI

            # 1. Initialize Genkit and define a flow
            ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))


            @ai.flow
            async def suggest_dish(cuisine: str) -> str:
                response = await ai.generate(prompt=f'Suggest one {cuisine} dish.')
                return response.text


            # 2. Run a quick check from your script's entry point
            async def main() -> None:
                print(await suggest_dish('Thai'))


            # 3. Start it
            ai.run_main(main())
            # => Green curry with chicken
            #    `python main.py` exits here. Under `genkit start`, the process
            #    stays up for the Dev UI until you press Ctrl+C.
            ```
        """
        try:
            asyncio.get_running_loop()
        except RuntimeError:
            pass
        else:
            # Jupyter, IPython, and async frameworks already run a loop, and
            # asyncio.run would fail with a raw RuntimeError plus an
            # unawaited-coroutine warning.
            coro.close()
            raise RuntimeError(
                'ai.run_main() cannot be called from a running event loop (Jupyter, IPython, or an async '
                'framework). Use `await main()` instead.'
            )
        if not self._reflection_config.enabled:
            return run_loop(coro)

        user_error: Exception | None = None
        stop_signal: signal.Signals | None = None

        async def reflection_runner() -> T | None:
            nonlocal user_error, stop_signal
            user_result: T | None = None
            try:
                user_result = await coro
                logger.debug('User coroutine completed successfully.')
            except Exception as e:
                # Script entrypoint failed — there's no Dev UI panel for this run,
                # so keep a headline + a debug traceback.
                logger.error('Startup failed: %s: %s', type(e).__name__, e)
                logger.debug('Startup failure details', exc_info=True)
                user_error = e

            # Block until Ctrl+C, SIGTERM, or the reflection server stops,
            # keeping the daemon reflection thread alive. The receiver is open
            # before the ready line, so a signal sent once it prints is ours,
            # not asyncio's default SIGINT handling.
            try:
                with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as sigs:
                    logger.info(self._reflection_ready_message())
                    async with anyio.create_task_group() as tg:

                        async def _handle_signal(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                            nonlocal stop_signal
                            async for sig in sigs:
                                stop_signal = sig
                                tg_.cancel_scope.cancel()
                                return

                        async def _handle_reflection_stopped(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                            # Poll rather than park a worker thread in Event.wait:
                            # anyio worker threads are non-daemon, so a parked one
                            # keeps the process alive after run_main returns.
                            while not self._reflection_stopped.is_set():  # noqa: ASYNC110 - threading.Event, set off-loop
                                await anyio.sleep(0.25)
                            logger.warning('Reflection server stopped; returning from run_main.')
                            tg_.cancel_scope.cancel()

                        tg.start_soon(_handle_signal, tg)
                        tg.start_soon(_handle_reflection_stopped, tg)
                        await anyio.sleep_forever()
            except anyio.get_cancelled_exc_class():
                pass

            logger.debug('Reflection server stopped.')
            return user_result

        # Decide out here, after the loop has shut down cleanly, so neither the
        # coroutine's error nor KeyboardInterrupt is raised during asyncio shutdown.
        try:
            result = anyio.run(reflection_runner)
        except KeyboardInterrupt:
            # Ctrl+C before the receiver opened (main still running).
            if user_error is None:
                raise
            raise user_error from None
        if user_error is not None:
            raise user_error
        if stop_signal == signal.SIGINT:
            raise KeyboardInterrupt
        # main returned normally (user_error is None), so result holds its value.
        return cast(T, result)

    def _reflection_ready_message(self) -> str:
        """The line run_main logs once it starts waiting on the reflection server."""
        config = self._reflection_config
        # Only dev writes the runtime file the Dev UI discovers, so only dev
        # can promise the Dev UI will find this runtime.
        if is_dev_environment():
            return 'Dev UI ready. Press Ctrl+C to stop.'
        if config.mode == 'v2':
            return f'Reflection API connecting to {config.v2_url}. Press Ctrl+C to stop.'
        return f'Reflection API listening on {self._reflection_bound_addr}. Press Ctrl+C to stop.'

    # -------------------------------------------------------------------------
    # Genkit-specific methods (generation, embedding, retrieval, etc.)
    # -------------------------------------------------------------------------

    def _resolve_embedder_name(self, embedder: str | EmbedderRef | None) -> str:
        """Resolve embedder name from string or EmbedderRef."""
        if embedder is None:
            raise ValueError('Embedder must be specified as a string name or an EmbedderRef.')
        return embedder.name if isinstance(embedder, EmbedderRef) else embedder

    async def _embedder_and_options(
        self,
        *,
        embedder: str | EmbedderRef[Any] | None,
        config: object,
    ) -> tuple[Action[EmbedRequest, EmbedResponse, Never], dict[str, Any]]:
        """Resolve the embedder, check the call config, and layer the options.

        Same steps as generate: pick the class (call_config_class), check the
        caller's keys, then ``ref.version < ref.config < call`` folded to that
        class. A required field left out is checked at the action boundary,
        where the embedder's own defaults go underneath.
        """
        name = self._resolve_embedder_name(embedder)
        action = await self._registry.resolve_embedder(name)
        if action is None:
            raise GenkitError(
                status='NOT_FOUND',
                message=f"Embedder '{name}' not found.",
                reason=ErrorReason.ACTION_NOT_FOUND,
            )
        ref = embedder if isinstance(embedder, EmbedderRef) else None
        ref_schema = cast('type[BaseModel] | None', ref.config_schema) if ref else None
        schema = call_config_class(
            name=name,
            kind='embedder',
            ref_schema=ref_schema,
            action_schema=python_config_schema(action.config_schema),
        )
        check_call_config(config=config, schema=schema, model=name)
        options = layer_call_config(
            call=config,
            version=ref.version if ref else None,
            ref_config=ref.config if ref else None,
            schema=schema,
        )
        return action, options

    # Overload: config=ModelConfigDict, output_schema=type[T] -> ModelResponse[T]
    # No config: any ref, including one picked between providers.
    @overload
    async def generate(
        self,
        *,
        model: ModelRef[Any] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[OutputT]: ...

    @overload
    async def generate(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelConfigDict,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[OutputT]: ...

    # Overload: config=ModelRefConfigT | Mapping, output_schema=type[T] -> ModelResponse[T]
    @overload
    async def generate(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[OutputT]: ...

    # Overload: config=ModelConfigDict, no output_schema -> ModelResponse[Any]
    # No config: any ref, including one picked between providers.
    @overload
    async def generate(
        self,
        *,
        model: ModelRef[Any] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[Any]: ...

    @overload
    async def generate(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelConfigDict,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[Any]: ...

    # Overload: config=ModelRefConfigT | Mapping, no output_schema -> ModelResponse[Any]
    @overload
    async def generate(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[Any]: ...

    async def generate(
        self,
        *,
        model: str | ModelRef[Any] | Action | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelResponse[Any]:
        """Generate text or structured data using a language model.

        ``model`` accepts a typed ``ModelRef`` from a plugin constructor
        (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``,
        which takes the bare model ID, stamps the ``'googleai/'`` namespace
        prefix, and type-checks ``config``), a plugin-prefixed string
        (``'googleai/gemini-flash-latest'``), a registered model ``Action``, or
        ``None`` to use the default ``model=`` passed to ``Genkit(...)``. When
        passing a plain ``str`` for a plugin model, the ``<plugin>/`` prefix
        (such as ``'googleai/'`` or ``'vertexai/'``) is required; passing an
        unprefixed string raises ``GenkitError`` with ``NOT_FOUND``. Any model
        ID served by the provider (including newly released models) is resolved
        lazily on demand at call time without needing pre-registration or SDK
        updates.

        ``tools`` is typed as ``Sequence`` rather than ``list`` because ``Sequence``
        is covariant: ``list[Tool]`` or ``list[str]`` are both assignable to
        ``Sequence[str | Tool]``, but not to ``list[str | Tool]``.

        Example:
            from pydantic import BaseModel

            class Weather(BaseModel):
                city: str
                forecast: str

            res = await ai.generate(
                prompt='Weather in Paris?',
                tools=[current_weather],
                output_schema=Weather,
            )
            if res.output:
                print(res.output)
            # => city='Paris' forecast='Sunny'

        ``max_turns`` caps tool rounds (default 50, matching Go): the model may
        call tools that many times and then reply, so a run uses at most
        ``max_turns + 1`` model calls. Past the cap the response is ``ABORTED``
        with reason ``MAX_TURNS_EXCEEDED``.

        ``prompt`` and ``system`` strings are sent exactly as written. Braces
        are content (JSON, code, or another template), not Handlebars.
        Partials (``{{> persona}}``), ``define_helper`` helpers and
        ``{{media url=...}}`` only render in ``define_prompt`` or a ``.prompt``
        file; otherwise build the text or ``Part.from_media(...)`` yourself.
        """
        return await self._generate(
            model=model,
            prompt=prompt,
            system=system,
            messages=messages,
            tools=tools,
            return_tool_requests=return_tool_requests,
            tool_choice=tool_choice,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
            config=config,
            max_turns=max_turns,
            context=context,
            output_schema=output_schema,
            output_format=output_format,
            output_content_type=output_content_type,
            output_instructions=output_instructions,
            output_constrained=output_constrained,
            use=use,
            docs=docs,
        )

    # Overload: config=ModelConfigDict, output_schema=type[T] -> ModelStreamResponse[T]
    # No config: any ref, including one picked between providers.
    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[Any] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[OutputT]: ...

    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelConfigDict,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[OutputT]: ...

    # Overload: config=ModelRefConfigT | Mapping, output_schema=type[T] -> ModelStreamResponse[T]
    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[OutputT],
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[OutputT]: ...

    # Overload: config=ModelConfigDict, no output_schema -> ModelStreamResponse[Any]
    # No config: any ref, including one picked between providers.
    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[Any] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[Any]: ...

    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelConfigDict,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[Any]: ...

    # Overload: config=ModelRefConfigT | Mapping, no output_schema -> ModelStreamResponse[Any]
    @overload
    def generate_stream(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[Any]: ...

    def generate_stream(
        self,
        *,
        model: str | ModelRef[Any] | Action | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> ModelStreamResponse[Any]:
        """Stream generated text, returning a ModelStreamResponse with .stream and .response.

        With ``output_schema=Recipe``, each ``chunk.output`` is a partial of
        that type: same attributes, any field may still be ``None`` or a
        prefix. Guard the field you are about to use. The finished
        ``Recipe`` is only ``(await result.response).output``, and it's ``None``
        when the reply isn't a ``Recipe``.

        If the model fails partway through, the ``async for`` still ends
        normally. The final response has ``finish_reason == FAILED``,
        ``error`` set, ``text == ''``, ``message is None``, and ``messages``
        ending at the last complete turn, so it's safe to send back. The
        chunks you already received are the record of what was shown.

        Use ``async with result.stream as stream:`` so that leaving the loop
        early (``break``, an exception, a disconnected client) closes the
        stream and stops the model call.

        Example:
            ```python
            # 1. Start streaming
            result = ai.generate_stream(prompt='Write a haiku about rain.')

            # 2. Print chunks as they arrive; the context manager closes the stream
            async with result.stream as stream:
                async for chunk in stream:
                    print(chunk.text, end='')
            print()
            # => Soft rain on the roof...

            # 3. Await the final response
            final = await result.response
            print(final.finish_reason)
            # => stop
            ```
        """
        check_max_turns(max_turns)
        initial_msgs: list[Message] = []
        if not isinstance(messages, str):
            initial_msgs = call_messages(system=system, messages=messages, prompt=prompt)

        async def _run_generate(
            send_chunk: Callable[[ModelResponseChunk], None],
            caller_stopped: asyncio.Event,
        ) -> ModelResponse[Any]:
            return await self._generate(
                model=model,
                prompt=prompt,
                system=system,
                messages=messages,
                tools=tools,
                return_tool_requests=return_tool_requests,
                tool_choice=tool_choice,
                resume_respond=resume_respond,
                resume_restart=resume_restart,
                resume_metadata=resume_metadata,
                config=config,
                max_turns=max_turns,
                context=context,
                output_schema=output_schema,
                output_format=output_format,
                output_content_type=output_content_type,
                output_instructions=output_instructions,
                output_constrained=output_constrained,
                use=use,
                docs=docs,
                on_chunk=send_chunk,
                caller_stopped=caller_stopped,
            )

        stream, task = start_generate_stream(initial_messages=initial_msgs, run=_run_generate)
        return ModelStreamResponse[Any](stream=stream, response=task)

    async def _generate(
        self,
        *,
        model: str | ModelRef[Any] | Action | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        return_tool_requests: bool | None = None,
        tool_choice: ToolChoice | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
        max_turns: int | None = None,
        context: dict[str, object] | None = None,
        output_schema: type[Any] | dict[str, Any] | str | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_constrained: bool | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        on_chunk: Callable[[ModelResponseChunk], None] | None = None,
        caller_stopped: asyncio.Event | None = None,
    ) -> ModelResponse[Any]:
        """Fold ``ai.generate`` kwargs into engine ``options`` and run generate_action.

        Inline tools and middleware live on a child registry so they die
        with the call and stay out of ``self._registry``.
        """
        if isinstance(messages, str):
            raise TypeError('messages must be a list of Message; pass text with prompt=')
        # Before GenerateCall, whose lax int field turns True into 1.
        check_max_turns(max_turns)
        if prompt is not None and (resume_respond is not None or resume_restart is not None):
            return box_from_exc(
                response=ModelResponse(),
                messages=call_messages(system=system, messages=messages, prompt=prompt),
                exc=PublicError(
                    'FAILED_PRECONDITION',
                    "Cannot 'resume' generation unless the previous message is a model message with at least one"
                    ' tool request. resume_respond/resume_restart cannot be combined with prompt=.',
                    reason=ErrorReason.INVALID_RESUME,
                ),
                caller_stopped=False,
                reason=ErrorReason.INVALID_RESUME,
            )

        scope = CallScope(self)
        registry = scope.registry
        await register_tools(registry, tools)
        use_refs = register_middleware(registry, use)
        resolved = await resolve_for_generate(model=model, config=config, registry=registry)
        check_call_config(config=config, schema=resolved.config_schema, model=resolved.name)
        # strings passed at call time are content, not templates: braces may be
        # JSON, code, or another template. templates are what you define up
        # front (define_prompt, .prompt files, define_agent's system).
        resolved_msgs = call_messages(system=system, messages=messages, prompt=prompt)
        options = await to_generate_options(
            registry=registry,
            call=GenerateCall(
                model=resolved.name,
                prompt=None,
                system=None,
                messages=resolved_msgs,
                tools=tools,
                return_tool_requests=return_tool_requests,
                tool_choice=tool_choice,
                resume_respond=resume_respond,
                resume_restart=resume_restart,
                resume_metadata=resume_metadata,
                config=resolved.config,
                max_turns=max_turns,
                output_format=output_format,
                output_content_type=output_content_type,
                output_instructions=output_instructions,
                output_schema=output_schema,
                output_constrained=output_constrained,
                docs=docs,
                use=use_refs,
            ),
        )
        return await generate_action(
            scope,
            options,
            on_chunk=on_chunk,
            context=context,
            caller_stopped=caller_stopped,
        )

    # No config: any ref, including one picked between providers.
    @overload
    async def embed(
        self,
        *,
        embedder: str | EmbedderRef[Any],
        content: str | Document,
        metadata: dict[str, object] | None = None,
        config: None = None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]: ...

    # A config is pinned to the ref's config class.
    @overload
    async def embed(
        self,
        *,
        embedder: str | EmbedderRef[EmbedderRefConfigT],
        content: str | Document,
        metadata: dict[str, object] | None = None,
        config: EmbedderRefConfigT | Mapping[str, Any] | None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]: ...

    async def embed(
        self,
        *,
        embedder: str | EmbedderRef[Any],
        content: str | Document,
        metadata: dict[str, object] | None = None,
        config: BaseModel | Mapping[str, Any] | None = None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]:
        """Generate vector embeddings for a single document or string.

        ``config`` is layered over the ``EmbedderRef``'s version and config
        (the call wins per key) and reaches the embedder as
        ``request.options``. A config object must be the embedder's options
        class. An embedder name that isn't registered raises ``GenkitError``
        with ``NOT_FOUND``.

        ``metadata`` is attached to a string ``content``. A ``Document``
        already carries its own metadata, so passing both raises ``TypeError``.

        ``context`` reaches the embedder as ``ctx.context``, as on
        ``generate``. Omitted, the embedder sees the enclosing action's
        context. The GoogleAI, VertexAI and OpenAI embedders read a
        per-request key from ``context={'secrets': {'api_key': ...}}``, so
        the tenant, not the plugin key, is billed. Ollama and Bedrock
        embedders always use the plugin's client.

        Example:
            from genkit_google_genai import GoogleAI

            embeddings = await ai.embed(
                embedder=GoogleAI.embedder('gemini-embedding-001'),
                content='Hello world',
            )
            vector = embeddings[0].embedding
        """
        if metadata is not None and isinstance(content, Document):
            raise TypeError(_DOCUMENT_METADATA_CONFLICT)

        embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

        documents = [Document.from_text(content, metadata)] if isinstance(content, str) else [content]

        response = (
            await embed_action.run(
                EmbedRequest(
                    input=documents,
                    options=final_options,
                ),
                context=context,
            )
        ).response
        return response.embeddings

    # No config: any ref, including one picked between providers.
    @overload
    async def embed_many(
        self,
        *,
        embedder: str | EmbedderRef[Any],
        content: Sequence[str | Document],
        metadata: dict[str, object] | None = None,
        config: None = None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]: ...

    # A config is pinned to the ref's config class.
    @overload
    async def embed_many(
        self,
        *,
        embedder: str | EmbedderRef[EmbedderRefConfigT],
        content: Sequence[str | Document],
        metadata: dict[str, object] | None = None,
        config: EmbedderRefConfigT | Mapping[str, Any] | None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]: ...

    async def embed_many(
        self,
        *,
        embedder: str | EmbedderRef[Any],
        content: Sequence[str | Document],
        metadata: dict[str, object] | None = None,
        config: BaseModel | Mapping[str, Any] | None = None,
        context: dict[str, Any] | None = None,
    ) -> list[Embedding]:
        """Generate vector embeddings for multiple documents in a single batch call.

        ``content`` is any sequence (list, tuple, ...) of strings or
        ``Document``s; one embedding comes back per item, in order. A bare
        ``str`` raises ``TypeError``; use ``embed`` for one item.
        ``config``, ``metadata`` and ``context`` work the same as on ``embed``.
        """
        if isinstance(content, str):
            raise TypeError('embed_many() takes a sequence of strings or Documents, not a str; use embed() for one.')
        if metadata is not None and any(isinstance(item, Document) for item in content):
            raise TypeError(_DOCUMENT_METADATA_CONFLICT)

        # Convert strings to Documents if needed
        documents: list[Document] = [
            Document.from_text(item, metadata) if isinstance(item, str) else item for item in content
        ]

        embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

        response = (
            await embed_action.run(EmbedRequest(input=documents, options=final_options), context=context)  # type: ignore[arg-type]
        ).response
        return response.embeddings

    async def evaluate(
        self,
        *,
        evaluator: str | EvaluatorRef,
        dataset: list[BaseDataPoint],
        config: dict[str, object] | None = None,
        eval_run_id: str | None = None,
    ) -> list[EvaluatorResponse]:
        """Evaluate a dataset using the specified evaluator.

        Returns a list of rows. A per-row evaluator gives one row per
        datapoint, in dataset order. A batch evaluator gives the rows its
        function returned, as returned. Each row's ``evaluation`` is a list of
        scores.

        ``config`` is merged over the ``EvaluatorRef``'s config (the call
        wins per key) and handed to the evaluator as its second argument. When
        neither sets anything, the evaluator gets ``None``. An evaluator name
        that isn't registered raises ``GenkitError`` with ``NOT_FOUND``.

        Example:
            from genkit.evaluator import BaseDataPoint

            results = await ai.evaluate(
                evaluator='my_eval',
                dataset=[BaseDataPoint(input='What is 2+2?', output='4')],
            )
            for row in results:
                for score in row.evaluation:
                    print(row.test_case_id, score.score)
        """
        warn_evaluators_deprecated()
        if isinstance(evaluator, EvaluatorRef):
            evaluator_name = evaluator.name
            ref_config = evaluator.config
        else:
            evaluator_name = evaluator
            ref_config = None

        # same rule as _embedder_options: None when nothing was set, matching
        # what the CLI / Dev UI send, so `options is None` is the one check.
        final_options: dict[str, object] | None = None
        if ref_config is not None or config is not None:
            final_options = {**(ref_config or {}), **(config or {})}

        eval_action = await self._registry.resolve_evaluator(evaluator_name)
        if eval_action is None:
            raise GenkitError(
                status='NOT_FOUND',
                message=f"Evaluator '{evaluator_name}' not found.",
                reason=ErrorReason.ACTION_NOT_FOUND,
            )

        if not eval_run_id:
            eval_run_id = str(uuid.uuid4())

        with suppress_evaluator_warning():
            response = await eval_action.run(
                EvaluatorRequest(
                    dataset=dataset,
                    options=final_options,
                    eval_run_id=eval_run_id,
                ),
            )
        return response.response.root

    @staticmethod
    def current_context() -> dict[str, Any] | None:
        """Get the current execution context, or None if not in an action."""
        return get_current_context()

    async def run(
        self,
        name: str,
        fn: Callable[[], Awaitable[T]],
        *,
        metadata: dict[str, Any] | None = None,
    ) -> T:
        """Run a function as a discrete traced step within a flow.

        ``fn`` takes no arguments and returns an awaitable, so ``async def``
        functions, ``lambda: fetch(i)``, and callables with an ``async def
        __call__`` all work. Same shape as JS ``ai.run('step', fn)``.

        Example:
            ```python
            # 1. Each fan-out step gets its own span in the trace
            menus = await asyncio.gather(*[ai.run(f'fetch-{i}', lambda i=i: fetch_menu(i)) for i in range(3)])

            # 2. Keyword form still works
            total = await ai.run(name='sum', fn=lambda: sum_prices(menus))
            ```
        """
        if not callable(fn):
            raise TypeError(f'fn must be callable, got {type(fn).__name__}')
        not_awaitable = (
            'fn must return an awaitable: pass an async def, a lambda returning a coroutine, '
            'or wrap blocking work in asyncio.to_thread'
        )

        async def body(_span: object) -> T:
            result = fn()
            if not inspect.isawaitable(result):
                # Steps stay async like tools and flows; blocking work goes
                # through asyncio.to_thread.
                raise TypeError(not_awaitable)
            return await result

        attributes = {metadata_key(k): str(v) for k, v in (metadata or {}).items()}
        return await run_in_new_span(name, body, action_type='flowStep', attributes=attributes)

    @overload
    async def check_operation(
        self,
        operation: Operation[T],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[T]: ...

    @overload
    async def check_operation(
        self,
        operation: Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[Any]: ...

    async def check_operation(
        self,
        operation: Operation[Any] | Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[Any]:
        """Poll a background job.

        Generic like JS ``checkOperation<T>``: an ``Operation[T]`` comes back
        as ``Operation[T]``, a stored dict as ``Operation[Any]``. The handle's
        ``action`` key finds the job. For a background model the handle is
        validated as ``Operation[ModelResponse]`` before anything runs: an
        unknown key, a missing ``id``, or an ``output`` that isn't a
        ModelResponse is INVALID_ARGUMENT.

        Pass ``context={'secrets': {'api_key': ...}}`` again when start used a
        per-request key. ``config`` is client knobs (``base_url``,
        ``location``, ``api_version``), not video settings.

        Example:
            ```python
            # 1. Start a job and store the handle as JSON
            op = await ai.generate_operation(
                model='googleai/veo-3.1-generate-preview',
                prompt='A chef plating risotto.',
            )
            saved = op.model_dump_json()

            # 2. Later, reload it typed and poll
            op = await ai.check_operation(Operation[ModelResponse].model_validate_json(saved))
            print(op.done)
            # => False

            # 3. Poll until done; output is a ModelResponse
            while not op.done:
                op = await ai.check_operation(op)
            if op.output and op.output.media:
                print(op.output.media.url)
            # => https://storage.googleapis.com/.../risotto.mp4
            ```
        """
        return await check_operation(self._registry, operation, context=context, config=config)

    @overload
    async def cancel_operation(
        self,
        operation: Operation[T],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[T]: ...

    @overload
    async def cancel_operation(
        self,
        operation: Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[Any]: ...

    async def cancel_operation(
        self,
        operation: Operation[Any] | Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
        config: Mapping[str, Any] | None = None,
    ) -> Operation[Any]:
        """Cancel a background job.

        Same input and return types as ``check_operation``: ``Operation[T]``
        in, ``Operation[T]`` out; a stored dict in, ``Operation[Any]`` out.
        Same ``context`` / ``config`` pockets.

        Example:
            ```python
            # 1. Reload the stored handle and cancel it
            op = await ai.cancel_operation(json.loads(saved))

            # 2. The returned handle reflects the cancel attempt
            print(op.id)
            # => operations/risotto-123
            ```
        """
        return await cancel_operation(self._registry, operation, context=context, config=config)

    # No config: any ref, including one picked between providers.
    @overload
    async def generate_operation(
        self,
        *,
        model: ModelRef[Any] | BackgroundModel | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        config: None = None,
        context: dict[str, object] | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> Operation[ModelResponse]: ...

    @overload
    async def generate_operation(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | BackgroundModel | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        config: ModelConfigDict,
        context: dict[str, object] | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> Operation[ModelResponse]: ...

    @overload
    async def generate_operation(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | BackgroundModel | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        context: dict[str, object] | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> Operation[ModelResponse]: ...

    async def generate_operation(
        self,
        *,
        model: ModelRef[ModelRefConfigT] | BackgroundModel | str | None = None,
        prompt: str | list[Part] | None = None,
        system: str | list[Part] | None = None,
        messages: list[Message] | None = None,
        config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
        context: dict[str, object] | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
    ) -> Operation[ModelResponse]:
        """Generate content using a long-running model, returning an Operation to poll.

        A background start is one request that returns a job handle. There is
        no tool loop and no output parsing on ``check_operation``, so tools,
        ``max_turns``, and the ``output_*`` options are not accepted here.

        Example:
            op = await ai.generate_operation(
                model='googleai/veo-3.1-generate-preview',
                prompt='A timelapse of a flower blooming.',
            )
            while not op.done:
                op = await ai.check_operation(op)
        """
        if isinstance(model, BackgroundModel):
            # Same as its name, once we know this registry holds that object.
            model = background_model_name(model=model, registry=self._registry)
        resolved = await resolve_for_generate(
            model=model,
            config=config,
            registry=self._registry,
            message='No model specified for generate_operation.',
        )
        check_call_config(config=config, schema=resolved.config_schema, model=resolved.name)

        model_action = await self._registry.resolve_model(resolved.name)
        if not model_action:
            raise GenkitError(
                status='NOT_FOUND',
                message=f"Model '{resolved.name}' not found.",
                reason=ErrorReason.MODEL_NOT_FOUND,
            )

        if model_action.kind != ActionKind.BACKGROUND_MODEL:
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=f"Model '{model_action.name}' does not support long running operations.",
                reason=ErrorReason.UNSUPPORTED_BY_MODEL,
            )

        # Call generate with already-resolved wire name + config.
        response = await self.generate(
            model=resolved.name,
            prompt=prompt,
            system=system,
            messages=messages,
            config=resolved.config,
            context=context,
            use=use,
            docs=docs,
        )

        if response.error is not None:
            # This call is "give me the ticket." A start that already
            # failed is not that ticket — while-not-done would poll it
            # as a live job.
            err = GenkitError(
                status=response.error.status or 'INTERNAL',
                message=response.error.message,
                details=response.error.details,
                reason=response.error.reason,
            )
            mark_already_sourced(err)
            raise err
        if not response.operation:
            raise missing_operation_error(name=model_action.name)
        return as_model_operation(response.operation, name=model_action.name, status='INTERNAL')

__init__(*args, plugins=None, model=None, prompt_dir=None)

Initialize a Genkit instance.

Parameters:

Name Type Description Default
plugins list[genkit._core._plugin.Plugin] | None

Plugins to register (e.g. [GoogleAI()]). Plugins resolve models lazily on demand when ai.generate() is called.

None
model genkit._ai._model.ModelArg | None

Default model for ai.generate(). Accepts a typed ModelRef (recommended, e.g. GoogleAI.gemini('gemini-flash-latest')) or a plugin-prefixed string ('googleai/gemini-flash-latest').

None
prompt_dir str | pathlib.Path | None

Optional directory for loading .prompt files.

None
Source code in packages/genkit/src/genkit/_ai/_aio.py
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
def __init__(  # noqa: D417
    self,
    *args: object,
    plugins: list[Plugin] | None = None,
    model: ModelArg | None = None,
    prompt_dir: str | Path | None = None,
) -> None:
    """Initialize a Genkit instance.

    Args:
        plugins: Plugins to register (e.g. ``[GoogleAI()]``). Plugins resolve
            models lazily on demand when ``ai.generate()`` is called.
        model: Default model for ``ai.generate()``. Accepts a typed ``ModelRef``
            (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``) or
            a plugin-prefixed string (``'googleai/gemini-flash-latest'``).
        prompt_dir: Optional directory for loading ``.prompt`` files.
    """
    if args:
        raise TypeError(
            f'Genkit() takes no positional arguments, got {len(args)}. '
            f'Pass keyword arguments instead, e.g. {init_keyword_example(args[0])}.'
        )
    # Before anything that logs, so plugin initialization is covered too.
    configure_logging()
    self._registry = Registry()
    self._reflection_server_spec = None
    # The reflection API runs under GENKIT_ENV=dev, or in any environment
    # with GENKIT_REFLECTION_ENABLED=true. Resolving here keeps an invalid
    # setting a constructor-time error.
    self._reflection_config = resolve_reflection_config()
    self._reflection_ready = threading.Event()
    # Set when the reflection thread exits for any reason (v2 auth
    # rejection, server crash), so run_main stops waiting on nothing.
    self._reflection_stopped = threading.Event()
    # host:port the v1 socket is bound to, set in the constructor so
    # run_main can log it without waiting on the server thread.
    self._reflection_bound_addr = None
    self._initialize_registry(model, plugins)
    # Ensure the default generate action is registered for async usage.
    define_generate_action(self)
    self._register_plugin_middleware(plugins)
    maybe_inject_dev_instrumentation()
    # When reflection is on, start the server immediately in a background
    # daemon thread so it's available regardless of which web framework (or
    # none) the user chooses.
    if self._reflection_config.enabled:
        # SIGINT (Ctrl+C) always hits handle_signal. SIGTERM inside the
        # run_main wait loop is stolen by anyio (clean exit → atexit);
        # elsewhere SIGTERM also goes through handle_signal. Both paths
        # remove the runtime discovery files.
        setup_signal_handlers()
        self._start_reflection_background()

    # Load prompts
    load_path = prompt_dir
    if load_path is None:
        default_prompts_path = Path('./prompts')
        if default_prompts_path.is_dir():
            load_path = default_prompts_path

    if load_path:
        load_prompt_folder(self, dir_path=load_path)

cancel_operation(operation, *, context=None, config=None) async

cancel_operation(
    operation: Operation[T],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[T]
cancel_operation(
    operation: Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[Any]

Cancel a background job.

Same input and return types as check_operation: Operation[T] in, Operation[T] out; a stored dict in, Operation[Any] out. Same context / config pockets.

Example
# 1. Reload the stored handle and cancel it
op = await ai.cancel_operation(json.loads(saved))

# 2. The returned handle reflects the cancel attempt
print(op.id)
# => operations/risotto-123
Source code in packages/genkit/src/genkit/_ai/_aio.py
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
async def cancel_operation(
    self,
    operation: Operation[Any] | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None,
) -> Operation[Any]:
    """Cancel a background job.

    Same input and return types as ``check_operation``: ``Operation[T]``
    in, ``Operation[T]`` out; a stored dict in, ``Operation[Any]`` out.
    Same ``context`` / ``config`` pockets.

    Example:
        ```python
        # 1. Reload the stored handle and cancel it
        op = await ai.cancel_operation(json.loads(saved))

        # 2. The returned handle reflects the cancel attempt
        print(op.id)
        # => operations/risotto-123
        ```
    """
    return await cancel_operation(self._registry, operation, context=context, config=config)

check_operation(operation, *, context=None, config=None) async

check_operation(
    operation: Operation[T],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[T]
check_operation(
    operation: Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[Any]

Poll a background job.

Generic like JS checkOperation<T>: an Operation[T] comes back as Operation[T], a stored dict as Operation[Any]. The handle's action key finds the job. For a background model the handle is validated as Operation[ModelResponse] before anything runs: an unknown key, a missing id, or an output that isn't a ModelResponse is INVALID_ARGUMENT.

Pass context={'secrets': {'api_key': ...}} again when start used a per-request key. config is client knobs (base_url, location, api_version), not video settings.

Example
# 1. Start a job and store the handle as JSON
op = await ai.generate_operation(
    model='googleai/veo-3.1-generate-preview',
    prompt='A chef plating risotto.',
)
saved = op.model_dump_json()

# 2. Later, reload it typed and poll
op = await ai.check_operation(Operation[ModelResponse].model_validate_json(saved))
print(op.done)
# => False

# 3. Poll until done; output is a ModelResponse
while not op.done:
    op = await ai.check_operation(op)
if op.output and op.output.media:
    print(op.output.media.url)
# => https://storage.googleapis.com/.../risotto.mp4
Source code in packages/genkit/src/genkit/_ai/_aio.py
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
async def check_operation(
    self,
    operation: Operation[Any] | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None,
) -> Operation[Any]:
    """Poll a background job.

    Generic like JS ``checkOperation<T>``: an ``Operation[T]`` comes back
    as ``Operation[T]``, a stored dict as ``Operation[Any]``. The handle's
    ``action`` key finds the job. For a background model the handle is
    validated as ``Operation[ModelResponse]`` before anything runs: an
    unknown key, a missing ``id``, or an ``output`` that isn't a
    ModelResponse is INVALID_ARGUMENT.

    Pass ``context={'secrets': {'api_key': ...}}`` again when start used a
    per-request key. ``config`` is client knobs (``base_url``,
    ``location``, ``api_version``), not video settings.

    Example:
        ```python
        # 1. Start a job and store the handle as JSON
        op = await ai.generate_operation(
            model='googleai/veo-3.1-generate-preview',
            prompt='A chef plating risotto.',
        )
        saved = op.model_dump_json()

        # 2. Later, reload it typed and poll
        op = await ai.check_operation(Operation[ModelResponse].model_validate_json(saved))
        print(op.done)
        # => False

        # 3. Poll until done; output is a ModelResponse
        while not op.done:
            op = await ai.check_operation(op)
        if op.output and op.output.media:
            print(op.output.media.url)
        # => https://storage.googleapis.com/.../risotto.mp4
        ```
    """
    return await check_operation(self._registry, operation, context=context, config=config)

current_context() staticmethod

Get the current execution context, or None if not in an action.

Source code in packages/genkit/src/genkit/_ai/_aio.py
2596
2597
2598
2599
@staticmethod
def current_context() -> dict[str, Any] | None:
    """Get the current execution context, or None if not in an action."""
    return get_current_context()

define_background_model(name, *, start, check, cancel=None, info=None, config_schema=None, metadata=None, description=None)

Register a background model for long-running AI operations.

Source code in packages/genkit/src/genkit/_ai/_aio.py
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
def define_background_model(
    self,
    name: str,
    *,
    start: StartModelOpFn,
    check: CheckModelOpFn,
    cancel: CancelModelOpFn | None = None,
    info: ModelInfo | None = None,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> BackgroundModel:
    """Register a background model for long-running AI operations."""
    return define_background_model(
        registry=self._registry,
        name=name,
        start=start,
        check=check,
        cancel=cancel,
        info=info,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_batch_evaluator(name, fn, *, display_name, definition, is_billed=False, config_schema=None, metadata=None, description=None)

Register a batch evaluator.

The function takes one EvaluatorRequest and returns list[EvaluatorResponse]. Read options from req.options. A second parameter raises TypeError when defined.

Source code in packages/genkit/src/genkit/_ai/_aio.py
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
def define_batch_evaluator(
    self,
    name: str,
    fn: BatchEvaluatorFn,
    *,
    display_name: str,
    definition: str,
    is_billed: bool = False,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> BatchEvaluator:
    """Register a batch evaluator.

    The function takes one ``EvaluatorRequest`` and returns ``list[EvaluatorResponse]``.
    Read options from ``req.options``. A second parameter raises ``TypeError`` when defined.
    """
    return define_batch_evaluator(
        self._registry,
        name=name,
        display_name=display_name,
        definition=definition,
        fn=fn,
        is_billed=is_billed,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_dynamic_action_provider(name, fn, *, description=None, cache_ttl_millis=None, metadata=None)

Register a Dynamic Action Provider (DAP).

Source code in packages/genkit/src/genkit/_ai/_aio.py
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
def define_dynamic_action_provider(
    self,
    name: str,
    fn: DapFn,
    *,
    description: str | None = None,
    cache_ttl_millis: int | None = None,
    metadata: dict[str, Any] | None = None,
) -> DynamicActionProvider:
    """Register a Dynamic Action Provider (DAP)."""
    return define_dap_block(
        self._registry,
        name,
        fn,
        description=description,
        cache_ttl_millis=cache_ttl_millis,
        metadata=metadata,
    )

define_embedder(name, fn, *, info=None, metadata=None, description=None, config_schema=None)

define_embedder(
    name: str,
    fn: EmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> Embedder
define_embedder(
    name: str,
    fn: CtxFirstEmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> Embedder

Register a custom embedder action.

The options class comes from config_schema or the fn's EmbedRequest[Cfg] annotation; given both, they must be the same class.

Source code in packages/genkit/src/genkit/_ai/_aio.py
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
def define_embedder(
    self,
    name: str,
    fn: EmbedderFn | CtxFirstEmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
) -> Embedder:
    """Register a custom embedder action.

    The options class comes from ``config_schema`` or the fn's
    ``EmbedRequest[Cfg]`` annotation; given both, they must be the same class.
    """
    return define_embedder(self._registry, name, fn, info, metadata, description, config_schema=config_schema)

define_evaluator(name, fn, *, display_name, definition, is_billed=False, config_schema=None, metadata=None, description=None)

Register an evaluator that scores one dataset row at a time.

Example
# 1. Score whether the answer mentions the expected dish
async def mentions_dish(row: BaseDataPoint, options: object | None) -> EvaluatorResponse:
    hit = row.reference.lower() in str(row.output).lower()
    return EvaluatorResponse(test_case_id=row.test_case_id or '', evaluation=[Score(score=hit)])


# 2. Register it under a name
ai.define_evaluator(
    'mentions_dish',
    mentions_dish,
    display_name='Mentions dish',
    definition='Whether the answer names the expected dish.',
)

# 3. Run it over a dataset
rows = await ai.evaluate(evaluator='mentions_dish', dataset=dataset)
# => [EvaluatorResponse(test_case_id='...', evaluation=[Score(score=True)]), ...]
Source code in packages/genkit/src/genkit/_ai/_aio.py
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
def define_evaluator(
    self,
    name: str,
    fn: EvaluatorFn[Any],
    *,
    display_name: str,
    definition: str,
    is_billed: bool = False,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> Evaluator:
    """Register an evaluator that scores one dataset row at a time.

    Example:
        ```python
        # 1. Score whether the answer mentions the expected dish
        async def mentions_dish(row: BaseDataPoint, options: object | None) -> EvaluatorResponse:
            hit = row.reference.lower() in str(row.output).lower()
            return EvaluatorResponse(test_case_id=row.test_case_id or '', evaluation=[Score(score=hit)])


        # 2. Register it under a name
        ai.define_evaluator(
            'mentions_dish',
            mentions_dish,
            display_name='Mentions dish',
            definition='Whether the answer names the expected dish.',
        )

        # 3. Run it over a dataset
        rows = await ai.evaluate(evaluator='mentions_dish', dataset=dataset)
        # => [EvaluatorResponse(test_case_id='...', evaluation=[Score(score=True)]), ...]
        ```
    """
    return define_evaluator(
        self._registry,
        name=name,
        display_name=display_name,
        definition=definition,
        fn=fn,
        is_billed=is_billed,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_format(formatter)

Register a custom output format. See genkit.formats.Formatter.

Source code in packages/genkit/src/genkit/_ai/_aio.py
900
901
902
def define_format(self, formatter: Formatter) -> None:
    """Register a custom output format. See `genkit.formats.Formatter`."""
    self._registry.register_value('format', formatter.name, formatter)

define_helper(name, fn)

Register a Handlebars helper for prompt templates.

Dotprompt calls the helper as fn(params, options): params is a list of the positional arguments from the template, and options carries the named arguments in options.hash. A one-argument function such as lambda s: s.upper() raises TypeError at render time. Return a str.

Example
# 1. Register a helper that takes one positional and one named argument
def menu_item(params: list[Any], options: Any) -> str:
    dish = str(params[0])
    return dish.upper() if options.hash.get('loud') else dish


ai.define_helper('menu_item', menu_item)

# 2. Use it in a prompt template
special = ai.define_prompt(
    name='special',
    model='googleai/gemini-flash-latest',
    prompt="Describe today's special, {{menu_item dish loud=true}}, in one line.",
)

# 3. Render to check the expanded text
request = await special.render(input={'dish': 'smoked salmon tartine'})
print(request.messages[0].content[0].text)
# => Describe today's special, SMOKED SALMON TARTINE, in one line.
Source code in packages/genkit/src/genkit/_ai/_aio.py
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
def define_helper(self, name: str, fn: Callable[..., Any]) -> None:
    """Register a Handlebars helper for prompt templates.

    Dotprompt calls the helper as ``fn(params, options)``: ``params`` is a
    list of the positional arguments from the template, and ``options``
    carries the named arguments in ``options.hash``. A one-argument
    function such as ``lambda s: s.upper()`` raises ``TypeError`` at
    render time. Return a ``str``.

    Example:
        ```python
        # 1. Register a helper that takes one positional and one named argument
        def menu_item(params: list[Any], options: Any) -> str:
            dish = str(params[0])
            return dish.upper() if options.hash.get('loud') else dish


        ai.define_helper('menu_item', menu_item)

        # 2. Use it in a prompt template
        special = ai.define_prompt(
            name='special',
            model='googleai/gemini-flash-latest',
            prompt="Describe today's special, {{menu_item dish loud=true}}, in one line.",
        )

        # 3. Render to check the expanded text
        request = await special.render(input={'dish': 'smoked salmon tartine'})
        print(request.messages[0].content[0].text)
        # => Describe today's special, SMOKED SALMON TARTINE, in one line.
        ```
    """
    define_helper(self._registry, name, fn)

define_interrupt(name, *, input_schema=None, description=None)

Register an interrupt tool that always pauses for user input.

Parameters:

Name Type Description Default
name str

Tool name

required
input_schema type[pydantic.BaseModel] | dict[str, object] | None

Optional input schema (Pydantic model or JSON schema dict)

None
description str | None

Tool description

None

Returns:

Type Description
genkit._core._tool.Tool[typing.Any, typing.NoReturn]

The registered interrupt tool. Awaiting it directly raises Interrupt.

Example

ask_user = ai.define_interrupt( name='ask_user', input_schema=Question, description='Ask the user a question', )

Source code in packages/genkit/src/genkit/_ai/_aio.py
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
def define_interrupt(
    self,
    name: str,
    *,
    input_schema: type[BaseModel] | dict[str, object] | None = None,
    description: str | None = None,
) -> Tool[Any, NoReturn]:
    """Register an interrupt tool that always pauses for user input.

    Args:
        name: Tool name
        input_schema: Optional input schema (Pydantic model or JSON schema dict)
        description: Tool description

    Returns:
        The registered interrupt tool. Awaiting it directly raises ``Interrupt``.

    Example:
        ask_user = ai.define_interrupt(
            name='ask_user',
            input_schema=Question,
            description='Ask the user a question',
        )
    """
    return define_interrupt(
        self._registry,
        name,
        description=description,
        input_schema=input_schema,
    )

define_json_schema(name, json_schema)

Register a JSON schema for use in prompts.

Source code in packages/genkit/src/genkit/_ai/_aio.py
499
500
501
502
def define_json_schema(self, name: str, json_schema: dict[str, object]) -> dict[str, object]:
    """Register a JSON schema for use in prompts."""
    self._registry.register_schema(name, json_schema)
    return json_schema

define_middleware(cls, *, name=None, description=None)

Register a middleware class on this app's registry.

Source code in packages/genkit/src/genkit/_ai/_aio.py
645
646
647
648
649
650
651
652
653
654
655
def define_middleware(
    self,
    cls: type[MiddlewareT],
    *,
    name: str | None = None,
    description: str | None = None,
) -> type[MiddlewareT]:
    """Register a middleware class on this app's registry."""
    desc = cls._middleware_metadata(name, description=description)
    self._registry.register_value('middleware', desc.name, desc)
    return cls

define_model(name, fn, *, config_schema=None, metadata=None, info=None, description=None)

define_model(
    name: str,
    fn: ModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> Model
define_model(
    name: str,
    fn: CtxFirstModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> Model

Register a custom model action.

Source code in packages/genkit/src/genkit/_ai/_aio.py
821
822
823
824
825
826
827
828
829
830
831
832
def define_model(
    self,
    name: str,
    fn: ModelFn | CtxFirstModelFn,
    *,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None,
) -> Model:
    """Register a custom model action."""
    return define_model(self._registry, name, fn, config_schema, metadata, info, description)

define_partial(name, source)

Register a Handlebars partial template.

Source code in packages/genkit/src/genkit/_ai/_aio.py
490
491
492
def define_partial(self, name: str, source: str) -> None:
    """Register a Handlebars partial template."""
    define_partial(self._registry, name, source)

define_prompt(name=None, *, variant=None, model=None, config=None, description=None, system=None, prompt=None, messages=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, max_turns=None, return_tool_requests=None, metadata=None, tools=None, tool_choice=None, use=None, docs=None, input_schema=None, output_schema=None)

define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]

Register a prompt template.

Example

joke = ai.define_prompt(name='joke', prompt='Tell a joke about {{topic}}.') res = await joke(input={'topic': 'cats'}) print(res.text)

=> Why did the cat sit on the keyboard? To keep an eye on the mouse.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
def define_prompt(
    self,
    name: str | None = None,
    *,
    variant: str | None = None,
    model: str | ModelRef[Any] | Action | None = None,
    config: Mapping[str, Any] | BaseModel | ModelConfigDict | None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type | dict[str, object] | str | None = None,
    output_schema: type | dict[str, object] | str | None = None,
) -> Prompt[Any, Any]:
    """Register a prompt template.

    Example:
        joke = ai.define_prompt(name='joke', prompt='Tell a joke about {{topic}}.')
        res = await joke(input={'topic': 'cats'})
        print(res.text)
        # => Why did the cat sit on the keyboard? To keep an eye on the mouse.
    """
    executable_prompt = Prompt(
        self,
        variant=variant,
        model=model,
        config=config,
        description=description,
        input_schema=input_schema,
        system=system,
        prompt=prompt,
        messages=messages,
        output_format=output_format,
        output_content_type=output_content_type,
        output_instructions=output_instructions,
        output_schema=output_schema,
        output_constrained=output_constrained,
        max_turns=max_turns,
        return_tool_requests=return_tool_requests,
        metadata=metadata,
        tools=tools,
        tool_choice=tool_choice,
        use=use,
        docs=docs,
        name=name,
    )
    if name:
        register_prompt_actions(self._registry, executable_prompt, name, variant)
    return executable_prompt

define_schema(name, schema)

Register a Pydantic schema for use in prompts.

Source code in packages/genkit/src/genkit/_ai/_aio.py
494
495
496
497
def define_schema(self, name: str, schema: type[BaseModel]) -> type[BaseModel]:
    """Register a Pydantic schema for use in prompts."""
    define_schema(self._registry, name, schema)
    return schema

define_value(*, kind, name, value)

Store value under kind and name for later lookup_value.

Defining the same kind and name again replaces the value, so a re-run notebook cell does not fail.

Raises:

Type Description
ValueError

kind is one Genkit owns (use define_middleware, define_format, or Genkit(model=...)), or value is None.

Source code in packages/genkit/src/genkit/_ai/_aio.py
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
def define_value(self, *, kind: str, name: str, value: object) -> None:
    """Store ``value`` under ``kind`` and ``name`` for later ``lookup_value``.

    Defining the same kind and name again replaces the value, so a
    re-run notebook cell does not fail.

    Raises:
        ValueError: ``kind`` is one Genkit owns (use ``define_middleware``,
            ``define_format``, or ``Genkit(model=...)``), or ``value`` is None.
    """
    if kind in _CORE_VALUE_KINDS:
        raise ValueError(f'define_value kind {kind!r} is reserved; use {_CORE_VALUE_KINDS[kind]} instead.')
    if value is None:
        raise ValueError('define_value value must not be None; lookup_value returns None for "not defined".')
    self._registry.register_value(kind, name, value, allow_overwrite=True)

embed(*, embedder, content, metadata=None, config=None, context=None) async

embed(
    *,
    embedder: str | EmbedderRef[Any],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: None = None,
    context: dict[str, Any] | None = None
) -> list[Embedding]
embed(
    *,
    embedder: str | EmbedderRef[EmbedderRefConfigT],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: EmbedderRefConfigT | Mapping[str, Any] | None,
    context: dict[str, Any] | None = None
) -> list[Embedding]

Generate vector embeddings for a single document or string.

config is layered over the EmbedderRef's version and config (the call wins per key) and reaches the embedder as request.options. A config object must be the embedder's options class. An embedder name that isn't registered raises GenkitError with NOT_FOUND.

metadata is attached to a string content. A Document already carries its own metadata, so passing both raises TypeError.

context reaches the embedder as ctx.context, as on generate. Omitted, the embedder sees the enclosing action's context. The GoogleAI, VertexAI and OpenAI embedders read a per-request key from context={'secrets': {'api_key': ...}}, so the tenant, not the plugin key, is billed. Ollama and Bedrock embedders always use the plugin's client.

Example

from genkit_google_genai import GoogleAI

embeddings = await ai.embed( embedder=GoogleAI.embedder('gemini-embedding-001'), content='Hello world', ) vector = embeddings[0].embedding

Source code in packages/genkit/src/genkit/_ai/_aio.py
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
async def embed(
    self,
    *,
    embedder: str | EmbedderRef[Any],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: BaseModel | Mapping[str, Any] | None = None,
    context: dict[str, Any] | None = None,
) -> list[Embedding]:
    """Generate vector embeddings for a single document or string.

    ``config`` is layered over the ``EmbedderRef``'s version and config
    (the call wins per key) and reaches the embedder as
    ``request.options``. A config object must be the embedder's options
    class. An embedder name that isn't registered raises ``GenkitError``
    with ``NOT_FOUND``.

    ``metadata`` is attached to a string ``content``. A ``Document``
    already carries its own metadata, so passing both raises ``TypeError``.

    ``context`` reaches the embedder as ``ctx.context``, as on
    ``generate``. Omitted, the embedder sees the enclosing action's
    context. The GoogleAI, VertexAI and OpenAI embedders read a
    per-request key from ``context={'secrets': {'api_key': ...}}``, so
    the tenant, not the plugin key, is billed. Ollama and Bedrock
    embedders always use the plugin's client.

    Example:
        from genkit_google_genai import GoogleAI

        embeddings = await ai.embed(
            embedder=GoogleAI.embedder('gemini-embedding-001'),
            content='Hello world',
        )
        vector = embeddings[0].embedding
    """
    if metadata is not None and isinstance(content, Document):
        raise TypeError(_DOCUMENT_METADATA_CONFLICT)

    embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

    documents = [Document.from_text(content, metadata)] if isinstance(content, str) else [content]

    response = (
        await embed_action.run(
            EmbedRequest(
                input=documents,
                options=final_options,
            ),
            context=context,
        )
    ).response
    return response.embeddings

embed_many(*, embedder, content, metadata=None, config=None, context=None) async

embed_many(
    *,
    embedder: str | EmbedderRef[Any],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: None = None,
    context: dict[str, Any] | None = None
) -> list[Embedding]
embed_many(
    *,
    embedder: str | EmbedderRef[EmbedderRefConfigT],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: EmbedderRefConfigT | Mapping[str, Any] | None,
    context: dict[str, Any] | None = None
) -> list[Embedding]

Generate vector embeddings for multiple documents in a single batch call.

content is any sequence (list, tuple, ...) of strings or Documents; one embedding comes back per item, in order. A bare str raises TypeError; use embed for one item. config, metadata and context work the same as on embed.

Source code in packages/genkit/src/genkit/_ai/_aio.py
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
async def embed_many(
    self,
    *,
    embedder: str | EmbedderRef[Any],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: BaseModel | Mapping[str, Any] | None = None,
    context: dict[str, Any] | None = None,
) -> list[Embedding]:
    """Generate vector embeddings for multiple documents in a single batch call.

    ``content`` is any sequence (list, tuple, ...) of strings or
    ``Document``s; one embedding comes back per item, in order. A bare
    ``str`` raises ``TypeError``; use ``embed`` for one item.
    ``config``, ``metadata`` and ``context`` work the same as on ``embed``.
    """
    if isinstance(content, str):
        raise TypeError('embed_many() takes a sequence of strings or Documents, not a str; use embed() for one.')
    if metadata is not None and any(isinstance(item, Document) for item in content):
        raise TypeError(_DOCUMENT_METADATA_CONFLICT)

    # Convert strings to Documents if needed
    documents: list[Document] = [
        Document.from_text(item, metadata) if isinstance(item, str) else item for item in content
    ]

    embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

    response = (
        await embed_action.run(EmbedRequest(input=documents, options=final_options), context=context)  # type: ignore[arg-type]
    ).response
    return response.embeddings

evaluate(*, evaluator, dataset, config=None, eval_run_id=None) async

Evaluate a dataset using the specified evaluator.

Returns a list of rows. A per-row evaluator gives one row per datapoint, in dataset order. A batch evaluator gives the rows its function returned, as returned. Each row's evaluation is a list of scores.

config is merged over the EvaluatorRef's config (the call wins per key) and handed to the evaluator as its second argument. When neither sets anything, the evaluator gets None. An evaluator name that isn't registered raises GenkitError with NOT_FOUND.

Example

from genkit.evaluator import BaseDataPoint

results = await ai.evaluate( evaluator='my_eval', dataset=[BaseDataPoint(input='What is 2+2?', output='4')], ) for row in results: for score in row.evaluation: print(row.test_case_id, score.score)

Source code in packages/genkit/src/genkit/_ai/_aio.py
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
async def evaluate(
    self,
    *,
    evaluator: str | EvaluatorRef,
    dataset: list[BaseDataPoint],
    config: dict[str, object] | None = None,
    eval_run_id: str | None = None,
) -> list[EvaluatorResponse]:
    """Evaluate a dataset using the specified evaluator.

    Returns a list of rows. A per-row evaluator gives one row per
    datapoint, in dataset order. A batch evaluator gives the rows its
    function returned, as returned. Each row's ``evaluation`` is a list of
    scores.

    ``config`` is merged over the ``EvaluatorRef``'s config (the call
    wins per key) and handed to the evaluator as its second argument. When
    neither sets anything, the evaluator gets ``None``. An evaluator name
    that isn't registered raises ``GenkitError`` with ``NOT_FOUND``.

    Example:
        from genkit.evaluator import BaseDataPoint

        results = await ai.evaluate(
            evaluator='my_eval',
            dataset=[BaseDataPoint(input='What is 2+2?', output='4')],
        )
        for row in results:
            for score in row.evaluation:
                print(row.test_case_id, score.score)
    """
    warn_evaluators_deprecated()
    if isinstance(evaluator, EvaluatorRef):
        evaluator_name = evaluator.name
        ref_config = evaluator.config
    else:
        evaluator_name = evaluator
        ref_config = None

    # same rule as _embedder_options: None when nothing was set, matching
    # what the CLI / Dev UI send, so `options is None` is the one check.
    final_options: dict[str, object] | None = None
    if ref_config is not None or config is not None:
        final_options = {**(ref_config or {}), **(config or {})}

    eval_action = await self._registry.resolve_evaluator(evaluator_name)
    if eval_action is None:
        raise GenkitError(
            status='NOT_FOUND',
            message=f"Evaluator '{evaluator_name}' not found.",
            reason=ErrorReason.ACTION_NOT_FOUND,
        )

    if not eval_run_id:
        eval_run_id = str(uuid.uuid4())

    with suppress_evaluator_warning():
        response = await eval_action.run(
            EvaluatorRequest(
                dataset=dataset,
                options=final_options,
                eval_run_id=eval_run_id,
            ),
        )
    return response.response.root

flow(name=None, *, description=None)

flow(
    name: str | None = None,
    *,
    description: str | None = None
) -> _FlowDecorator
flow(
    func: Callable[
        [FlowContext[ChunkT], object], Awaitable[OutputT]
    ],
) -> Flow[Any, OutputT, ChunkT]
flow(
    func: DefaultInputCtxFn[
        FlowContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedFlow[InputT, OutputT, ChunkT]
flow(
    func: Callable[
        [InputT, FlowContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Flow[InputT, OutputT, ChunkT]
flow(
    func: CtxDefaultInputFn[
        FlowContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedFlow[InputT, OutputT, ChunkT]
flow(
    func: Callable[
        [FlowContext[ChunkT], InputT], Awaitable[OutputT]
    ],
) -> Flow[InputT, OutputT, ChunkT]
flow(
    func: Callable[[object], Awaitable[OutputT]],
) -> Flow[Any, OutputT]
flow(
    func: Callable[
        [FlowContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Flow[None, OutputT, ChunkT]
flow(
    func: DefaultInputFn[InputT, OutputT],
) -> DefaultedFlow[InputT, OutputT]
flow(
    func: Callable[[InputT], Awaitable[OutputT]],
) -> Flow[InputT, OutputT]
flow(
    func: Callable[[], Awaitable[OutputT]],
) -> Flow[None, OutputT]

Decorator to register an async function as a flow.

Can be used bare (@ai.flow) or with arguments (@ai.flow(), @ai.flow('custom_name', description='...')).

A flow takes at most one input. To read the request context or stream chunks, add a parameter annotated FlowContext, in any position. Any other second parameter raises TypeError when the flow is defined.

Parameters:

Name Type Description Default
name str | collections.abc.Callable[..., collections.abc.Awaitable[typing.Any]] | None

Optional name for the flow (or the function itself when used as @ai.flow). Defaults to the function name.

None
description str | None

Optional description for the flow.

None
Example

from genkit import FlowContext, Genkit from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

@ai.flow async def my_flow(prompt: str) -> str: res = await ai.generate(prompt=prompt) return res.text

@ai.flow async def streaming_flow(x: int, ctx: FlowContext[str]) -> str: ctx.send_chunk('progress') return 'done'

Source code in packages/genkit/src/genkit/_ai/_aio.py
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
def flow(
    self,
    name: str | Callable[..., Awaitable[Any]] | None = None,
    *,
    description: str | None = None,
) -> _FlowDecorator | Flow[Any, Any, Any]:
    """Decorator to register an async function as a flow.

    Can be used bare (``@ai.flow``) or with arguments (``@ai.flow()``,
    ``@ai.flow('custom_name', description='...')``).

    A flow takes at most one input. To read the request context or stream
    chunks, add a parameter annotated ``FlowContext``, in any position.
    Any other second parameter raises ``TypeError`` when the flow is defined.

    Args:
        name: Optional name for the flow (or the function itself when used
            as ``@ai.flow``). Defaults to the function name.
        description: Optional description for the flow.

    Example:
        from genkit import FlowContext, Genkit
        from genkit_google_genai import GoogleAI

        ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

        @ai.flow
        async def my_flow(prompt: str) -> str:
            res = await ai.generate(prompt=prompt)
            return res.text

        @ai.flow
        async def streaming_flow(x: int, ctx: FlowContext[str]) -> str:
            ctx.send_chunk('progress')
            return 'done'
    """
    if not isinstance(name, str) and name is not None:
        return _FlowDecorator(self._registry, None, description)(name)
    return _FlowDecorator(self._registry, name, description)

generate(*, model=None, prompt=None, system=None, messages=None, tools=None, return_tool_requests=None, tool_choice=None, resume_respond=None, resume_restart=None, resume_metadata=None, config=None, max_turns=None, context=None, output_schema=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, use=None, docs=None) async

generate(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]

Generate text or structured data using a language model.

model accepts a typed ModelRef from a plugin constructor (recommended, e.g. GoogleAI.gemini('gemini-flash-latest'), which takes the bare model ID, stamps the 'googleai/' namespace prefix, and type-checks config), a plugin-prefixed string ('googleai/gemini-flash-latest'), a registered model Action, or None to use the default model= passed to Genkit(...). When passing a plain str for a plugin model, the <plugin>/ prefix (such as 'googleai/' or 'vertexai/') is required; passing an unprefixed string raises GenkitError with NOT_FOUND. Any model ID served by the provider (including newly released models) is resolved lazily on demand at call time without needing pre-registration or SDK updates.

tools is typed as Sequence rather than list because Sequence is covariant: list[Tool] or list[str] are both assignable to Sequence[str | Tool], but not to list[str | Tool].

Example

from pydantic import BaseModel

class Weather(BaseModel): city: str forecast: str

res = await ai.generate( prompt='Weather in Paris?', tools=[current_weather], output_schema=Weather, ) if res.output: print(res.output)

=> city='Paris' forecast='Sunny'

max_turns caps tool rounds (default 50, matching Go): the model may call tools that many times and then reply, so a run uses at most max_turns + 1 model calls. Past the cap the response is ABORTED with reason MAX_TURNS_EXCEEDED.

prompt and system strings are sent exactly as written. Braces are content (JSON, code, or another template), not Handlebars. Partials ({{> persona}}), define_helper helpers and {{media url=...}} only render in define_prompt or a .prompt file; otherwise build the text or Part.from_media(...) yourself.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
async def generate(
    self,
    *,
    model: str | ModelRef[Any] | Action | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[Any] | dict[str, Any] | str | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> ModelResponse[Any]:
    """Generate text or structured data using a language model.

    ``model`` accepts a typed ``ModelRef`` from a plugin constructor
    (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``,
    which takes the bare model ID, stamps the ``'googleai/'`` namespace
    prefix, and type-checks ``config``), a plugin-prefixed string
    (``'googleai/gemini-flash-latest'``), a registered model ``Action``, or
    ``None`` to use the default ``model=`` passed to ``Genkit(...)``. When
    passing a plain ``str`` for a plugin model, the ``<plugin>/`` prefix
    (such as ``'googleai/'`` or ``'vertexai/'``) is required; passing an
    unprefixed string raises ``GenkitError`` with ``NOT_FOUND``. Any model
    ID served by the provider (including newly released models) is resolved
    lazily on demand at call time without needing pre-registration or SDK
    updates.

    ``tools`` is typed as ``Sequence`` rather than ``list`` because ``Sequence``
    is covariant: ``list[Tool]`` or ``list[str]`` are both assignable to
    ``Sequence[str | Tool]``, but not to ``list[str | Tool]``.

    Example:
        from pydantic import BaseModel

        class Weather(BaseModel):
            city: str
            forecast: str

        res = await ai.generate(
            prompt='Weather in Paris?',
            tools=[current_weather],
            output_schema=Weather,
        )
        if res.output:
            print(res.output)
        # => city='Paris' forecast='Sunny'

    ``max_turns`` caps tool rounds (default 50, matching Go): the model may
    call tools that many times and then reply, so a run uses at most
    ``max_turns + 1`` model calls. Past the cap the response is ``ABORTED``
    with reason ``MAX_TURNS_EXCEEDED``.

    ``prompt`` and ``system`` strings are sent exactly as written. Braces
    are content (JSON, code, or another template), not Handlebars.
    Partials (``{{> persona}}``), ``define_helper`` helpers and
    ``{{media url=...}}`` only render in ``define_prompt`` or a ``.prompt``
    file; otherwise build the text or ``Part.from_media(...)`` yourself.
    """
    return await self._generate(
        model=model,
        prompt=prompt,
        system=system,
        messages=messages,
        tools=tools,
        return_tool_requests=return_tool_requests,
        tool_choice=tool_choice,
        resume_respond=resume_respond,
        resume_restart=resume_restart,
        resume_metadata=resume_metadata,
        config=config,
        max_turns=max_turns,
        context=context,
        output_schema=output_schema,
        output_format=output_format,
        output_content_type=output_content_type,
        output_instructions=output_instructions,
        output_constrained=output_constrained,
        use=use,
        docs=docs,
    )

generate_operation(*, model=None, prompt=None, system=None, messages=None, config=None, context=None, use=None, docs=None) async

generate_operation(
    *,
    model: (
        ModelRef[Any] | BackgroundModel | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: None = None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]
generate_operation(
    *,
    model: (
        ModelRef[ModelRefConfigT]
        | BackgroundModel
        | str
        | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: ModelConfigDict,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]
generate_operation(
    *,
    model: (
        ModelRef[ModelRefConfigT]
        | BackgroundModel
        | str
        | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]

Generate content using a long-running model, returning an Operation to poll.

A background start is one request that returns a job handle. There is no tool loop and no output parsing on check_operation, so tools, max_turns, and the output_* options are not accepted here.

Example

op = await ai.generate_operation( model='googleai/veo-3.1-generate-preview', prompt='A timelapse of a flower blooming.', ) while not op.done: op = await ai.check_operation(op)

Source code in packages/genkit/src/genkit/_ai/_aio.py
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
async def generate_operation(
    self,
    *,
    model: ModelRef[ModelRefConfigT] | BackgroundModel | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> Operation[ModelResponse]:
    """Generate content using a long-running model, returning an Operation to poll.

    A background start is one request that returns a job handle. There is
    no tool loop and no output parsing on ``check_operation``, so tools,
    ``max_turns``, and the ``output_*`` options are not accepted here.

    Example:
        op = await ai.generate_operation(
            model='googleai/veo-3.1-generate-preview',
            prompt='A timelapse of a flower blooming.',
        )
        while not op.done:
            op = await ai.check_operation(op)
    """
    if isinstance(model, BackgroundModel):
        # Same as its name, once we know this registry holds that object.
        model = background_model_name(model=model, registry=self._registry)
    resolved = await resolve_for_generate(
        model=model,
        config=config,
        registry=self._registry,
        message='No model specified for generate_operation.',
    )
    check_call_config(config=config, schema=resolved.config_schema, model=resolved.name)

    model_action = await self._registry.resolve_model(resolved.name)
    if not model_action:
        raise GenkitError(
            status='NOT_FOUND',
            message=f"Model '{resolved.name}' not found.",
            reason=ErrorReason.MODEL_NOT_FOUND,
        )

    if model_action.kind != ActionKind.BACKGROUND_MODEL:
        raise GenkitError(
            status='INVALID_ARGUMENT',
            message=f"Model '{model_action.name}' does not support long running operations.",
            reason=ErrorReason.UNSUPPORTED_BY_MODEL,
        )

    # Call generate with already-resolved wire name + config.
    response = await self.generate(
        model=resolved.name,
        prompt=prompt,
        system=system,
        messages=messages,
        config=resolved.config,
        context=context,
        use=use,
        docs=docs,
    )

    if response.error is not None:
        # This call is "give me the ticket." A start that already
        # failed is not that ticket — while-not-done would poll it
        # as a live job.
        err = GenkitError(
            status=response.error.status or 'INTERNAL',
            message=response.error.message,
            details=response.error.details,
            reason=response.error.reason,
        )
        mark_already_sourced(err)
        raise err
    if not response.operation:
        raise missing_operation_error(name=model_action.name)
    return as_model_operation(response.operation, name=model_action.name, status='INTERNAL')

generate_stream(*, model=None, prompt=None, system=None, messages=None, tools=None, return_tool_requests=None, tool_choice=None, resume_respond=None, resume_restart=None, resume_metadata=None, config=None, max_turns=None, context=None, output_schema=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, use=None, docs=None)

generate_stream(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]

Stream generated text, returning a ModelStreamResponse with .stream and .response.

With output_schema=Recipe, each chunk.output is a partial of that type: same attributes, any field may still be None or a prefix. Guard the field you are about to use. The finished Recipe is only (await result.response).output, and it's None when the reply isn't a Recipe.

If the model fails partway through, the async for still ends normally. The final response has finish_reason == FAILED, error set, text == '', message is None, and messages ending at the last complete turn, so it's safe to send back. The chunks you already received are the record of what was shown.

Use async with result.stream as stream: so that leaving the loop early (break, an exception, a disconnected client) closes the stream and stops the model call.

Example
# 1. Start streaming
result = ai.generate_stream(prompt='Write a haiku about rain.')

# 2. Print chunks as they arrive; the context manager closes the stream
async with result.stream as stream:
    async for chunk in stream:
        print(chunk.text, end='')
print()
# => Soft rain on the roof...

# 3. Await the final response
final = await result.response
print(final.finish_reason)
# => stop
Source code in packages/genkit/src/genkit/_ai/_aio.py
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
def generate_stream(
    self,
    *,
    model: str | ModelRef[Any] | Action | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[Any] | dict[str, Any] | str | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> ModelStreamResponse[Any]:
    """Stream generated text, returning a ModelStreamResponse with .stream and .response.

    With ``output_schema=Recipe``, each ``chunk.output`` is a partial of
    that type: same attributes, any field may still be ``None`` or a
    prefix. Guard the field you are about to use. The finished
    ``Recipe`` is only ``(await result.response).output``, and it's ``None``
    when the reply isn't a ``Recipe``.

    If the model fails partway through, the ``async for`` still ends
    normally. The final response has ``finish_reason == FAILED``,
    ``error`` set, ``text == ''``, ``message is None``, and ``messages``
    ending at the last complete turn, so it's safe to send back. The
    chunks you already received are the record of what was shown.

    Use ``async with result.stream as stream:`` so that leaving the loop
    early (``break``, an exception, a disconnected client) closes the
    stream and stops the model call.

    Example:
        ```python
        # 1. Start streaming
        result = ai.generate_stream(prompt='Write a haiku about rain.')

        # 2. Print chunks as they arrive; the context manager closes the stream
        async with result.stream as stream:
            async for chunk in stream:
                print(chunk.text, end='')
        print()
        # => Soft rain on the roof...

        # 3. Await the final response
        final = await result.response
        print(final.finish_reason)
        # => stop
        ```
    """
    check_max_turns(max_turns)
    initial_msgs: list[Message] = []
    if not isinstance(messages, str):
        initial_msgs = call_messages(system=system, messages=messages, prompt=prompt)

    async def _run_generate(
        send_chunk: Callable[[ModelResponseChunk], None],
        caller_stopped: asyncio.Event,
    ) -> ModelResponse[Any]:
        return await self._generate(
            model=model,
            prompt=prompt,
            system=system,
            messages=messages,
            tools=tools,
            return_tool_requests=return_tool_requests,
            tool_choice=tool_choice,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
            config=config,
            max_turns=max_turns,
            context=context,
            output_schema=output_schema,
            output_format=output_format,
            output_content_type=output_content_type,
            output_instructions=output_instructions,
            output_constrained=output_constrained,
            use=use,
            docs=docs,
            on_chunk=send_chunk,
            caller_stopped=caller_stopped,
        )

    stream, task = start_generate_stream(initial_messages=initial_msgs, run=_run_generate)
    return ModelStreamResponse[Any](stream=stream, response=task)

lookup_model(name) async

Return the model action registered under name, or None.

Plugin models that haven't been used yet are resolved through the plugin, so 'googleai/gemini-flash-latest' works before any generate call. Background models aren't included; they run through generate_operation.

Source code in packages/genkit/src/genkit/_ai/_aio.py
904
905
906
907
908
909
910
911
912
913
async def lookup_model(self, name: str) -> Action[ModelRequest, ModelResponse, ModelResponseChunk] | None:
    """Return the model action registered under ``name``, or None.

    Plugin models that haven't been used yet are resolved through the
    plugin, so ``'googleai/gemini-flash-latest'`` works before any
    generate call. Background models aren't included; they run through
    ``generate_operation``.
    """
    action = await self._registry.resolve_action(ActionKind.MODEL, name)
    return cast(Action[ModelRequest, ModelResponse, ModelResponseChunk], action) if action is not None else None

lookup_tool(name) async

Return the tool registered under name, or None.

The same handle @ai.tool returns, so a tool defined in one module can be called or passed in tools=[...] from another without importing it.

Example
# 1. Define a tool in one module
@ai.tool
async def menu_price(dish: str) -> float:
    return 14.5


# 2. Find it by name somewhere else
price_tool = await ai.lookup_tool('menu_price')
response = await ai.generate(prompt='How much is the ramen?', tools=[price_tool])
print(response.text)
# => The ramen is $14.50.
Source code in packages/genkit/src/genkit/_ai/_aio.py
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
async def lookup_tool(self, name: str) -> Tool | None:
    """Return the tool registered under ``name``, or None.

    The same handle ``@ai.tool`` returns, so a tool defined in one module
    can be called or passed in ``tools=[...]`` from another without
    importing it.

    Example:
        ```python
        # 1. Define a tool in one module
        @ai.tool
        async def menu_price(dish: str) -> float:
            return 14.5


        # 2. Find it by name somewhere else
        price_tool = await ai.lookup_tool('menu_price')
        response = await ai.generate(prompt='How much is the ramen?', tools=[price_tool])
        print(response.text)
        # => The ramen is $14.50.
        ```
    """
    action = await self._registry.resolve_action(ActionKind.TOOL, name)
    if action is None:
        return None
    return Tool.from_action(action)

lookup_value(*, kind, name)

Return the value defined under kind and name, or None.

Source code in packages/genkit/src/genkit/_ai/_aio.py
942
943
944
def lookup_value(self, *, kind: str, name: str) -> object | None:
    """Return the value defined under ``kind`` and ``name``, or None."""
    return self._registry.lookup_value(kind, name)

middleware(cls=None, *, name=None, description=None)

middleware(cls: type[MiddlewareT]) -> type[MiddlewareT]
middleware(
    *,
    name: str | None = None,
    description: str | None = None
) -> Callable[[type[MiddlewareT]], type[MiddlewareT]]

Decorator that registers a custom middleware on this app's registry.

Source code in packages/genkit/src/genkit/_ai/_aio.py
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def middleware(
    self,
    cls: type[MiddlewareT] | None = None,
    *,
    name: str | None = None,
    description: str | None = None,
) -> type[MiddlewareT] | Callable[[type[MiddlewareT]], type[MiddlewareT]]:
    """Decorator that registers a custom middleware on this app's registry."""

    def decorator(target: type[MiddlewareT]) -> type[MiddlewareT]:
        return self.define_middleware(target, name=name, description=description)

    if cls is not None:
        return decorator(cls)
    return decorator

prompt(name, *, variant=None, input_schema=None, output_schema=None)

prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: None = None,
    output_schema: None = None
) -> Prompt[Any, Any]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT],
    output_schema: None = None
) -> Prompt[InputT, Any]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]

Look up a prompt by name and optional variant.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
def prompt(
    self,
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT] | None = None,
    output_schema: type[OutputT] | None = None,
) -> Prompt[InputT, OutputT] | Prompt[Any, Any]:
    """Look up a prompt by name and optional variant."""
    return Prompt(
        self,
        name=name,
        variant=variant,
        input_schema=input_schema,
        output_schema=output_schema,
    )

run(name, fn, *, metadata=None) async

Run a function as a discrete traced step within a flow.

fn takes no arguments and returns an awaitable, so async def functions, lambda: fetch(i), and callables with an async def __call__ all work. Same shape as JS ai.run('step', fn).

Example
# 1. Each fan-out step gets its own span in the trace
menus = await asyncio.gather(*[ai.run(f'fetch-{i}', lambda i=i: fetch_menu(i)) for i in range(3)])

# 2. Keyword form still works
total = await ai.run(name='sum', fn=lambda: sum_prices(menus))
Source code in packages/genkit/src/genkit/_ai/_aio.py
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
async def run(
    self,
    name: str,
    fn: Callable[[], Awaitable[T]],
    *,
    metadata: dict[str, Any] | None = None,
) -> T:
    """Run a function as a discrete traced step within a flow.

    ``fn`` takes no arguments and returns an awaitable, so ``async def``
    functions, ``lambda: fetch(i)``, and callables with an ``async def
    __call__`` all work. Same shape as JS ``ai.run('step', fn)``.

    Example:
        ```python
        # 1. Each fan-out step gets its own span in the trace
        menus = await asyncio.gather(*[ai.run(f'fetch-{i}', lambda i=i: fetch_menu(i)) for i in range(3)])

        # 2. Keyword form still works
        total = await ai.run(name='sum', fn=lambda: sum_prices(menus))
        ```
    """
    if not callable(fn):
        raise TypeError(f'fn must be callable, got {type(fn).__name__}')
    not_awaitable = (
        'fn must return an awaitable: pass an async def, a lambda returning a coroutine, '
        'or wrap blocking work in asyncio.to_thread'
    )

    async def body(_span: object) -> T:
        result = fn()
        if not inspect.isawaitable(result):
            # Steps stay async like tools and flows; blocking work goes
            # through asyncio.to_thread.
            raise TypeError(not_awaitable)
        return await result

    attributes = {metadata_key(k): str(v) for k, v in (metadata or {}).items()}
    return await run_in_new_span(name, body, action_type='flowStep', attributes=attributes)

run_main(coro)

Run your main coroutine and return its result, like asyncio.run.

With reflection on (GENKIT_ENV=dev, which genkit start sets, or GENKIT_REFLECTION_ENABLED=true), it keeps the process alive after main returns, so the Dev UI can keep running your flows, until Ctrl+C, SIGTERM, or the reflection server stops on its own. With reflection off, it returns as soon as main does.

If main raises while reflection is on, the error is logged and the Dev UI stays up. The error is raised once the process stops. Ctrl+C after a successful main raises KeyboardInterrupt, and SIGTERM returns main's result.

Example
from genkit import Genkit
from genkit_google_genai import GoogleAI

# 1. Initialize Genkit and define a flow
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))


@ai.flow
async def suggest_dish(cuisine: str) -> str:
    response = await ai.generate(prompt=f'Suggest one {cuisine} dish.')
    return response.text


# 2. Run a quick check from your script's entry point
async def main() -> None:
    print(await suggest_dish('Thai'))


# 3. Start it
ai.run_main(main())
# => Green curry with chicken
#    `python main.py` exits here. Under `genkit start`, the process
#    stays up for the Dev UI until you press Ctrl+C.
Source code in packages/genkit/src/genkit/_ai/_aio.py
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
def run_main(self, coro: Coroutine[Any, Any, T]) -> T:
    """Run your ``main`` coroutine and return its result, like ``asyncio.run``.

    With reflection on (``GENKIT_ENV=dev``, which ``genkit start`` sets, or
    ``GENKIT_REFLECTION_ENABLED=true``), it keeps the process alive after
    ``main`` returns, so the Dev UI can keep running your flows, until
    Ctrl+C, SIGTERM, or the reflection server stops on its own. With
    reflection off, it returns as soon as ``main`` does.

    If ``main`` raises while reflection is on, the error is logged and the
    Dev UI stays up. The error is raised once the process stops. Ctrl+C
    after a successful ``main`` raises ``KeyboardInterrupt``, and SIGTERM
    returns ``main``'s result.

    Example:
        ```python
        from genkit import Genkit
        from genkit_google_genai import GoogleAI

        # 1. Initialize Genkit and define a flow
        ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))


        @ai.flow
        async def suggest_dish(cuisine: str) -> str:
            response = await ai.generate(prompt=f'Suggest one {cuisine} dish.')
            return response.text


        # 2. Run a quick check from your script's entry point
        async def main() -> None:
            print(await suggest_dish('Thai'))


        # 3. Start it
        ai.run_main(main())
        # => Green curry with chicken
        #    `python main.py` exits here. Under `genkit start`, the process
        #    stays up for the Dev UI until you press Ctrl+C.
        ```
    """
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        pass
    else:
        # Jupyter, IPython, and async frameworks already run a loop, and
        # asyncio.run would fail with a raw RuntimeError plus an
        # unawaited-coroutine warning.
        coro.close()
        raise RuntimeError(
            'ai.run_main() cannot be called from a running event loop (Jupyter, IPython, or an async '
            'framework). Use `await main()` instead.'
        )
    if not self._reflection_config.enabled:
        return run_loop(coro)

    user_error: Exception | None = None
    stop_signal: signal.Signals | None = None

    async def reflection_runner() -> T | None:
        nonlocal user_error, stop_signal
        user_result: T | None = None
        try:
            user_result = await coro
            logger.debug('User coroutine completed successfully.')
        except Exception as e:
            # Script entrypoint failed — there's no Dev UI panel for this run,
            # so keep a headline + a debug traceback.
            logger.error('Startup failed: %s: %s', type(e).__name__, e)
            logger.debug('Startup failure details', exc_info=True)
            user_error = e

        # Block until Ctrl+C, SIGTERM, or the reflection server stops,
        # keeping the daemon reflection thread alive. The receiver is open
        # before the ready line, so a signal sent once it prints is ours,
        # not asyncio's default SIGINT handling.
        try:
            with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as sigs:
                logger.info(self._reflection_ready_message())
                async with anyio.create_task_group() as tg:

                    async def _handle_signal(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                        nonlocal stop_signal
                        async for sig in sigs:
                            stop_signal = sig
                            tg_.cancel_scope.cancel()
                            return

                    async def _handle_reflection_stopped(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                        # Poll rather than park a worker thread in Event.wait:
                        # anyio worker threads are non-daemon, so a parked one
                        # keeps the process alive after run_main returns.
                        while not self._reflection_stopped.is_set():  # noqa: ASYNC110 - threading.Event, set off-loop
                            await anyio.sleep(0.25)
                        logger.warning('Reflection server stopped; returning from run_main.')
                        tg_.cancel_scope.cancel()

                    tg.start_soon(_handle_signal, tg)
                    tg.start_soon(_handle_reflection_stopped, tg)
                    await anyio.sleep_forever()
        except anyio.get_cancelled_exc_class():
            pass

        logger.debug('Reflection server stopped.')
        return user_result

    # Decide out here, after the loop has shut down cleanly, so neither the
    # coroutine's error nor KeyboardInterrupt is raised during asyncio shutdown.
    try:
        result = anyio.run(reflection_runner)
    except KeyboardInterrupt:
        # Ctrl+C before the receiver opened (main still running).
        if user_error is None:
            raise
        raise user_error from None
    if user_error is not None:
        raise user_error
    if stop_signal == signal.SIGINT:
        raise KeyboardInterrupt
    # main returned normally (user_error is None), so result holds its value.
    return cast(T, result)

tool(name=None, *, description=None, input_schema=None)

tool(
    name: str | None = None,
    *,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> _ToolDecorator
tool(
    func: Callable[
        [ToolContext[ChunkT], object], Awaitable[OutputT]
    ],
) -> Tool[Any, OutputT, ChunkT]
tool(
    func: DefaultInputCtxFn[
        ToolContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedTool[InputT, OutputT, ChunkT]
tool(
    func: Callable[
        [InputT, ToolContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Tool[InputT, OutputT, ChunkT]
tool(
    func: CtxDefaultInputFn[
        ToolContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedTool[InputT, OutputT, ChunkT]
tool(
    func: Callable[
        [ToolContext[ChunkT], InputT], Awaitable[OutputT]
    ],
) -> Tool[InputT, OutputT, ChunkT]
tool(
    func: Callable[[object], Awaitable[OutputT]],
) -> Tool[Any, OutputT]
tool(
    func: Callable[
        [ToolContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Tool[None, OutputT, ChunkT]
tool(
    func: DefaultInputFn[InputT, OutputT],
) -> DefaultedTool[InputT, OutputT]
tool(
    func: Callable[[InputT], Awaitable[OutputT]],
) -> Tool[InputT, OutputT]
tool(
    func: Callable[[], Awaitable[OutputT]],
) -> Tool[None, OutputT]

Decorator to register a function as a tool.

Can be used bare (@ai.tool) or with arguments (@ai.tool(), @ai.tool('custom_name', description='...')).

The return annotation is what the model binds as outputSchema. Awaiting the tool directly returns what the function returned.

A tool takes at most one input, and that input's type is the schema the model fills in. For several fields, use one Pydantic model. To read the request context or interrupt, add a parameter annotated ToolContext, in any position. Any other second parameter raises TypeError when the tool is defined.

Example

@ai.tool async def current_weather(city: str) -> str: return f'Sunny in {city}'

class Forecast(BaseModel): city: str days: int = 3

@ai.tool async def forecast(input: Forecast, ctx: ToolContext) -> str: user = ctx.context.get('user_id') return f'{input.days}-day forecast for {input.city} ({user})'

res = await ai.generate(prompt='Weather in Paris?', tools=['current_weather', 'forecast'])

Source code in packages/genkit/src/genkit/_ai/_aio.py
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
def tool(
    self,
    name: str | Callable[..., Awaitable[Any]] | None = None,
    *,
    description: str | None = None,
    input_schema: type[BaseModel] | dict[str, object] | None = None,
) -> _ToolDecorator | Tool[Any, Any, Any]:
    """Decorator to register a function as a tool.

    Can be used bare (``@ai.tool``) or with arguments (``@ai.tool()``,
    ``@ai.tool('custom_name', description='...')``).

    The return annotation is what the model binds as ``outputSchema``.
    Awaiting the tool directly returns what the function returned.

    A tool takes at most one input, and that input's type is the schema the
    model fills in. For several fields, use one Pydantic model. To read the
    request context or interrupt, add a parameter annotated
    ``ToolContext``, in any position. Any other second parameter raises
    ``TypeError`` when the tool is defined.

    Example:
        @ai.tool
        async def current_weather(city: str) -> str:
            return f'Sunny in {city}'

        class Forecast(BaseModel):
            city: str
            days: int = 3

        @ai.tool
        async def forecast(input: Forecast, ctx: ToolContext) -> str:
            user = ctx.context.get('user_id')
            return f'{input.days}-day forecast for {input.city} ({user})'

        res = await ai.generate(prompt='Weather in Paris?', tools=['current_weather', 'forecast'])
    """
    if not isinstance(name, str) and name is not None:
        return _ToolDecorator(self._registry, None, description, input_schema)(name)
    return _ToolDecorator(self._registry, name, description, input_schema)

GenkitError

Bases: Exception

Base error class for Genkit errors.

Source code in packages/genkit/src/genkit/_core/_error.py
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
class GenkitError(Exception):
    """Base error class for Genkit errors."""

    def __init__(
        self,
        *,
        message: str,
        status: StatusName | None = None,
        cause: BaseException | None = None,
        details: Any = None,  # noqa: ANN401
        reason: ErrorReason | None = None,
        source: str | None = None,
        retry_after_ms: float | None = None,
    ) -> None:
        """Initialize a GenkitError.

        Args:
            message: The error message.
            status: The status name for this error.
            cause: The underlying exception; set as ``__cause__``.
            details: Optional detail information.
            reason: Extra why when we classified the failure.
            source: Optional prefix for ``str(err)``.
            retry_after_ms: How long the provider asked callers to wait before retrying.
        """
        temp_status: StatusName
        if status:
            temp_status = status
        elif isinstance(cause, GenkitError):
            temp_status = cause.status
        else:
            temp_status = 'INTERNAL'
        self.status: StatusName = temp_status

        # When this error wraps another (the common shape — the action runtime
        # catches the underlying failure and re-raises as ``GenkitError(...,
        # cause=original)``), surface the cause in the default string form so
        # downstream consumers (logs, model-facing tool error messages, the Dev
        # UI) see the real reason instead of the bare wrapper text.
        source_prefix = f'{source}: ' if source else ''
        if isinstance(cause, ValidationError):
            formatted = format_validation_error(cause)
            cause_suffix = f': {formatted}' if formatted else ''
        else:
            # Skip a cause whose text is empty or already in the message, so a
            # bare TimeoutError() adds no dangling ': ' and nothing repeats.
            # Also skip one whose own .message is ours: provider_error takes a
            # google-genai APIError's message, and str() of that APIError is
            # the same message again inside a dict repr.
            cause_text = str(cause) if cause is not None else ''
            repeats = cause_text in message or getattr(cause, 'message', None) == message
            cause_suffix = f': {cause_text}' if cause_text and not repeats else ''
        super().__init__(f'{source_prefix}{self.status}: {message}{cause_suffix}')
        self.message: str = message

        if not details:
            details = {}
        if reason is not None:
            details = dict(details)
            details['reason'] = reason.value
        if isinstance(cause, ValidationError) and 'errors' not in details:
            details = dict(details)
            details['errors'] = validation_error_details(cause)

        self.details: Any = details
        if cause is not None:
            self.__cause__ = cause
        # Only the cause passed as ``cause=``. ``raise ... from e`` also sets
        # ``__cause__``, but finish-message redaction and the Dev UI message
        # key off what the raiser chose to attach.
        self._cause: BaseException | None = cause
        self.retry_after_ms: float | None = retry_after_ms
        # Plugin errors built from a provider response keep their status
        # in-process (Retry, Fallback) but serve as a crash at the HTTP
        # boundary so a dead server key is not a 401 to the end caller.
        self._provider_sourced: bool = False
        # The served action's own input/init check is the caller's request,
        # so it keeps a 4xx. A plugin "bad role" inside the flow does not.
        self._request_sourced: bool = False

    @property
    def reason(self) -> ErrorReason | None:
        return error_reason(self.details)

__init__(*, message, status=None, cause=None, details=None, reason=None, source=None, retry_after_ms=None)

Initialize a GenkitError.

Parameters:

Name Type Description Default
message str

The error message.

required
status genkit._core._error.StatusName | None

The status name for this error.

None
cause BaseException | None

The underlying exception; set as __cause__.

None
details typing.Any

Optional detail information.

None
reason genkit._core._error.ErrorReason | None

Extra why when we classified the failure.

None
source str | None

Optional prefix for str(err).

None
retry_after_ms float | None

How long the provider asked callers to wait before retrying.

None
Source code in packages/genkit/src/genkit/_core/_error.py
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
def __init__(
    self,
    *,
    message: str,
    status: StatusName | None = None,
    cause: BaseException | None = None,
    details: Any = None,  # noqa: ANN401
    reason: ErrorReason | None = None,
    source: str | None = None,
    retry_after_ms: float | None = None,
) -> None:
    """Initialize a GenkitError.

    Args:
        message: The error message.
        status: The status name for this error.
        cause: The underlying exception; set as ``__cause__``.
        details: Optional detail information.
        reason: Extra why when we classified the failure.
        source: Optional prefix for ``str(err)``.
        retry_after_ms: How long the provider asked callers to wait before retrying.
    """
    temp_status: StatusName
    if status:
        temp_status = status
    elif isinstance(cause, GenkitError):
        temp_status = cause.status
    else:
        temp_status = 'INTERNAL'
    self.status: StatusName = temp_status

    # When this error wraps another (the common shape — the action runtime
    # catches the underlying failure and re-raises as ``GenkitError(...,
    # cause=original)``), surface the cause in the default string form so
    # downstream consumers (logs, model-facing tool error messages, the Dev
    # UI) see the real reason instead of the bare wrapper text.
    source_prefix = f'{source}: ' if source else ''
    if isinstance(cause, ValidationError):
        formatted = format_validation_error(cause)
        cause_suffix = f': {formatted}' if formatted else ''
    else:
        # Skip a cause whose text is empty or already in the message, so a
        # bare TimeoutError() adds no dangling ': ' and nothing repeats.
        # Also skip one whose own .message is ours: provider_error takes a
        # google-genai APIError's message, and str() of that APIError is
        # the same message again inside a dict repr.
        cause_text = str(cause) if cause is not None else ''
        repeats = cause_text in message or getattr(cause, 'message', None) == message
        cause_suffix = f': {cause_text}' if cause_text and not repeats else ''
    super().__init__(f'{source_prefix}{self.status}: {message}{cause_suffix}')
    self.message: str = message

    if not details:
        details = {}
    if reason is not None:
        details = dict(details)
        details['reason'] = reason.value
    if isinstance(cause, ValidationError) and 'errors' not in details:
        details = dict(details)
        details['errors'] = validation_error_details(cause)

    self.details: Any = details
    if cause is not None:
        self.__cause__ = cause
    # Only the cause passed as ``cause=``. ``raise ... from e`` also sets
    # ``__cause__``, but finish-message redaction and the Dev UI message
    # key off what the raiser chose to attach.
    self._cause: BaseException | None = cause
    self.retry_after_ms: float | None = retry_after_ms
    # Plugin errors built from a provider response keep their status
    # in-process (Retry, Fallback) but serve as a crash at the HTTP
    # boundary so a dead server key is not a 401 to the end caller.
    self._provider_sourced: bool = False
    # The served action's own input/init check is the caller's request,
    # so it keeps a 4xx. A plugin "bad role" inside the flow does not.
    self._request_sourced: bool = False

GenkitLogger

Bases: typing.Protocol

The calls get_logger promises. Nothing here names the logging backend.

Each method takes an event string, optional printf-style args, and keyword fields that are recorded as structured attributes.

Source code in packages/genkit/src/genkit/_core/_logger.py
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
class GenkitLogger(Protocol):
    """The calls ``get_logger`` promises. Nothing here names the logging backend.

    Each method takes an event string, optional printf-style ``args``, and
    keyword ``fields`` that are recorded as structured attributes.
    """

    def debug(self, event: str, *args: object, **fields: object) -> None:
        """Log at DEBUG."""
        ...

    def info(self, event: str, *args: object, **fields: object) -> None:
        """Log at INFO."""
        ...

    def warning(self, event: str, *args: object, **fields: object) -> None:
        """Log at WARNING."""
        ...

    def error(self, event: str, *args: object, **fields: object) -> None:
        """Log at ERROR."""
        ...

    def exception(self, event: str, *args: object, **fields: object) -> None:
        """Log at ERROR with the active exception's traceback."""
        ...

debug(event, *args, **fields)

Log at DEBUG.

Source code in packages/genkit/src/genkit/_core/_logger.py
381
382
383
def debug(self, event: str, *args: object, **fields: object) -> None:
    """Log at DEBUG."""
    ...

error(event, *args, **fields)

Log at ERROR.

Source code in packages/genkit/src/genkit/_core/_logger.py
393
394
395
def error(self, event: str, *args: object, **fields: object) -> None:
    """Log at ERROR."""
    ...

exception(event, *args, **fields)

Log at ERROR with the active exception's traceback.

Source code in packages/genkit/src/genkit/_core/_logger.py
397
398
399
def exception(self, event: str, *args: object, **fields: object) -> None:
    """Log at ERROR with the active exception's traceback."""
    ...

info(event, *args, **fields)

Log at INFO.

Source code in packages/genkit/src/genkit/_core/_logger.py
385
386
387
def info(self, event: str, *args: object, **fields: object) -> None:
    """Log at INFO."""
    ...

warning(event, *args, **fields)

Log at WARNING.

Source code in packages/genkit/src/genkit/_core/_logger.py
389
390
391
def warning(self, event: str, *args: object, **fields: object) -> None:
    """Log at WARNING."""
    ...

Interrupt

Bases: BaseException

Pause a tool so the caller can approve, reply, or restart.

Raise Interrupt(metadata) from a tool or from tool middleware. It is a control-flow signal like asyncio.CancelledError, so it subclasses BaseException: an except Exception in tool code can't swallow it and skip the approval. Catch Interrupt by name if a tool needs to clean up, then re-raise. Raised anywhere else (a flow, an agent turn body), the action fails with GenkitError INTERNAL. In the trace the tool's own span shows as interrupted; the generate that paused on it stays green.

Source code in packages/genkit/src/genkit/_core/_error.py
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
class Interrupt(BaseException):
    """Pause a tool so the caller can approve, reply, or restart.

    Raise ``Interrupt(metadata)`` from a tool or from tool middleware.
    It is a control-flow signal like ``asyncio.CancelledError``, so it
    subclasses ``BaseException``: an ``except Exception`` in tool code can't
    swallow it and skip the approval. Catch ``Interrupt`` by name if a tool
    needs to clean up, then re-raise. Raised anywhere else (a flow, an
    agent turn body), the action fails with ``GenkitError`` INTERNAL.
    In the trace the tool's own span shows as interrupted; the generate
    that paused on it stays green.
    """

    def __init__(self, metadata: dict[str, Any] | None = None) -> None:
        # Metadata goes in args so str(interrupt) and tracebacks show it.
        if metadata is None:
            super().__init__()
        else:
            super().__init__(metadata)
        self.metadata: dict[str, Any] = {} if metadata is None else metadata

Media

Bases: genkit._core._base.GenkitModel

Model for media data.

Source code in packages/genkit/src/genkit/_core/_typing.py
764
765
766
767
768
769
770
771
class Media(GenkitModel):
    """Model for media data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    content_type: str | None = None
    url: str = Field(...)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Message

Bases: genkit._core._base.GenkitModel

A single turn in a conversation.

Source code in packages/genkit/src/genkit/_core/_model.py
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
class Message(GenkitModel):
    """A single turn in a conversation."""

    role: Role | str
    content: list[Part]
    metadata: dict[str, Any] | None = None

    def __init__(self, *args: object, **kwargs: object) -> None:
        if args:
            raise TypeError('Message takes keyword fields; use as_message to unwrap a wire message')
        super().__init__(**kwargs)

    @field_validator('content', mode='before')
    @classmethod
    def _wrap_parts(cls, v: object) -> object:
        return parts_from_inbound(v)

    @property
    def text(self) -> str:
        """All text parts concatenated into a single string."""
        return text_from_message(self)

    @property
    def media(self) -> Media | None:
        """The first media part in this message, or ``None``."""
        return next((p.media for p in self.content if p.media is not None), None)

    @property
    def reasoning(self) -> str:
        """All reasoning (thinking) parts concatenated; ``''`` when the model sent none."""
        return ''.join(p.reasoning for p in self.content if p.reasoning is not None)

    @property
    def tool_requests(self) -> list[Part]:
        """All tool request parts in this message."""
        return [p for p in self.content if p.tool_request is not None]

    @property
    def interrupts(self) -> list[Part]:
        """Tool requests marked as interrupted."""
        return [p for p in self.tool_requests if p.metadata and p.metadata.get('interrupt')]

interrupts property

Tool requests marked as interrupted.

media property

The first media part in this message, or None.

reasoning property

All reasoning (thinking) parts concatenated; '' when the model sent none.

text property

All text parts concatenated into a single string.

tool_requests property

All tool request parts in this message.

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ModelResponse

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._model.OutputT]

Model response with utilities for text extraction, output parsing, and validation.

Source code in packages/genkit/src/genkit/_core/_model.py
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
class ModelResponse(GenkitModel, Generic[OutputT]):
    """Model response with utilities for text extraction, output parsing, and validation."""

    # _message_parser and _schema_type are set by the framework after construction
    # when output format parsing or schema validation is needed.
    _message_parser: Callable[[Message], object] | None = PrivateAttr(None)
    _schema_type: type[BaseModel] | None = PrivateAttr(None)
    _failure: BoxedFailure | None = PrivateAttr(None)
    # Wire fields (must be declared for extra='forbid' to accept wire responses)
    message: Message | None = None
    error: Failure | None = None
    finish_reason: FinishReason | None = None
    finish_message: str | None = None
    latency_ms: float | None = None
    usage: GenerationUsage | None = None
    total_usage: GenerationUsage | None = None
    custom: dict[str, Any] | None = None
    raw: dict[str, Any] | None = None
    request: ModelRequest | None = None
    operation: Operation | None = None

    @model_validator(mode='before')
    @classmethod
    def _drop_candidates(cls, data: object) -> object:
        # JS responses, stored traces, session snapshots and older plugins may
        # still carry the deprecated `candidates` list. Drop it instead of
        # failing on extra='forbid'. When the top-level reply is missing, fill
        # it from candidate 0, as JS GenerateResponse does.
        if not isinstance(data, dict) or 'candidates' not in data:
            return data
        raw = cast(dict[str, Any], data)
        fields = {k: v for k, v in raw.items() if k != 'candidates'}
        candidates: object = raw['candidates']
        if fields.get('message') is not None or not isinstance(candidates, list) or not candidates:
            return fields
        candidate_list = cast(list[Any], candidates)
        first: object = next(
            (c for c in candidate_list if isinstance(c, Mapping) and cast(Mapping[str, Any], c).get('index', 0) == 0),
            candidate_list[0],
        )
        if isinstance(first, BaseModel):
            first = first.model_dump(by_alias=True, exclude_none=True)
        if not isinstance(first, Mapping):
            return fields
        candidate = cast(Mapping[str, Any], first)
        fields['message'] = candidate.get('message')
        for camel, snake in (('finishReason', 'finish_reason'), ('finishMessage', 'finish_message')):
            value = candidate.get(camel, candidate.get(snake))
            if value is not None and fields.get(camel) is None and fields.get(snake) is None:
                fields[camel] = value
        return fields

    @field_validator('message', mode='before')
    @classmethod
    def _wrap_message(cls, v: object) -> object:
        if v is None:
            return v
        return as_message(v)

    @field_validator('request', mode='before')
    @classmethod
    def _wrap_request(cls, v: object) -> object:
        if v is None:
            return v
        return as_model_request(v)

    def model_post_init(self, __context: object) -> None:
        """Initialize default usage and custom dict if not provided."""
        if self.usage is None:
            self.usage = GenerationUsage()
        if self.custom is None:
            self.custom = {}

    def _mark_invalid_output(self, message: str) -> None:
        self.error = Failure(
            status='INTERNAL',
            message=message,
            details={'reason': ErrorReason.INVALID_OUTPUT.value},
        )

    @property
    def _wants_structure(self) -> bool:
        """Whether the caller asked for a schema or a structured output format."""
        if self._schema_type is not None:
            return True
        if self.request is not None:
            if self.request.output_schema is not None:
                return True
            fmt = self.request.output_format
            if fmt and fmt != 'text':
                return True
        return False

    def _assert_valid_schema(self) -> None:
        """Mark this response as unusable structured output without throwing.

        Raw text or a wrong-shape JSON is not a Recipe. generate()
        still returns so that text stays on ``.text``; the model's finish
        reason stays intact and ``error`` records the post-processing failure.
        ``.output`` is None.
        A blocked/aborted/interrupted/other finish keeps the model's reason.
        """
        if not self._wants_structure:
            return
        if self.error is not None:
            return
        if self.finish_reason in ABNORMAL_FINISH_REASONS:
            return

        schema = self.request.output_schema if self.request is not None else None
        cut_off = self.finish_reason == FinishReason.LENGTH

        try:
            parsed = self._raw_parsed_output()
        except Exception as exc:
            if isinstance(exc, GenkitError) and (exc.message or '').startswith('Invalid output_schema'):
                raise
            preview = (self.text or '')[:200]
            if cut_off:
                self._mark_invalid_output(
                    'Model output was cut off at the token limit '
                    f'(finish_reason=length) before the JSON was complete: {preview}'
                )
            else:
                target = 'schema' if schema is not None else 'format'
                self._mark_invalid_output(f'Model output was not valid JSON for the requested {target}: {preview}')
            return

        if parsed is None:
            preview = (self.text or '')[:200]
            if cut_off:
                self._mark_invalid_output(
                    'Model output was cut off at the token limit '
                    f'(finish_reason=length) before the JSON was complete: {preview}'
                )
            else:
                self._mark_invalid_output(f'Model output was not valid for the requested format: {preview}')
            return

        if schema is not None:
            try:
                parse_schema(data=parsed, json_schema=schema)
            except GenkitError as error:
                if error.message.startswith('Invalid output_schema'):
                    raise
                self._mark_invalid_output(error.message)
                return

        # A custom format's parser can return a scalar (e.g. enum string).
        # Skip Pydantic model validation for scalars.
        is_custom_scalar = self._message_parser is not None and not isinstance(parsed, (dict, list))
        if is_custom_scalar or self._schema_type is None:
            return

        try:
            _ = self._schema_type.model_validate(parsed)
        except ValidationError:
            self._mark_invalid_output('Model output did not match the requested schema.')

    def _raw_parsed_output(self) -> object:
        if self._message_parser and self.message is not None:
            return self._message_parser(self.message)
        return extract_json(self.text)

    def __eq__(self, other: object) -> bool:
        """Compare responses by message, finish_reason, and poll snapshot.

        Same job id with a later done/error/output is a later check, not
        the same response. Timing on the handle is not part of the job.
        """
        if isinstance(other, ModelResponse):
            return (
                self.message == other.message
                and self.finish_reason == other.finish_reason
                and operation_snapshot(operation=self.operation) == operation_snapshot(operation=other.operation)
            )
        return super().__eq__(other)

    def __hash__(self) -> int:
        """Return identity-based hash."""
        return hash(id(self))

    @property
    def text(self) -> str:
        """All text parts concatenated into a single string."""
        if self.message is None:
            return ''
        return self.message.text

    @property
    def reasoning(self) -> str:
        """The reply's reasoning (thinking) text, kept out of ``.text``; ``''`` when there is none."""
        if self.message is None:
            return ''
        return self.message.reasoning

    @property
    def output(self) -> OutputT | None:
        """Parsed structured output, or None when the reply is not that shape.

        generate() does not throw when the text is not the schema. If you
        asked for a schema and this is not it, read ``error`` / ``.text``.
        Only complete JSON counts: a reply cut off mid-object is None (check
        ``finish_reason == 'length'`` to tell a token cap from bad JSON).
        """
        # BLOCKED and FAILED carry no legitimate content at all, so there is
        # nothing to hand back even when the caller only asked for a format.
        # The rest of ABNORMAL_FINISH_REASONS can still hold usable parts (an
        # interrupt carries tool requests), so they only gate the schema path.
        if self.finish_reason in (FinishReason.BLOCKED, FinishReason.FAILED):
            return None
        if self._wants_structure and self.finish_reason in ABNORMAL_FINISH_REASONS:
            return None

        schema = self.request.output_schema if self.request is not None else None

        try:
            parsed = self._raw_parsed_output()
        except Exception:
            # Text that is not the shape they asked for is still text. Reading
            # it back is never worth an exception: `.text` holds the raw reply
            # and `error` carries INVALID_OUTPUT when structure was requested.
            return None

        if schema is not None:
            try:
                parse_schema(data=parsed, json_schema=schema)
            except GenkitError:
                return None

        # A custom format's parser can return a scalar (e.g. enum string).
        # Skip Pydantic model validation for scalars.
        is_custom_scalar = self._message_parser is not None and not isinstance(parsed, (dict, list))
        if is_custom_scalar or self._schema_type is None or parsed is None:
            return cast(OutputT, parsed)

        try:
            return cast(OutputT, self._schema_type.model_validate(parsed))
        except ValidationError:
            return None

    @property
    def messages(self) -> list[Message]:
        """All messages including request history and the response message.

        Recomputed each read so attaching ``request`` later still shows up.
        """
        if self.message is None:
            return [as_message(m) for m in self.request.messages] if self.request else []
        return [
            *(as_message(m) for m in (self.request.messages if self.request else [])),
            self.message,
        ]

    @property
    def tool_requests(self) -> list[Part]:
        """All tool request parts in the response message.

        Recomputed each read so a later message still shows up.
        """
        if self.message is None:
            return []
        return self.message.tool_requests

    @property
    def media(self) -> Media | None:
        """The first media part in the response message, or ``None``.

        Use ``media_parts`` when the model returns more than one.
        """
        if self.message is None:
            return None
        return self.message.media

    @property
    def media_parts(self) -> list[Media]:
        """All media parts in the response message."""
        if self.message is None:
            return []
        return [part.media for part in self.message.content if part.media is not None]

    @property
    def interrupts(self) -> list[Part]:
        """Tool requests marked as interrupted."""
        if self.message is None:
            return []
        return self.message.interrupts

interrupts property

Tool requests marked as interrupted.

media property

The first media part in the response message, or None.

Use media_parts when the model returns more than one.

media_parts property

All media parts in the response message.

messages property

All messages including request history and the response message.

Recomputed each read so attaching request later still shows up.

output property

Parsed structured output, or None when the reply is not that shape.

generate() does not throw when the text is not the schema. If you asked for a schema and this is not it, read error / .text. Only complete JSON counts: a reply cut off mid-object is None (check finish_reason == 'length' to tell a token cap from bad JSON).

reasoning property

The reply's reasoning (thinking) text, kept out of .text; '' when there is none.

text property

All text parts concatenated into a single string.

tool_requests property

All tool request parts in the response message.

Recomputed each read so a later message still shows up.

__eq__(other)

Compare responses by message, finish_reason, and poll snapshot.

Same job id with a later done/error/output is a later check, not the same response. Timing on the handle is not part of the job.

Source code in packages/genkit/src/genkit/_core/_model.py
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
def __eq__(self, other: object) -> bool:
    """Compare responses by message, finish_reason, and poll snapshot.

    Same job id with a later done/error/output is a later check, not
    the same response. Timing on the handle is not part of the job.
    """
    if isinstance(other, ModelResponse):
        return (
            self.message == other.message
            and self.finish_reason == other.finish_reason
            and operation_snapshot(operation=self.operation) == operation_snapshot(operation=other.operation)
        )
    return super().__eq__(other)

__hash__()

Return identity-based hash.

Source code in packages/genkit/src/genkit/_core/_model.py
1917
1918
1919
def __hash__(self) -> int:
    """Return identity-based hash."""
    return hash(id(self))

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

model_post_init(__context)

Initialize default usage and custom dict if not provided.

Source code in packages/genkit/src/genkit/_core/_model.py
1805
1806
1807
1808
1809
1810
def model_post_init(self, __context: object) -> None:
    """Initialize default usage and custom dict if not provided."""
    if self.usage is None:
        self.usage = GenerationUsage()
    if self.custom is None:
        self.custom = {}

ModelResponseChunk

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._model.OutputT]

Streaming chunk with text, accumulated text, and output parsing.

Source code in packages/genkit/src/genkit/_core/_model.py
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
class ModelResponseChunk(GenkitModel, Generic[OutputT]):
    """Streaming chunk with text, accumulated text, and output parsing."""

    role: Any | None = Field(default=None)
    index: float | None = None
    content: list[Part]
    custom: Any | None = Field(default=None)
    aggregated: bool | None = None
    # History and the format parser are stamped by the stream helper after
    # construction so the constructor a plugin types is just the wire fields.
    _previous_chunks: list[Any] = PrivateAttr(default_factory=list)
    _chunk_parser: Callable[..., object] | None = PrivateAttr(default=None)
    _schema_type: type[BaseModel] | None = PrivateAttr(default=None)
    # .output is parsed once per chunk. A plain @property over a private cache
    # rather than @cached_property: ty loses OutputT through cached_property on
    # a generic model and types every chunk.output as None.
    _output_parsed: bool = PrivateAttr(default=False)
    _output_cache: Any = PrivateAttr(default=None)

    @field_validator('content', mode='before')
    @classmethod
    def _wrap_parts(cls, v: object) -> object:
        return parts_from_inbound(v)

    def __eq__(self, other: object) -> bool:
        """Check equality."""
        if isinstance(other, ModelResponseChunk):
            return self.role == other.role and self.content == other.content
        return super().__eq__(other)

    def __hash__(self) -> int:
        """Return hash."""
        return hash(id(self))

    @property
    def text(self) -> str:
        """Text content of this chunk."""
        return ''.join(p.text for p in self.content if p.text is not None)

    @property
    def reasoning(self) -> str:
        """Reasoning (thinking) text in this chunk."""
        return ''.join(p.reasoning for p in self.content if p.reasoning is not None)

    @property
    def accumulated_text(self) -> str:
        """Text from all previous chunks plus this chunk."""
        prior = ''
        if self._previous_chunks:
            prior = ''.join(p.text for chunk in self._previous_chunks for p in chunk.content if p.text)
        return prior + self.text

    @property
    def media(self) -> Media | None:
        """The first media part in this chunk, or ``None``."""
        return next((p.media for p in self.content if p.media is not None), None)

    @property
    def tool_requests(self) -> list[Part]:
        """All tool request parts in this chunk."""
        return [p for p in self.content if p.tool_request is not None]

    @property
    def tool_responses(self) -> list[Part]:
        """All tool response parts in this chunk."""
        return [p for p in self.content if p.tool_response is not None]

    @property
    def output(self) -> OutputT | None:
        """The reply so far, parsed as far as it goes. Never raises.

        With ``output_schema=Recipe``, this is a ``Recipe`` filled as far as
        the JSON goes:
        - Optional fields populate from their default or ``default_factory``
          (called fresh per chunk, so non-deterministic factories like ``uuid4``
          or ``datetime.now`` change per chunk until final validation), and
          missing required fields are ``None``.
        - Closed fields and list items run field validation (``@field_validator``
          and field constraints, while ``@model_validator`` waits until the
          object closes); closed values that fail validation pass through raw.
        - Open ``str`` fields stream as prefixes, while open ``str`` values for
          ``Enum``/``datetime``/``Literal`` and unresolved discriminated unions
          stay at ``None`` (or their default) until closed. Open numbers still
          pass through raw for ``datetime`` fields and for numeric ``Literal``
          values that already match a member (even if more digits may follow).

        ``(await stream.response).output`` is the only fully validated ``Recipe``.
        The partial is built without validation, so a required ``title: str``
        can read ``None`` here even though the type says ``str``. Guard each
        field before you use it: ``if chunk.output and chunk.output.title:``.

        With no schema class, this is the JSON value so far (dict, list,
        or scalar). It's ``None`` before an object starts or while the text
        can't be parsed.
        """
        if not self._output_parsed:
            self._output_cache = self._parse_output()
            self._output_parsed = True
        return cast('OutputT | None', self._output_cache)

    def _parse_output(self) -> object:
        if self.role is not None and self.role != Role.MODEL:
            return None
        try:
            text = self.accumulated_text
            parsed = self._chunk_parser(self) if self._chunk_parser else extract_partial_json(text)
            if (
                self._schema_type is not None
                and isinstance(parsed, dict)
                and not issubclass(self._schema_type, RootModel)
            ):
                return construct_partial(
                    schema_type=self._schema_type,
                    data=parsed,
                    closed=is_complete_json(text),
                )
            return parsed
        except Exception:
            # one odd chunk shouldn't end a stream whose final reply may still parse.
            logger.debug('chunk.output could not be parsed; returning None', exc_info=True)
            return None

accumulated_text property

Text from all previous chunks plus this chunk.

media property

The first media part in this chunk, or None.

output property

The reply so far, parsed as far as it goes. Never raises.

With output_schema=Recipe, this is a Recipe filled as far as the JSON goes: - Optional fields populate from their default or default_factory (called fresh per chunk, so non-deterministic factories like uuid4 or datetime.now change per chunk until final validation), and missing required fields are None. - Closed fields and list items run field validation (@field_validator and field constraints, while @model_validator waits until the object closes); closed values that fail validation pass through raw. - Open str fields stream as prefixes, while open str values for Enum/datetime/Literal and unresolved discriminated unions stay at None (or their default) until closed. Open numbers still pass through raw for datetime fields and for numeric Literal values that already match a member (even if more digits may follow).

(await stream.response).output is the only fully validated Recipe. The partial is built without validation, so a required title: str can read None here even though the type says str. Guard each field before you use it: if chunk.output and chunk.output.title:.

With no schema class, this is the JSON value so far (dict, list, or scalar). It's None before an object starts or while the text can't be parsed.

reasoning property

Reasoning (thinking) text in this chunk.

text property

Text content of this chunk.

tool_requests property

All tool request parts in this chunk.

tool_responses property

All tool response parts in this chunk.

__eq__(other)

Check equality.

Source code in packages/genkit/src/genkit/_core/_model.py
2052
2053
2054
2055
2056
def __eq__(self, other: object) -> bool:
    """Check equality."""
    if isinstance(other, ModelResponseChunk):
        return self.role == other.role and self.content == other.content
    return super().__eq__(other)

__hash__()

Return hash.

Source code in packages/genkit/src/genkit/_core/_model.py
2058
2059
2060
def __hash__(self) -> int:
    """Return hash."""
    return hash(id(self))

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ModelStreamResponse

Bases: genkit._core._action.StreamResponse[genkit._ai._model.ModelResponseChunk[genkit._ai._prompt.OutputT], genkit._ai._model.ModelResponse[genkit._ai._prompt.OutputT]], typing.Generic[genkit._ai._prompt.OutputT]

Chunks of a model reply, then the full ModelResponse.

Returned by ai.generate_stream() and prompt.stream(). Iteration and .response follow StreamResponse; failures and early exit don't:

  • Before the request (unknown model, bad config, ...): the loop and .response both raise the GenkitError (NOT_FOUND, ...).
  • Model or tool failure on any turn, including the first: the loop ends normally and .response resolves with error set and finish_reason == FAILED. The chunks already received are the record of what was shown.
  • Early close (async with or await result.aclose()): stops the in-flight model or tool turn and awaits finally: cleanup; .response resolves with finish_reason == ABORTED, error.status == 'CANCELLED', and messages ending at the last completed round.
Example
result = ai.generate_stream(prompt='Describe miso soup in one line.')
async for chunk in result.stream:
    print(chunk.text)
# => Savory soybean broth
#    with tofu and scallions.

response = await result.response
print(response.finish_reason)
# => stop
Source code in packages/genkit/src/genkit/_ai/_prompt.py
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
class ModelStreamResponse(StreamResponse[ModelResponseChunk[OutputT], ModelResponse[OutputT]], Generic[OutputT]):
    """Chunks of a model reply, then the full ``ModelResponse``.

    Returned by ``ai.generate_stream()`` and ``prompt.stream()``. Iteration
    and ``.response`` follow ``StreamResponse``; failures and early exit don't:

    - **Before the request** (unknown model, bad config, ...): the loop and
      ``.response`` both raise the ``GenkitError`` (``NOT_FOUND``, ...).
    - **Model or tool failure on any turn, including the first**: the loop
      ends normally and ``.response`` resolves with ``error`` set and
      ``finish_reason == FAILED``. The chunks already received are the record
      of what was shown.
    - **Early close** (``async with`` or ``await result.aclose()``): stops the
      in-flight model or tool turn and awaits ``finally:`` cleanup;
      ``.response`` resolves with ``finish_reason == ABORTED``,
      ``error.status == 'CANCELLED'``, and ``messages`` ending at the last
      completed round.

    Example:
        ```python
        result = ai.generate_stream(prompt='Describe miso soup in one line.')
        async for chunk in result.stream:
            print(chunk.text)
        # => Savory soybean broth
        #    with tofu and scallions.

        response = await result.response
        print(response.finish_reason)
        # => stop
        ```
    """

response property

The final result, available once the run ends.

stream property

The chunks, in order (AsyncIterator). Iterating the response itself reads the same stream.

aclose() async

Close the stream and release any underlying resources.

Source code in packages/genkit/src/genkit/_core/_action.py
294
295
296
297
298
async def aclose(self) -> None:
    """Close the stream and release any underlying resources."""
    aclose = getattr(self._stream, 'aclose', None)
    if aclose is not None:
        await aclose()

MultipartToolResponse

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._model.OutputT]

A tool result with structured output plus media the model can see.

Return one from a tool when the reply is more than a JSON value, such as a caption and a screenshot. A plain return value still works and is treated as output only. Annotate MultipartToolResponse[ShotOut] so the tool's output schema is ShotOut.

Example
@ai.tool
async def screenshot(label: str) -> MultipartToolResponse[Shot]:
    return MultipartToolResponse(output=Shot(label=label), content=[png])
Source code in packages/genkit/src/genkit/_core/_model.py
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
class MultipartToolResponse(GenkitModel, Generic[OutputT]):
    """A tool result with structured output plus media the model can see.

    Return one from a tool when the reply is more than a JSON value, such as
    a caption and a screenshot. A plain ``return value`` still works and is
    treated as ``output`` only. Annotate ``MultipartToolResponse[ShotOut]`` so
    the tool's output schema is ``ShotOut``.

    Example:
        ```python
        @ai.tool
        async def screenshot(label: str) -> MultipartToolResponse[Shot]:
            return MultipartToolResponse(output=Shot(label=label), content=[png])
        ```
    """

    output: OutputT | None = None
    content: list[Part] | None = None
    metadata: dict[str, Any] | None = None

    @field_validator('content', mode='before')
    @classmethod
    def _wrap_parts(cls, v: object) -> object:
        if v is None:
            return None
        if isinstance(v, (str, bytes, Mapping, Part)) or not isinstance(v, Sequence):
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=f'MultipartToolResponse content must be a list of Parts, got {type(v).__name__}.',
                reason=ErrorReason.INVALID_PART,
            )
        out: list[Part] = []
        for item in v:
            try:
                out.append(as_part(item))
            except (ValidationError, ValueError, TypeError) as e:
                raise GenkitError(
                    status='INVALID_ARGUMENT',
                    message=(
                        f'MultipartToolResponse content must be a list of Parts, got {type(item).__name__} in the list.'
                    ),
                    reason=ErrorReason.INVALID_PART,
                ) from e
        return out

    @field_validator('metadata', mode='before')
    @classmethod
    def _require_dict_metadata(cls, v: object) -> object:
        if v is not None and not isinstance(v, dict):
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=f'MultipartToolResponse metadata must be a dict, got {type(v).__name__}.',
                reason=ErrorReason.INVALID_INPUT,
            )
        return v

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Operation

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._operation.OutputT]

Poll handle for a background job.

A background action returns an Operation right away. Poll it until done is true, then read output or error. Generic over the output type, like JS Operation<O> and Go Operation[Out]. Background models return Operation[ModelResponse]. The wire shape does not depend on OutputT, so a stored handle goes back to ai.check_operation as the dict you saved, or reloads with Operation[ModelResponse].model_validate_json(...).

Example
# 1. Start a background video generation
op = await ai.generate_operation(model='googleai/veo-3.1-generate-preview', prompt='A chef plating risotto.')
print(op.done)
# => False

# 2. Store the handle; later, check it with the dict you saved
saved = op.model_dump_json()
op = await ai.check_operation(json.loads(saved))

# 3. Poll until done; output is a ModelResponse
while not op.done:
    op = await ai.check_operation(op)
print(op.output.media.url)
# => https://storage.googleapis.com/.../risotto.mp4
Source code in packages/genkit/src/genkit/_core/_operation.py
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
class Operation(GenkitModel, Generic[OutputT]):
    """Poll handle for a background job.

    A background action returns an ``Operation`` right away. Poll it until
    ``done`` is true, then read ``output`` or ``error``. Generic over the
    output type, like JS ``Operation<O>`` and Go ``Operation[Out]``. Background
    models return ``Operation[ModelResponse]``. The wire shape does not depend
    on ``OutputT``, so a stored handle goes back to ``ai.check_operation`` as
    the dict you saved, or reloads with
    ``Operation[ModelResponse].model_validate_json(...)``.

    Example:
        ```python
        # 1. Start a background video generation
        op = await ai.generate_operation(model='googleai/veo-3.1-generate-preview', prompt='A chef plating risotto.')
        print(op.done)
        # => False

        # 2. Store the handle; later, check it with the dict you saved
        saved = op.model_dump_json()
        op = await ai.check_operation(json.loads(saved))

        # 3. Poll until done; output is a ModelResponse
        while not op.done:
            op = await ai.check_operation(op)
        print(op.output.media.url)
        # => https://storage.googleapis.com/.../risotto.mp4
        ```
    """

    # Pin the schema description to the generated one. Without it Pydantic copies
    # this docstring into every background model's outputSchema. Pydantic
    # merges this with GenkitModel's config.
    model_config: ClassVar[ConfigDict] = ConfigDict(
        json_schema_extra={'description': 'Model for operation data.'},
    )
    action: str | None = None
    id: str = Field(...)
    done: bool | None = None
    output: OutputT | None = None
    error: Failure | None = None
    metadata: Metadata | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Part

Bases: genkit._core._base.GenkitModel

A single piece of content in a message or document.

Source code in packages/genkit/src/genkit/_core/_model.py
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
class Part(GenkitModel):
    """A single piece of content in a message or document."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel,
        extra='forbid',
        validate_by_name=True,
        validate_by_alias=True,
        validate_assignment=True,
    )

    text: str | None = None
    media: Media | None = None
    tool_request: ToolRequest | None = None
    tool_response: ToolResponse | None = None
    data: Any | None = Field(default=None)
    metadata: dict[str, Any] | None = None
    custom: dict[str, Any] | None = None
    reasoning: str | None = None
    resource: Resource | None = None

    @model_validator(mode='before')
    @classmethod
    def _exactly_one_kind(cls, value: object) -> object:
        if isinstance(value, Mapping) and 'root' in value:
            raise ValueError('Part(root=...) is gone; use Part.from_text or Part(text=...)')
        if isinstance(value, Part):
            value = dump_keeping_unknown(value)
        if isinstance(value, PartData):
            value = value.root
        if isinstance(value, BaseModel):
            value = dump_keeping_unknown(value)
        if not isinstance(value, dict):
            return value
        raw = cast(dict[str, object], value)
        _require_exactly_one_kind(raw)
        return value

    @model_validator(mode='after')
    def _exactly_one_kind_after(self) -> Part:
        # Construct already checked the incoming dict. This one catches
        # part.media = ... on an existing text part, and treats data=null
        # as a real payload so a tool that returned null still has a kind.
        kinds = [name for name in PART_KIND_FIELDS if getattr(self, name) is not None]
        if not kinds and self.custom is None and 'data' in self.model_fields_set and self.data is None:
            kinds.append('data')
        if len(kinds) > 1:
            raise ValueError(EXACTLY_ONE_KIND)
        if len(kinds) == 1:
            return self
        if self.custom is not None:
            return self
        raise ValueError(EXACTLY_ONE_KIND)

    def _drop_none_fields(self, dumped: dict[str, Any]) -> dict[str, Any]:
        kept = super()._drop_none_fields(dumped)
        # Keep data: null when it's the part's only payload so replay still
        # sees a data part instead of an empty one.
        if self._is_null_data_part():
            kept['data'] = None
        return kept

    def _is_null_data_part(self) -> bool:
        if 'data' not in self.model_fields_set or self.custom is not None:
            return False
        return all(getattr(self, name) is None for name in PART_KIND_FIELDS)

    @classmethod
    def from_text(cls, text: str, metadata: dict[str, Any] | None = None) -> Part:
        return cls(text=text, metadata=metadata)

    @classmethod
    def from_media(
        cls,
        url: str,
        content_type: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> Part:
        return cls(media=Media(url=url, content_type=content_type), metadata=metadata)

    @classmethod
    def from_tool_request(
        cls,
        name: str,
        input: Any | None = None,  # noqa: ANN401
        ref: str | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> Part:
        return cls(tool_request=ToolRequest(name=name, input=input, ref=ref), metadata=metadata)

    @classmethod
    def from_tool_response(
        cls,
        name: str,
        output: Any | None = None,  # noqa: ANN401
        ref: str | None = None,
        metadata: dict[str, Any] | None = None,
        content: Sequence[Part] | None = None,
    ) -> Part:
        """Build a tool-response part, e.g. for a manual tool loop.

        ``content`` carries media the model should see next to ``output``
        (a screenshot, a chart). A ``MultipartToolResponse`` passed as
        ``output`` is unwrapped the way the engine does it: its ``output``,
        ``content``, and ``metadata`` land in their own slots instead of being
        serialized as JSON text. Setting ``content`` or ``metadata`` both on
        the ``MultipartToolResponse`` and as a keyword raises ``GenkitError``
        (``INVALID_ARGUMENT``) instead of dropping one.

        ``output`` and ``metadata`` are dumped to JSON and ``content`` to wire
        parts, the same as a tool return inside ``generate``, so a Pydantic
        output reaches the model plugin as JSON. Output that can't be dumped,
        or a part with nothing in it (an empty media URL), raises
        ``GenkitError`` (``INVALID_ARGUMENT``) here.
        """
        if isinstance(output, MultipartToolResponse):
            multipart = cast('MultipartToolResponse[Any]', output)
            # Two sources for one slot is a caller mistake; picking one would drop the other silently.
            for slot, explicit, wrapped in (
                ('content', content, multipart.content),
                ('metadata', metadata, multipart.metadata),
            ):
                if explicit is not None and wrapped is not None:
                    raise GenkitError(
                        status='INVALID_ARGUMENT',
                        message=(
                            f"tool '{name}': {slot} is set on the MultipartToolResponse and passed as {slot}=. "
                            'Pass it in one place.'
                        ),
                    )
            if content is None:
                content = multipart.content
            if metadata is None:
                metadata = multipart.metadata
            output = multipart.output
        return cls(
            tool_response=ToolResponse(
                name=name,
                output=dump_tool_output(output, tool_name=name),
                ref=ref,
                content=parts_to_wire(content, tool_name=name),
            ),
            metadata=dump_tool_metadata(metadata, tool_name=name),
        )

    @classmethod
    def from_data(cls, data: Any, metadata: dict[str, Any] | None = None) -> Part:  # noqa: ANN401
        return cls(data=data, metadata=metadata)

    @classmethod
    def from_custom(cls, custom: dict[str, Any], metadata: dict[str, Any] | None = None) -> Part:
        return cls(custom=custom, metadata=metadata)

    @classmethod
    def from_reasoning(cls, reasoning: str, metadata: dict[str, Any] | None = None) -> Part:
        return cls(reasoning=reasoning, metadata=metadata)

    def restart(
        self,
        *,
        resumed_metadata: dict[str, Any] | None = None,
        replace_input: Any | None = None,  # noqa: ANN401
    ) -> Part:
        """Build the tool-request part that runs this interrupt again.

        ``resumed_metadata`` is what the tool reads as ``ctx.resumed_metadata``.
        Omit it and the tool still sees a resume (``ctx.is_resumed()`` is true).
        ``replace_input`` swaps the tool input and keeps the previous input on
        ``metadata['replacedInput']``.
        """
        tool_req = self.tool_request
        if tool_req is None:
            raise ValueError('restart needs a tool request part')
        new_meta: dict[str, Any] = dict(self.metadata or {})
        new_meta['resumed'] = resumed_metadata if resumed_metadata is not None else True
        new_input = tool_req.input
        if replace_input is not None:
            new_meta['replacedInput'] = tool_req.input
            new_input = replace_input
        return Part.from_tool_request(
            name=tool_req.name,
            input=new_input,
            ref=tool_req.ref,
            metadata=new_meta,
        )

    def respond(
        self,
        output: Any,  # noqa: ANN401
        *,
        metadata: dict[str, Any] | None = None,
    ) -> Part:
        """Build the tool-response part that answers this interrupt without running the tool.

        ``metadata`` is stored under ``interruptResponse`` and defaults to true when omitted.
        """
        tool_req = self.tool_request
        if tool_req is None:
            raise ValueError('respond needs a tool request part')
        interrupt_metadata = metadata if metadata is not None else True
        return Part.from_tool_response(
            name=tool_req.name,
            output=output,
            ref=tool_req.ref,
            metadata={'interruptResponse': interrupt_metadata},
        )

    @property
    def is_partial(self) -> bool:
        """Whether this part is a partial tool response streamed during tool execution."""
        return self.tool_response is not None and bool(self.metadata and self.metadata.get('partial') is True)

is_partial property

Whether this part is a partial tool response streamed during tool execution.

from_tool_response(name, output=None, ref=None, metadata=None, content=None) classmethod

Build a tool-response part, e.g. for a manual tool loop.

content carries media the model should see next to output (a screenshot, a chart). A MultipartToolResponse passed as output is unwrapped the way the engine does it: its output, content, and metadata land in their own slots instead of being serialized as JSON text. Setting content or metadata both on the MultipartToolResponse and as a keyword raises GenkitError (INVALID_ARGUMENT) instead of dropping one.

output and metadata are dumped to JSON and content to wire parts, the same as a tool return inside generate, so a Pydantic output reaches the model plugin as JSON. Output that can't be dumped, or a part with nothing in it (an empty media URL), raises GenkitError (INVALID_ARGUMENT) here.

Source code in packages/genkit/src/genkit/_core/_model.py
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
@classmethod
def from_tool_response(
    cls,
    name: str,
    output: Any | None = None,  # noqa: ANN401
    ref: str | None = None,
    metadata: dict[str, Any] | None = None,
    content: Sequence[Part] | None = None,
) -> Part:
    """Build a tool-response part, e.g. for a manual tool loop.

    ``content`` carries media the model should see next to ``output``
    (a screenshot, a chart). A ``MultipartToolResponse`` passed as
    ``output`` is unwrapped the way the engine does it: its ``output``,
    ``content``, and ``metadata`` land in their own slots instead of being
    serialized as JSON text. Setting ``content`` or ``metadata`` both on
    the ``MultipartToolResponse`` and as a keyword raises ``GenkitError``
    (``INVALID_ARGUMENT``) instead of dropping one.

    ``output`` and ``metadata`` are dumped to JSON and ``content`` to wire
    parts, the same as a tool return inside ``generate``, so a Pydantic
    output reaches the model plugin as JSON. Output that can't be dumped,
    or a part with nothing in it (an empty media URL), raises
    ``GenkitError`` (``INVALID_ARGUMENT``) here.
    """
    if isinstance(output, MultipartToolResponse):
        multipart = cast('MultipartToolResponse[Any]', output)
        # Two sources for one slot is a caller mistake; picking one would drop the other silently.
        for slot, explicit, wrapped in (
            ('content', content, multipart.content),
            ('metadata', metadata, multipart.metadata),
        ):
            if explicit is not None and wrapped is not None:
                raise GenkitError(
                    status='INVALID_ARGUMENT',
                    message=(
                        f"tool '{name}': {slot} is set on the MultipartToolResponse and passed as {slot}=. "
                        'Pass it in one place.'
                    ),
                )
        if content is None:
            content = multipart.content
        if metadata is None:
            metadata = multipart.metadata
        output = multipart.output
    return cls(
        tool_response=ToolResponse(
            name=name,
            output=dump_tool_output(output, tool_name=name),
            ref=ref,
            content=parts_to_wire(content, tool_name=name),
        ),
        metadata=dump_tool_metadata(metadata, tool_name=name),
    )

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

respond(output, *, metadata=None)

Build the tool-response part that answers this interrupt without running the tool.

metadata is stored under interruptResponse and defaults to true when omitted.

Source code in packages/genkit/src/genkit/_core/_model.py
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
def respond(
    self,
    output: Any,  # noqa: ANN401
    *,
    metadata: dict[str, Any] | None = None,
) -> Part:
    """Build the tool-response part that answers this interrupt without running the tool.

    ``metadata`` is stored under ``interruptResponse`` and defaults to true when omitted.
    """
    tool_req = self.tool_request
    if tool_req is None:
        raise ValueError('respond needs a tool request part')
    interrupt_metadata = metadata if metadata is not None else True
    return Part.from_tool_response(
        name=tool_req.name,
        output=output,
        ref=tool_req.ref,
        metadata={'interruptResponse': interrupt_metadata},
    )

restart(*, resumed_metadata=None, replace_input=None)

Build the tool-request part that runs this interrupt again.

resumed_metadata is what the tool reads as ctx.resumed_metadata. Omit it and the tool still sees a resume (ctx.is_resumed() is true). replace_input swaps the tool input and keeps the previous input on metadata['replacedInput'].

Source code in packages/genkit/src/genkit/_core/_model.py
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
def restart(
    self,
    *,
    resumed_metadata: dict[str, Any] | None = None,
    replace_input: Any | None = None,  # noqa: ANN401
) -> Part:
    """Build the tool-request part that runs this interrupt again.

    ``resumed_metadata`` is what the tool reads as ``ctx.resumed_metadata``.
    Omit it and the tool still sees a resume (``ctx.is_resumed()`` is true).
    ``replace_input`` swaps the tool input and keeps the previous input on
    ``metadata['replacedInput']``.
    """
    tool_req = self.tool_request
    if tool_req is None:
        raise ValueError('restart needs a tool request part')
    new_meta: dict[str, Any] = dict(self.metadata or {})
    new_meta['resumed'] = resumed_metadata if resumed_metadata is not None else True
    new_input = tool_req.input
    if replace_input is not None:
        new_meta['replacedInput'] = tool_req.input
        new_input = replace_input
    return Part.from_tool_request(
        name=tool_req.name,
        input=new_input,
        ref=tool_req.ref,
        metadata=new_meta,
    )

Prompt

Bases: typing.Generic[genkit._ai._prompt.InputT, genkit._ai._prompt.OutputT]

A callable prompt with typed input/output that generates AI responses.

Source code in packages/genkit/src/genkit/_ai/_prompt.py
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
class Prompt(Generic[InputT, OutputT]):
    """A callable prompt with typed input/output that generates AI responses."""

    def __init__(
        self,
        ai: _aio.Genkit,
        *,
        variant: str | None = None,
        model: ModelArg | Action | None = None,
        config: Mapping[str, Any] | BaseModel | None = None,
        description: str | None = None,
        input_schema: type | dict[str, Any] | str | None = None,
        input_default: dict[str, Any] | None = None,
        system: str | list[Part] | None = None,
        prompt: str | list[Part] | None = None,
        messages: str | list[Message] | None = None,
        output_format: str | None = None,
        output_content_type: str | None = None,
        output_instructions: bool | str | None = None,
        output_schema: type | dict[str, Any] | str | None = None,
        output_constrained: bool | None = None,
        max_turns: int | None = None,
        return_tool_requests: bool | None = None,
        metadata: dict[str, Any] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        use: Sequence[Middleware] | None = None,
        docs: list[Document] | None = None,
        name: str | None = None,
        ns: str | None = None,
    ) -> None:
        """Initialize prompt with configuration, templates, and schema options."""
        self._ai = ai
        # Keys the caller leaves out take these values before the template runs.
        self._input_default = dict(input_default) if input_default else None
        # Set when a lookup also passed input_schema=; the file's schema still
        # has to pass so a required file field can't slip through.
        self._file_input_schema: type | dict[str, Any] | str | None = None
        # Identity: how the prompt is registered and looked up. Not part of _def,
        # which only holds what goes into a generate.
        self._name = name
        self._ns = ns
        self._variant = variant
        self._description = description
        # The whole definition as one value. Per-call overrides layer over it
        # in prepare_prompt via with_overrides; nothing mutates it after define
        # except _ensure_resolved swapping in a lazily loaded definition.
        self._def = GenerateCall(
            model=model,
            config=config,
            input_schema=input_schema,
            system=system,
            prompt=prompt,
            messages=messages,
            output_format=output_format,
            output_content_type=output_content_type,
            output_instructions=output_instructions,
            output_schema=output_schema,
            output_constrained=output_constrained,
            max_turns=max_turns,
            return_tool_requests=return_tool_requests,
            metadata=metadata,
            tools=tools,
            tool_choice=tool_choice,
            use=use,
            docs=docs,
        )
        # Compiled system/messages/prompt templates, filled on first render and reused.
        self._compiled_templates: PromptCache = PromptCache()
        self._prompt_action: Action | None = None
        define_name, define_schema = config_schema_at_define(model=model, registry=ai._registry)
        # Hop identity is what we knew at define time, not today's defaultModel.
        # Not a GenerateCall field, so _ensure_resolved copies it explicitly.
        self._defined_model_name = define_name
        assert_correct_config_class(config=config, schema=define_schema, model=define_name)

    @property
    def ref(self) -> dict[str, Any]:
        """Reference object with prompt name and metadata."""
        return {
            'name': registry_definition_key(self._name, self._variant, self._ns) if self._name else None,
            'metadata': self._def.metadata,
        }

    async def _ensure_resolved(self) -> None:
        if self._prompt_action or not self._name:
            return

        resolved = await lookup_prompt(self._ai._registry, self._name, self._variant)
        # Keep a Pydantic output type the caller passed: it wins over the file's
        # dict schema or registered name, and the type is what gives typed output.
        keep: dict[str, Any] = {}
        schema = self._def.output_schema
        if isinstance(schema, type) and issubclass(schema, BaseModel):
            keep['output_schema'] = schema
        original_input = self._def.input_schema
        if original_input is not None:
            keep['input_schema'] = original_input
            self._file_input_schema = resolved._file_input_schema or resolved._def.input_schema
        else:
            self._file_input_schema = resolved._file_input_schema
        self._def = resolved._def.model_copy(update=keep)
        self._defined_model_name = resolved._defined_model_name
        self._input_default = resolved._input_default
        self._prompt_action = resolved._prompt_action

    async def _resolve_model(self, call: GenerateCall, opts: ModelSettings) -> GenerateCall:
        """Resolve the model (the call's or the prompt's) and merge the call's config over the prompt's.

        Returns ``call`` with ``model`` set to the resolved name and ``config``
        to the merged, resolved config.
        """
        override_config = opts.get('config')
        override_model = opts.get('model')
        # A hop is a different model name: 'gem' and ModelRef(name='gem') are the same model.
        hopping = (
            override_model is not None
            and self._defined_model_name is not None
            and resolve_model_name(model=override_model, registry=self._ai._registry) != self._defined_model_name
        )
        model = override_model if override_model is not None else self._def.model
        resolved = await resolve_for_generate(
            model=model,
            config=override_config,
            prompt_config=self._def.config,
            hopping=hopping,
            registry=self._ai._registry,
        )
        check_config = override_config
        if hopping and isinstance(override_config, Mapping):
            _, check_config = clear_on_hop(
                prompt_config=self._def.config,
                call_config=override_config,
                schema=resolved.config_schema,
            )
        check_call_config(
            config=check_config,
            schema=resolved.config_schema,
            model=resolved.name,
        )
        # Re-check the stored typed config unless this call hops models.
        # A key the call sets to None replaces the prompt's value, so the
        # prompt's copy of that key is not checked against the model this call hits.
        if self._defined_model_name is None or self._defined_model_name == resolved.name:
            assert_correct_config_class(
                config=self._def.config,
                schema=resolved.config_schema,
                model=resolved.name,
            )
        check_config_values(
            config=unoverridden_prompt_config(
                stored=self._def.config,
                override=override_config,
                schema=resolved.config_schema,
            ),
            schema=resolved.config_schema,
            model=resolved.name,
        )
        return call.model_copy(update={'model': resolved.name, 'config': resolved.config})

    async def __call__(
        self,
        input: InputT | dict[str, Any] | None = None,
        *,
        model: ModelArg | Action | None = None,
        config: Mapping[str, Any] | BaseModel | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        docs: list[Document] | None = None,
        use: Sequence[Middleware] | None = None,
        max_turns: int | None = None,
        context: dict[str, Any] | None = None,
        return_tool_requests: bool | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
        on_chunk: Callable[[ModelResponseChunk], Any] | None = None,
    ) -> ModelResponse[OutputT]:
        """Render the prompt with ``input`` as template variables, run it, and return the response.

        Keywords take the same names as ``ai.generate``. An omitted (or ``None``)
        keyword keeps the prompt's value; ``tools=[]``, ``use=[]`` and ``docs=[]``
        clear the prompt's list for this call. ``config`` merges per key.
        """
        opts = PromptGenerateOptions(
            model=model,
            config=config,
            messages=messages,
            tools=tools,
            tool_choice=tool_choice,
            docs=docs,
            use=use,
            max_turns=max_turns,
            context=context,
            return_tool_requests=return_tool_requests,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
        )
        return await self._run(input=input, opts=opts, on_chunk=on_chunk, caller_stopped=None)

    async def _run(
        self,
        *,
        input: InputT | dict[str, Any] | None,
        opts: PromptGenerateOptions,
        on_chunk: Callable[[ModelResponseChunk], Any] | None,
        caller_stopped: asyncio.Event | None,
    ) -> ModelResponse[OutputT]:
        async def run() -> ModelResponse:
            prepared = await render_prompt(prompt=self, input=input, opts=opts)
            return await generate_action(
                prepared.scope,
                prepared.options,
                on_chunk=on_chunk,
                # Same context the template already rendered, so {{@auth}} and tools agree.
                context=prepared.context,
                caller_stopped=caller_stopped,
            )

        # An unnamed prompt has nothing to label a span with, so its render and
        # generate sit directly under the caller.
        if not self._name:
            return cast(ModelResponse[OutputT], await run())

        async def body(_span: SpanContext) -> ModelResponse:
            result = await run()
            if result.error is not None:
                set_span_state('error', message=failed_span_message(result))
            return result

        result = await run_in_new_span(
            registry_definition_key(self._name, self._variant, self._ns),
            body,
            action_type='dotprompt',
            input=input,
        )
        return cast(ModelResponse[OutputT], result)

    def stream(
        self,
        input: InputT | dict[str, Any] | None = None,
        *,
        model: ModelArg | Action | None = None,
        config: Mapping[str, Any] | BaseModel | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        docs: list[Document] | None = None,
        use: Sequence[Middleware] | None = None,
        max_turns: int | None = None,
        context: dict[str, Any] | None = None,
        return_tool_requests: bool | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
    ) -> ModelStreamResponse[OutputT]:
        """Stream the prompt execution. Same keywords as ``__call__``, minus ``on_chunk``.

        Iterate ``.stream`` on the returned response for chunks; there's no
        callback here so chunks only arrive one way.
        """
        opts = PromptGenerateOptions(
            model=model,
            config=config,
            messages=messages,
            tools=tools,
            tool_choice=tool_choice,
            docs=docs,
            use=use,
            max_turns=max_turns,
            context=context,
            return_tool_requests=return_tool_requests,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
        )

        # Same run path as __call__; only the chunk sink differs.
        async def run(
            send_chunk: Callable[[ModelResponseChunk[OutputT]], None],
            caller_stopped: asyncio.Event,
        ) -> ModelResponse[OutputT]:
            return await self._run(
                input=input,
                opts=opts,
                on_chunk=lambda c: send_chunk(cast('ModelResponseChunk[OutputT]', c)),
                caller_stopped=caller_stopped,
            )

        initial_msgs = list(messages) if isinstance(messages, list) else []
        stream, task = start_generate_stream(initial_messages=initial_msgs, run=run)
        return ModelStreamResponse[OutputT](stream=stream, response=task)

    async def render(
        self,
        input: InputT | dict[str, Any] | None = None,
        *,
        model: ModelArg | Action | None = None,
        config: Mapping[str, Any] | BaseModel | None = None,
        messages: list[Message] | None = None,
        tools: Sequence[str | Tool] | None = None,
        tool_choice: ToolChoice | None = None,
        docs: list[Document] | None = None,
        use: Sequence[Middleware] | None = None,
        max_turns: int | None = None,
        context: dict[str, Any] | None = None,
        return_tool_requests: bool | None = None,
        resume_respond: Part | list[Part] | None = None,
        resume_restart: Part | list[Part] | None = None,
        resume_metadata: dict[str, Any] | None = None,
    ) -> GenerateActionOptions:
        """Render the prompt without running it. Same keywords as ``__call__``, minus ``on_chunk``."""
        opts = PromptGenerateOptions(
            model=model,
            config=config,
            messages=messages,
            tools=tools,
            tool_choice=tool_choice,
            docs=docs,
            use=use,
            max_turns=max_turns,
            context=context,
            return_tool_requests=return_tool_requests,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
        )
        return (await render_prompt(prompt=self, input=input, opts=opts)).options

ref property

Reference object with prompt name and metadata.

__call__(input=None, *, model=None, config=None, messages=None, tools=None, tool_choice=None, docs=None, use=None, max_turns=None, context=None, return_tool_requests=None, resume_respond=None, resume_restart=None, resume_metadata=None, on_chunk=None) async

Render the prompt with input as template variables, run it, and return the response.

Keywords take the same names as ai.generate. An omitted (or None) keyword keeps the prompt's value; tools=[], use=[] and docs=[] clear the prompt's list for this call. config merges per key.

Source code in packages/genkit/src/genkit/_ai/_prompt.py
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
async def __call__(
    self,
    input: InputT | dict[str, Any] | None = None,
    *,
    model: ModelArg | Action | None = None,
    config: Mapping[str, Any] | BaseModel | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    docs: list[Document] | None = None,
    use: Sequence[Middleware] | None = None,
    max_turns: int | None = None,
    context: dict[str, Any] | None = None,
    return_tool_requests: bool | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    on_chunk: Callable[[ModelResponseChunk], Any] | None = None,
) -> ModelResponse[OutputT]:
    """Render the prompt with ``input`` as template variables, run it, and return the response.

    Keywords take the same names as ``ai.generate``. An omitted (or ``None``)
    keyword keeps the prompt's value; ``tools=[]``, ``use=[]`` and ``docs=[]``
    clear the prompt's list for this call. ``config`` merges per key.
    """
    opts = PromptGenerateOptions(
        model=model,
        config=config,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice,
        docs=docs,
        use=use,
        max_turns=max_turns,
        context=context,
        return_tool_requests=return_tool_requests,
        resume_respond=resume_respond,
        resume_restart=resume_restart,
        resume_metadata=resume_metadata,
    )
    return await self._run(input=input, opts=opts, on_chunk=on_chunk, caller_stopped=None)

__init__(ai, *, variant=None, model=None, config=None, description=None, input_schema=None, input_default=None, system=None, prompt=None, messages=None, output_format=None, output_content_type=None, output_instructions=None, output_schema=None, output_constrained=None, max_turns=None, return_tool_requests=None, metadata=None, tools=None, tool_choice=None, use=None, docs=None, name=None, ns=None)

Initialize prompt with configuration, templates, and schema options.

Source code in packages/genkit/src/genkit/_ai/_prompt.py
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
def __init__(
    self,
    ai: _aio.Genkit,
    *,
    variant: str | None = None,
    model: ModelArg | Action | None = None,
    config: Mapping[str, Any] | BaseModel | None = None,
    description: str | None = None,
    input_schema: type | dict[str, Any] | str | None = None,
    input_default: dict[str, Any] | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_schema: type | dict[str, Any] | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, Any] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    name: str | None = None,
    ns: str | None = None,
) -> None:
    """Initialize prompt with configuration, templates, and schema options."""
    self._ai = ai
    # Keys the caller leaves out take these values before the template runs.
    self._input_default = dict(input_default) if input_default else None
    # Set when a lookup also passed input_schema=; the file's schema still
    # has to pass so a required file field can't slip through.
    self._file_input_schema: type | dict[str, Any] | str | None = None
    # Identity: how the prompt is registered and looked up. Not part of _def,
    # which only holds what goes into a generate.
    self._name = name
    self._ns = ns
    self._variant = variant
    self._description = description
    # The whole definition as one value. Per-call overrides layer over it
    # in prepare_prompt via with_overrides; nothing mutates it after define
    # except _ensure_resolved swapping in a lazily loaded definition.
    self._def = GenerateCall(
        model=model,
        config=config,
        input_schema=input_schema,
        system=system,
        prompt=prompt,
        messages=messages,
        output_format=output_format,
        output_content_type=output_content_type,
        output_instructions=output_instructions,
        output_schema=output_schema,
        output_constrained=output_constrained,
        max_turns=max_turns,
        return_tool_requests=return_tool_requests,
        metadata=metadata,
        tools=tools,
        tool_choice=tool_choice,
        use=use,
        docs=docs,
    )
    # Compiled system/messages/prompt templates, filled on first render and reused.
    self._compiled_templates: PromptCache = PromptCache()
    self._prompt_action: Action | None = None
    define_name, define_schema = config_schema_at_define(model=model, registry=ai._registry)
    # Hop identity is what we knew at define time, not today's defaultModel.
    # Not a GenerateCall field, so _ensure_resolved copies it explicitly.
    self._defined_model_name = define_name
    assert_correct_config_class(config=config, schema=define_schema, model=define_name)

render(input=None, *, model=None, config=None, messages=None, tools=None, tool_choice=None, docs=None, use=None, max_turns=None, context=None, return_tool_requests=None, resume_respond=None, resume_restart=None, resume_metadata=None) async

Render the prompt without running it. Same keywords as __call__, minus on_chunk.

Source code in packages/genkit/src/genkit/_ai/_prompt.py
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
async def render(
    self,
    input: InputT | dict[str, Any] | None = None,
    *,
    model: ModelArg | Action | None = None,
    config: Mapping[str, Any] | BaseModel | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    docs: list[Document] | None = None,
    use: Sequence[Middleware] | None = None,
    max_turns: int | None = None,
    context: dict[str, Any] | None = None,
    return_tool_requests: bool | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
) -> GenerateActionOptions:
    """Render the prompt without running it. Same keywords as ``__call__``, minus ``on_chunk``."""
    opts = PromptGenerateOptions(
        model=model,
        config=config,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice,
        docs=docs,
        use=use,
        max_turns=max_turns,
        context=context,
        return_tool_requests=return_tool_requests,
        resume_respond=resume_respond,
        resume_restart=resume_restart,
        resume_metadata=resume_metadata,
    )
    return (await render_prompt(prompt=self, input=input, opts=opts)).options

stream(input=None, *, model=None, config=None, messages=None, tools=None, tool_choice=None, docs=None, use=None, max_turns=None, context=None, return_tool_requests=None, resume_respond=None, resume_restart=None, resume_metadata=None)

Stream the prompt execution. Same keywords as __call__, minus on_chunk.

Iterate .stream on the returned response for chunks; there's no callback here so chunks only arrive one way.

Source code in packages/genkit/src/genkit/_ai/_prompt.py
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
def stream(
    self,
    input: InputT | dict[str, Any] | None = None,
    *,
    model: ModelArg | Action | None = None,
    config: Mapping[str, Any] | BaseModel | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    docs: list[Document] | None = None,
    use: Sequence[Middleware] | None = None,
    max_turns: int | None = None,
    context: dict[str, Any] | None = None,
    return_tool_requests: bool | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
) -> ModelStreamResponse[OutputT]:
    """Stream the prompt execution. Same keywords as ``__call__``, minus ``on_chunk``.

    Iterate ``.stream`` on the returned response for chunks; there's no
    callback here so chunks only arrive one way.
    """
    opts = PromptGenerateOptions(
        model=model,
        config=config,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice,
        docs=docs,
        use=use,
        max_turns=max_turns,
        context=context,
        return_tool_requests=return_tool_requests,
        resume_respond=resume_respond,
        resume_restart=resume_restart,
        resume_metadata=resume_metadata,
    )

    # Same run path as __call__; only the chunk sink differs.
    async def run(
        send_chunk: Callable[[ModelResponseChunk[OutputT]], None],
        caller_stopped: asyncio.Event,
    ) -> ModelResponse[OutputT]:
        return await self._run(
            input=input,
            opts=opts,
            on_chunk=lambda c: send_chunk(cast('ModelResponseChunk[OutputT]', c)),
            caller_stopped=caller_stopped,
        )

    initial_msgs = list(messages) if isinstance(messages, list) else []
    stream, task = start_generate_stream(initial_messages=initial_msgs, run=run)
    return ModelStreamResponse[OutputT](stream=stream, response=task)

PublicError

Bases: genkit._core._error.GenkitError

Error class for issues to be returned to users.

Using this error allows a web framework handler (e.g. FastAPI, Flask) to know it is safe to return the message, details, and HTTP status in a request. Any other GenkitError is 500 Internal Error on the wire.

Source code in packages/genkit/src/genkit/_core/_error.py
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
class PublicError(GenkitError):
    """Error class for issues to be returned to users.

    Using this error allows a web framework handler (e.g. FastAPI, Flask) to know it
    is safe to return the message, details, and HTTP status in a request. Any
    other GenkitError is 500 Internal Error on the wire.
    """

    def __init__(
        self,
        status: StatusName,
        message: str,
        details: Any = None,  # noqa: ANN401
        *,
        reason: ErrorReason | None = None,
    ) -> None:
        """Initialize a PublicError.

        Args:
            status: The status name for this error.
            message: The error message.
            details: Optional details to include.
            reason: Extra why when the failure has a stable classification;
                stored on ``details['reason']``.
        """
        super().__init__(status=status, message=message, details=details, reason=reason)

__init__(status, message, details=None, *, reason=None)

Initialize a PublicError.

Parameters:

Name Type Description Default
status genkit._core._error.StatusName

The status name for this error.

required
message str

The error message.

required
details typing.Any

Optional details to include.

None
reason genkit._core._error.ErrorReason | None

Extra why when the failure has a stable classification; stored on details['reason'].

None
Source code in packages/genkit/src/genkit/_core/_error.py
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
def __init__(
    self,
    status: StatusName,
    message: str,
    details: Any = None,  # noqa: ANN401
    *,
    reason: ErrorReason | None = None,
) -> None:
    """Initialize a PublicError.

    Args:
        status: The status name for this error.
        message: The error message.
        details: Optional details to include.
        reason: Extra why when the failure has a stable classification;
            stored on ``details['reason']``.
    """
    super().__init__(status=status, message=message, details=details, reason=reason)

Role

Bases: genkit._core._compat.StrEnum

Role data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
111
112
113
114
115
116
117
class Role(StrEnum):
    """Role data type class."""

    SYSTEM = 'system'
    USER = 'user'
    MODEL = 'model'
    TOOL = 'tool'

StreamResponse

Bases: typing.Generic[genkit._core._action.ChunkT_co, genkit._core._action.OutputT_co]

Chunks from a running action, then its result.

Returned by Action.stream() for every action kind: flows, tools, models, and the rest.

  • Chunks are single-pass. Once a loop has read them, a second async for yields nothing (or re-raises, if the run failed).
  • .response can be awaited any number of times, before or after iterating. Chunks sent before you iterate are buffered.
  • If the run raises, both the loop and .response raise it. ModelStreamResponse (generate_stream, prompt.stream) reports model failures on .response instead; see its docstring.
  • Closing before the run finishes (async with result: or await result.aclose()) stops the run and awaits finally: cleanup; .response then raises GenkitError with status CANCELLED (ModelStreamResponse resolves with finish_reason == ABORTED instead). A reader cancelled mid-async for (e.g. a client disconnect) also stops the run, and so does dropping a stream left unfinished after break. Not iterating at all leaves the run going. See Action.stream.
Example
@ai.flow
async def track_order(order_id: str, ctx: FlowContext[str]) -> str:
    ctx.send_chunk('Out for delivery')
    return f'Order {order_id} delivered'


result = track_order.stream('A-1042')
async for update in result.stream:
    print(update)
# => Out for delivery

print(await result.response)
# => Order A-1042 delivered
Source code in packages/genkit/src/genkit/_core/_action.py
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
class StreamResponse(Generic[ChunkT_co, OutputT_co]):
    """Chunks from a running action, then its result.

    Returned by ``Action.stream()`` for every action kind: flows, tools,
    models, and the rest.

    - Chunks are single-pass. Once a loop has read them, a second ``async for``
      yields nothing (or re-raises, if the run failed).
    - ``.response`` can be awaited any number of times, before or after
      iterating. Chunks sent before you iterate are buffered.
    - If the run raises, both the loop and ``.response`` raise it.
      ``ModelStreamResponse`` (``generate_stream``, ``prompt.stream``) reports
      model failures on ``.response`` instead; see its docstring.
    - Closing before the run finishes (``async with result:`` or
      ``await result.aclose()``) stops the run and awaits ``finally:`` cleanup;
      ``.response`` then raises
      ``GenkitError`` with status ``CANCELLED`` (``ModelStreamResponse``
      resolves with ``finish_reason == ABORTED`` instead). A reader cancelled
      mid-``async for`` (e.g. a client disconnect) also stops the run, and so
      does dropping a stream left unfinished after ``break``. Not iterating at
      all leaves the run going. See ``Action.stream``.

    Example:
        ```python
        @ai.flow
        async def track_order(order_id: str, ctx: FlowContext[str]) -> str:
            ctx.send_chunk('Out for delivery')
            return f'Order {order_id} delivered'


        result = track_order.stream('A-1042')
        async for update in result.stream:
            print(update)
        # => Out for delivery

        print(await result.response)
        # => Order A-1042 delivered
        ```
    """

    def __init__(
        self,
        stream: AsyncIterable[ChunkT_co],
        response: Awaitable[OutputT_co],
    ) -> None:
        self._stream: StoppableStream[ChunkT_co] = (
            stream if isinstance(stream, StoppableStream) else StoppableStream(chunks=stream, stop=None)
        )
        self._response = response
        self._action_name: str | None = None

    @property
    def stream(self) -> StoppableStream[ChunkT_co]:
        """The chunks, in order (``AsyncIterator``). Iterating the response itself reads the same stream."""
        return self._stream

    @property
    def response(self) -> Awaitable[OutputT_co]:
        """The final result, available once the run ends."""
        return self._response

    def __aiter__(self) -> StoppableStream[ChunkT_co]:
        # `async for chunk in result` reads `.stream`, so `aiter(result) is result.stream`.
        return self._stream

    async def aclose(self) -> None:
        """Close the stream and release any underlying resources."""
        aclose = getattr(self._stream, 'aclose', None)
        if aclose is not None:
            await aclose()

    async def __aenter__(self) -> Self:
        return self

    async def __aexit__(self, *exc: object) -> None:
        await self.aclose()

response property

The final result, available once the run ends.

stream property

The chunks, in order (AsyncIterator). Iterating the response itself reads the same stream.

aclose() async

Close the stream and release any underlying resources.

Source code in packages/genkit/src/genkit/_core/_action.py
294
295
296
297
298
async def aclose(self) -> None:
    """Close the stream and release any underlying resources."""
    aclose = getattr(self._stream, 'aclose', None)
    if aclose is not None:
        await aclose()

Tool

Bases: genkit._core._action.Action[genkit._core._tool.InputT, genkit._core._tool.OutputT, genkit._core._tool.ChunkT, None]

A tool the model can call: an :class:~genkit._core._action.Action of kind tool.

await tool(x) is (await tool.run(x)).response: what the function returned. A str comes back as the string, a Pydantic model as the instance, and response(...) as that MultipartToolResponse.

Each tool also carries a tool.v2 action that returns the MultipartToolResponse envelope. The registry stores both, like JS and Go; the Dev UI lists and runs the tool.v2 one.

Source code in packages/genkit/src/genkit/_core/_tool.py
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
class Tool(Action[InputT, OutputT, ChunkT, None]):
    """A tool the model can call: an :class:`~genkit._core._action.Action` of kind ``tool``.

    ``await tool(x)`` is ``(await tool.run(x)).response``: what the function
    returned. A ``str`` comes back as the string, a Pydantic model as the
    instance, and ``response(...)`` as that ``MultipartToolResponse``.

    Each tool also carries a ``tool.v2`` action that returns the
    ``MultipartToolResponse`` envelope. The registry stores both, like JS and
    Go; the Dev UI lists and runs the ``tool.v2`` one.
    """

    _wire_action: Action[InputT, MultipartToolResponse[Any], ChunkT, None] | None

    # One overload per handler shape, same as ``ai.tool`` / ``define_tool``, so
    # ``Tool(place_order)`` infers ``Tool[Order, Receipt, Step]`` from the function.
    @overload
    def __init__(
        self: Tool[Any, _O, _C],
        func: Callable[[ToolContext[_C], object], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    # The defaulted-input shapes are self-typed to DefaultedTool, so they
    # apply when define_tool builds one. Tool(fn) itself stays a Tool and
    # skips them. `(x = ..., ctx = None)` also fits (input, ctx); catch it first.
    @overload
    def __init__(
        self: DefaultedTool[_I, _O, _C],
        func: DefaultInputCtxFn[ToolContext[_C], _I, _O],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[_I, _O, _C],
        func: Callable[[_I, ToolContext[_C]], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: DefaultedTool[_I, _O, _C],
        func: CtxDefaultInputFn[ToolContext[_C], _I, _O],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[_I, _O, _C],
        func: Callable[[ToolContext[_C], _I], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[Any, _O, Any],
        func: Callable[[object], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[None, _O, _C],
        func: Callable[[ToolContext[_C]], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: DefaultedTool[_I, _O, Any],
        func: DefaultInputFn[_I, _O],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[_I, _O, Any],
        func: Callable[[_I], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self: Tool[None, _O, Any],
        func: Callable[[], Awaitable[_O]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None: ...

    def __init__(
        self,
        func: Callable[..., Awaitable[Any]],
        *,
        name: str | None = None,
        description: str | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
    ) -> None:
        """Build a tool from an async function without registering it.

        ``define_tool`` / ``@ai.tool`` register it. Passed straight to
        ``generate(tools=[...])``, it is an ephemeral tool for that call.

        Args:
            func: Async tool implementation. It takes at most one input,
                annotated with a type that has a JSON schema, plus an optional
                ``ToolContext`` parameter.
            name: Tool name for the model. Defaults to ``func.__name__``.
            description: Sent to the model. Defaults to the function docstring.
            input_schema: Optional input schema override (Pydantic model or JSON-schema dict).

        Raises:
            TypeError: If ``func`` is not a coroutine function, takes more than one input,
                or its input has no annotation or no JSON schema.
            ValueError: If no ``name`` is given and ``func`` has no ``__name__``.

        Example:
            from genkit import Tool

            async def lookup_price(sku: str) -> str:
                return '12.00'

            ephemeral = Tool(lookup_price, name='lookup_price')
            res = await ai.generate(prompt='Price of SKU-1?', tools=[ephemeral])
        """
        # A callable instance with `async def __call__` is async too.
        if not (inspect.iscoroutinefunction(func) or inspect.iscoroutinefunction(type(func).__call__)):
            raise TypeError(f'Tool function must be async. Got sync function: {getattr(func, "__name__", repr(func))}')
        tool_name = name if name is not None else getattr(func, '__name__', None)
        if tool_name is None:
            raise ValueError(f'Cannot infer a tool name from {func!r}; pass name= explicitly.')
        tool_description = get_func_description(func, description)
        typed_func: Callable[..., Awaitable[OutputT]] = func
        self._wire_action = None

        async def tool_fn(raw_input: object, ctx: ActionContext[Any]) -> OutputT:
            return await call_tool_fn(self, typed_func, raw_input, ctx)

        super().__init__(
            kind=ActionKind.TOOL,
            name=tool_name,
            fn=tool_fn,
            metadata_fn=func,
            description=tool_description,
            input_schema=input_schema,
        )
        model_schema = model_schema_from_return_annotation(func, inferred=self.output_schema)
        self.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = model_schema

        async def wire_fn(raw_input: object, ctx: ActionContext[Any]) -> MultipartToolResponse[Any]:
            raw = await call_tool_fn(self, typed_func, raw_input, ctx)
            return as_multipart_tool_response(raw, tool_name=self.name)

        wire: Action[InputT, MultipartToolResponse[Any], ChunkT, None] = Action(
            kind=ActionKind.TOOL_V2,
            name=tool_name,
            fn=wire_fn,
            metadata_fn=func,
            description=tool_description,
            input_schema=input_schema,
        )
        wire.output_schema = TypeAdapter(MultipartToolResponseData).json_schema()
        wire.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = model_schema
        self._wire_action = wire

    @classmethod
    def from_action(cls, action: Action[InputT, OutputT, ChunkT, Any]) -> Tool[InputT, OutputT, ChunkT]:
        """View a tool ``Action`` that wasn't built as a ``Tool`` (plugin, DAP, hand-registered) as one.

        Shares the action's function and metadata; there is no ``tool.v2`` companion.
        """
        if isinstance(action, Tool):
            return cast(Tool[InputT, OutputT, ChunkT], action)  # pyrefly: ignore[redundant-cast] - ty needs it
        return _ActionTool(action)

    @property
    def model_output_schema(self) -> dict[str, object] | None:
        """JSON Schema the model binds as this tool's ``outputSchema``."""
        if ORIGINAL_OUTPUT_SCHEMA_KEY in self.metadata:
            original = self.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY]
            return cast(dict[str, object], original) if isinstance(original, dict) else None
        return self.output_schema

    @model_output_schema.setter
    def model_output_schema(self, value: dict[str, object] | None) -> None:
        self._metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = value
        if self._wire_action is not None:
            self._wire_action.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = value

    @property
    def wire_action(self) -> Action[InputT, MultipartToolResponse[Any], ChunkT, None] | None:
        """The ``tool.v2`` action: same function, returns the ``MultipartToolResponse`` envelope.

        The registry stores it next to the tool under ``/tool.v2/<name>``; the
        Dev UI and other wire consumers run it. ``None`` for a ``Tool`` viewed
        from a plain action.
        """
        return self._wire_action

    def definition(self) -> ToolDefinition:
        """Return the wire-format ToolDefinition for this tool.

        ``output_schema`` is what the model binds: ``T`` for ``-> T`` and for
        ``-> MultipartToolResponse[T]``, ``None`` for a bare
        ``-> MultipartToolResponse``.
        """
        return ToolDefinition(
            name=self.name,
            description=self.description or '',
            input_schema=self.input_schema,
            output_schema=self.model_output_schema,
        )

    async def _invoke(self, input: object | None, ctx: ActionContext) -> OutputT:
        """Run the function, then check its result the way generate would send it to a model.

        A value the model couldn't receive (unserializable output or metadata,
        a part with no payload) raises ``INVALID_ARGUMENT`` on every call path,
        not just inside ``generate``. The function's own value is returned.
        """
        output = await super()._invoke(input, ctx)
        as_multipart_tool_response(output, tool_name=self.name)
        return output

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

model_output_schema property writable

JSON Schema the model binds as this tool's outputSchema.

params property

The function's input and context parameters, as Genkit passes them.

wire_action property

The tool.v2 action: same function, returns the MultipartToolResponse envelope.

The registry stores it next to the tool under /tool.v2/<name>; the Dev UI and other wire consumers run it. None for a Tool viewed from a plain action.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

__init__(func, *, name=None, description=None, input_schema=None)

__init__(
    func: Callable[
        [ToolContext[_C], object], Awaitable[_O]
    ],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: DefaultInputCtxFn[ToolContext[_C], _I, _O],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[_I, ToolContext[_C]], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: CtxDefaultInputFn[ToolContext[_C], _I, _O],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[ToolContext[_C], _I], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[object], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[ToolContext[_C]], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: DefaultInputFn[_I, _O],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[_I], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None
__init__(
    func: Callable[[], Awaitable[_O]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> None

Build a tool from an async function without registering it.

define_tool / @ai.tool register it. Passed straight to generate(tools=[...]), it is an ephemeral tool for that call.

Parameters:

Name Type Description Default
func collections.abc.Callable[..., collections.abc.Awaitable[typing.Any]]

Async tool implementation. It takes at most one input, annotated with a type that has a JSON schema, plus an optional ToolContext parameter.

required
name str | None

Tool name for the model. Defaults to func.__name__.

None
description str | None

Sent to the model. Defaults to the function docstring.

None
input_schema type[pydantic.BaseModel] | dict[str, object] | None

Optional input schema override (Pydantic model or JSON-schema dict).

None

Raises:

Type Description
TypeError

If func is not a coroutine function, takes more than one input, or its input has no annotation or no JSON schema.

ValueError

If no name is given and func has no __name__.

Example

from genkit import Tool

async def lookup_price(sku: str) -> str: return '12.00'

ephemeral = Tool(lookup_price, name='lookup_price') res = await ai.generate(prompt='Price of SKU-1?', tools=[ephemeral])

Source code in packages/genkit/src/genkit/_core/_tool.py
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
def __init__(
    self,
    func: Callable[..., Awaitable[Any]],
    *,
    name: str | None = None,
    description: str | None = None,
    input_schema: type[BaseModel] | dict[str, object] | None = None,
) -> None:
    """Build a tool from an async function without registering it.

    ``define_tool`` / ``@ai.tool`` register it. Passed straight to
    ``generate(tools=[...])``, it is an ephemeral tool for that call.

    Args:
        func: Async tool implementation. It takes at most one input,
            annotated with a type that has a JSON schema, plus an optional
            ``ToolContext`` parameter.
        name: Tool name for the model. Defaults to ``func.__name__``.
        description: Sent to the model. Defaults to the function docstring.
        input_schema: Optional input schema override (Pydantic model or JSON-schema dict).

    Raises:
        TypeError: If ``func`` is not a coroutine function, takes more than one input,
            or its input has no annotation or no JSON schema.
        ValueError: If no ``name`` is given and ``func`` has no ``__name__``.

    Example:
        from genkit import Tool

        async def lookup_price(sku: str) -> str:
            return '12.00'

        ephemeral = Tool(lookup_price, name='lookup_price')
        res = await ai.generate(prompt='Price of SKU-1?', tools=[ephemeral])
    """
    # A callable instance with `async def __call__` is async too.
    if not (inspect.iscoroutinefunction(func) or inspect.iscoroutinefunction(type(func).__call__)):
        raise TypeError(f'Tool function must be async. Got sync function: {getattr(func, "__name__", repr(func))}')
    tool_name = name if name is not None else getattr(func, '__name__', None)
    if tool_name is None:
        raise ValueError(f'Cannot infer a tool name from {func!r}; pass name= explicitly.')
    tool_description = get_func_description(func, description)
    typed_func: Callable[..., Awaitable[OutputT]] = func
    self._wire_action = None

    async def tool_fn(raw_input: object, ctx: ActionContext[Any]) -> OutputT:
        return await call_tool_fn(self, typed_func, raw_input, ctx)

    super().__init__(
        kind=ActionKind.TOOL,
        name=tool_name,
        fn=tool_fn,
        metadata_fn=func,
        description=tool_description,
        input_schema=input_schema,
    )
    model_schema = model_schema_from_return_annotation(func, inferred=self.output_schema)
    self.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = model_schema

    async def wire_fn(raw_input: object, ctx: ActionContext[Any]) -> MultipartToolResponse[Any]:
        raw = await call_tool_fn(self, typed_func, raw_input, ctx)
        return as_multipart_tool_response(raw, tool_name=self.name)

    wire: Action[InputT, MultipartToolResponse[Any], ChunkT, None] = Action(
        kind=ActionKind.TOOL_V2,
        name=tool_name,
        fn=wire_fn,
        metadata_fn=func,
        description=tool_description,
        input_schema=input_schema,
    )
    wire.output_schema = TypeAdapter(MultipartToolResponseData).json_schema()
    wire.metadata[ORIGINAL_OUTPUT_SCHEMA_KEY] = model_schema
    self._wire_action = wire

definition()

Return the wire-format ToolDefinition for this tool.

output_schema is what the model binds: T for -> T and for -> MultipartToolResponse[T], None for a bare -> MultipartToolResponse.

Source code in packages/genkit/src/genkit/_core/_tool.py
478
479
480
481
482
483
484
485
486
487
488
489
490
def definition(self) -> ToolDefinition:
    """Return the wire-format ToolDefinition for this tool.

    ``output_schema`` is what the model binds: ``T`` for ``-> T`` and for
    ``-> MultipartToolResponse[T]``, ``None`` for a bare
    ``-> MultipartToolResponse``.
    """
    return ToolDefinition(
        name=self.name,
        description=self.description or '',
        input_schema=self.input_schema,
        output_schema=self.model_output_schema,
    )

from_action(action) classmethod

View a tool Action that wasn't built as a Tool (plugin, DAP, hand-registered) as one.

Shares the action's function and metadata; there is no tool.v2 companion.

Source code in packages/genkit/src/genkit/_core/_tool.py
444
445
446
447
448
449
450
451
452
@classmethod
def from_action(cls, action: Action[InputT, OutputT, ChunkT, Any]) -> Tool[InputT, OutputT, ChunkT]:
    """View a tool ``Action`` that wasn't built as a ``Tool`` (plugin, DAP, hand-registered) as one.

    Shares the action's function and metadata; there is no ``tool.v2`` companion.
    """
    if isinstance(action, Tool):
        return cast(Tool[InputT, OutputT, ChunkT], action)  # pyrefly: ignore[redundant-cast] - ty needs it
    return _ActionTool(action)

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

ToolContext

Bases: genkit._core._action.ActionContext[genkit._core._tool.ChunkT]

What a tool sees while it runs: request context, streaming, and resume state.

Annotate a tool parameter with it to receive it:

@ai.tool
async def check_allergens(dish: str, ctx: ToolContext) -> str:
    return 'resumed' if ctx.is_resumed() else ctx.context.get('user', 'guest')

ToolContext is not a FlowContext. A helper shared by a tool and a flow takes the union:

# 1. Read the caller's uid from either context
def user_id(ctx: FlowContext | ToolContext) -> str:
    return ctx.context['auth']['uid']

# 2. Call it from the tool
@ai.tool
async def list_allergies(guest: str, ctx: ToolContext) -> str:
    return f'{guest} ({user_id(ctx)}): shellfish'

await list_allergies('Ana', context={'auth': {'uid': 'diner-42'}})
# => 'Ana (diner-42): shellfish'

On a restart after an interrupt, is_resumed() is True and resumed_metadata is the dict passed to interrupt.restart(resumed_metadata=...), or {} when the restart carried none. On a first run, resumed_metadata is None. Check resumed_metadata is None so static type checkers narrow the dict:

@ai.tool
async def refund_order(order_id: str, ctx: ToolContext) -> str:
    # Interrupt is exported from genkit
    if ctx.resumed_metadata is None:
        raise Interrupt({'reason': 'needs approval'})
    approved = ctx.resumed_metadata.get('approved_by')
    return f'Refunded {order_id} (approved by {approved})'
Source code in packages/genkit/src/genkit/_core/_tool.py
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
class ToolContext(ActionContext[ChunkT]):
    """What a tool sees while it runs: request context, streaming, and resume state.

    Annotate a tool parameter with it to receive it:

        @ai.tool
        async def check_allergens(dish: str, ctx: ToolContext) -> str:
            return 'resumed' if ctx.is_resumed() else ctx.context.get('user', 'guest')

    ``ToolContext`` is not a ``FlowContext``. A helper shared by a tool and a
    flow takes the union:

        # 1. Read the caller's uid from either context
        def user_id(ctx: FlowContext | ToolContext) -> str:
            return ctx.context['auth']['uid']

        # 2. Call it from the tool
        @ai.tool
        async def list_allergies(guest: str, ctx: ToolContext) -> str:
            return f'{guest} ({user_id(ctx)}): shellfish'

        await list_allergies('Ana', context={'auth': {'uid': 'diner-42'}})
        # => 'Ana (diner-42): shellfish'

    On a restart after an interrupt, ``is_resumed()`` is ``True`` and
    ``resumed_metadata`` is the dict passed to
    ``interrupt.restart(resumed_metadata=...)``, or ``{}`` when the restart
    carried none. On a first run, ``resumed_metadata`` is ``None``. Check
    ``resumed_metadata is None`` so static type checkers narrow the dict:

        @ai.tool
        async def refund_order(order_id: str, ctx: ToolContext) -> str:
            # Interrupt is exported from genkit
            if ctx.resumed_metadata is None:
                raise Interrupt({'reason': 'needs approval'})
            approved = ctx.resumed_metadata.get('approved_by')
            return f'Refunded {order_id} (approved by {approved})'
    """

    def __init__(
        self,
        ctx: ActionContext[ChunkT],
        *,
        resumed_metadata: dict[str, Any] | None = None,
        original_input: Any = None,  # noqa: ANN401 - prior tool_request.input when replacing on restart
    ) -> None:
        """Initialize from the tool action's run context.

        Args:
            ctx: Parent action context
            resumed_metadata: Metadata from previous interrupt (if resumed)
            original_input: Original tool input before replacement (if resumed)
        """
        super().__init__(
            context=ctx.context,
            streaming_callback=ctx.streaming_callback,
        )
        self.resumed_metadata = resumed_metadata
        self.original_input = original_input

    def is_resumed(self) -> bool:
        """Return True if this run is a restart after an interrupt.

        Same as ``self.resumed_metadata is not None``. An empty ``{}`` still
        counts as resumed.
        """
        return self.resumed_metadata is not None

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

__init__(ctx, *, resumed_metadata=None, original_input=None)

Initialize from the tool action's run context.

Parameters:

Name Type Description Default
ctx genkit._core._action.ActionContext[genkit._core._tool.ChunkT]

Parent action context

required
resumed_metadata dict[str, typing.Any] | None

Metadata from previous interrupt (if resumed)

None
original_input typing.Any

Original tool input before replacement (if resumed)

None
Source code in packages/genkit/src/genkit/_core/_tool.py
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
def __init__(
    self,
    ctx: ActionContext[ChunkT],
    *,
    resumed_metadata: dict[str, Any] | None = None,
    original_input: Any = None,  # noqa: ANN401 - prior tool_request.input when replacing on restart
) -> None:
    """Initialize from the tool action's run context.

    Args:
        ctx: Parent action context
        resumed_metadata: Metadata from previous interrupt (if resumed)
        original_input: Original tool input before replacement (if resumed)
    """
    super().__init__(
        context=ctx.context,
        streaming_callback=ctx.streaming_callback,
    )
    self.resumed_metadata = resumed_metadata
    self.original_input = original_input

is_resumed()

Return True if this run is a restart after an interrupt.

Same as self.resumed_metadata is not None. An empty {} still counts as resumed.

Source code in packages/genkit/src/genkit/_core/_tool.py
218
219
220
221
222
223
224
def is_resumed(self) -> bool:
    """Return True if this run is a restart after an interrupt.

    Same as ``self.resumed_metadata is not None``. An empty ``{}`` still
    counts as resumed.
    """
    return self.resumed_metadata is not None

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

get_logger(name=None)

Return a logger whose lines also reach the Dev UI trace panel.

The logger has debug, info, warning, error and exception. Each takes an event string and keyword fields. Under genkit start, each line is also exported to the Dev UI with the active trace and span IDs.

Example
from genkit import Genkit, get_logger

# 1. Create a module logger
ai = Genkit()
logger = get_logger(__name__)


# 2. Log inside a flow; lines attach to the flow's trace
@ai.flow
async def lookup_menu(restaurant_id: str) -> int:
    logger.info('menu lookup', restaurant_id=restaurant_id, items=12)
    # => console: menu lookup  restaurant_id=r-42 items=12
    # => Dev UI:  same line, attached to the lookup_menu trace

    logger.debug('cache miss', restaurant_id=restaurant_id)
    # => console: nothing unless GENKIT_LOG=debug
    # => Dev UI:  cache miss, still exported under `genkit start`
    return 12
Source code in packages/genkit/src/genkit/_core/_logger.py
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
def get_logger(name: str | None = None) -> GenkitLogger:
    """Return a logger whose lines also reach the Dev UI trace panel.

    The logger has ``debug``, ``info``, ``warning``, ``error`` and
    ``exception``. Each takes an event string and keyword fields. Under
    ``genkit start``, each line is also exported to the Dev UI with the active
    trace and span IDs.

    Example:
        ```python
        from genkit import Genkit, get_logger

        # 1. Create a module logger
        ai = Genkit()
        logger = get_logger(__name__)


        # 2. Log inside a flow; lines attach to the flow's trace
        @ai.flow
        async def lookup_menu(restaurant_id: str) -> int:
            logger.info('menu lookup', restaurant_id=restaurant_id, items=12)
            # => console: menu lookup  restaurant_id=r-42 items=12
            # => Dev UI:  same line, attached to the lookup_menu trace

            logger.debug('cache miss', restaurant_id=restaurant_id)
            # => console: nothing unless GENKIT_LOG=debug
            # => Dev UI:  cache miss, still exported under `genkit start`
            return 12
        ```
    """
    app_bound = structlog.get_logger(name) if name is not None else structlog.get_logger()
    stderr_bound = cast(BindableLogger, structlog.wrap_logger(_StderrPrintLogger()))
    return cast(GenkitLogger, ExportTee(app_bound, stderr_bound=stderr_bound))

genkit.model

Model protocol types for plugin authors; application code should call :class:genkit.Genkit generate.

BackgroundModel

Bases: genkit._core._background.BackgroundAction[genkit._core._model.ModelRequest, genkit._core._model.ModelResponse]

A background model: start returns an Operation[ModelResponse].

Pass the handle to check until it's done. A finished job's output is a ModelResponse. label and config_schema are read back from the start action, so a model looked up from the registry has them too.

Source code in packages/genkit/src/genkit/_ai/_background_model.py
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
class BackgroundModel(BackgroundAction[ModelRequest, ModelResponse]):
    """A background model: ``start`` returns an ``Operation[ModelResponse]``.

    Pass the handle to ``check`` until it's done. A finished job's ``output``
    is a ``ModelResponse``. ``label`` and ``config_schema`` are read back from
    the start action, so a model looked up from the registry has them too.
    """

    _noun: ClassVar[str] = 'Background model'
    _cancel_unsupported_reason: ClassVar[ErrorReason | None] = ErrorReason.UNSUPPORTED_BY_MODEL

    label: str
    config_schema: type[BaseModel] | dict[str, Any] | None

    def __init__(
        self,
        name: str,
        start: StartModelOpFn,
        check: CheckModelOpFn,
        *,
        cancel: CancelModelOpFn | None = None,
        label: str | None = None,
        info: ModelInfo | None = None,
        config_schema: type[BaseModel] | dict[str, Any] | None = None,
        metadata: dict[str, Any] | None = None,
        description: str | None = None,
    ) -> None:
        """Build a background model without registering it.

        Plugin ``init`` / ``resolve`` return this; ``define_background_model``
        registers the start, check, and cancel actions.
        """
        model_meta: dict[str, Any] = metadata.copy() if metadata else {}
        model_options: dict[str, Any] = {}
        if info:
            model_options.update(info.model_dump(by_alias=True, exclude_none=True))

        # generate_operation looks at this flag. A background model is a
        # poll-handle model, so the flag is set when the action is built.
        supports = model_options.get('supports')
        supports = dict(supports) if isinstance(supports, dict) else {}
        supports['longRunning'] = True
        model_options['supports'] = supports

        resolved_label = label or model_options.get('label') or name
        model_options['label'] = resolved_label
        if config_schema:
            model_options['customOptions'] = custom_options_schema(config_schema)
        model_meta['model'] = model_options

        start_action, check_action, cancel_action = operation_actions(
            type(self),
            name,
            kind=ActionKind.BACKGROUND_MODEL,
            start=start,
            check=check,
            cancel=cancel,
            metadata=model_meta,
            description=description or f'Background model: {resolved_label}',
            label=resolved_label,
            config_schema=config_schema,
        )
        # Annotation only: the Dev UI form comes from ModelRequest[Cfg]. Start,
        # check and cancel share this dict, so all three see it.
        if 'customOptions' not in model_options and start_action.config_schema is not None:
            model_options['customOptions'] = custom_options_schema(start_action.config_schema)
        # BackgroundAction.__init__ takes no model options; build, then bind.
        self._bind(start_action, check_action, cancel_action)

    def _bind(self, start: Action, check: Action, cancel: Action | None) -> None:
        super()._bind(start, check, cancel)
        model_meta = start.metadata.get('model')
        label = cast(dict[str, object], model_meta).get('label') if isinstance(model_meta, dict) else None
        self.label = label if isinstance(label, str) and label else start.name
        self.config_schema = start.config_schema

    def _require_handle(self, value: object) -> Operation[ModelResponse]:
        reject_model_response(value)
        return super()._require_handle(value)

    async def start(
        self,
        input: ModelRequest | None = None,  # noqa: A002
        *,
        context: dict[str, Any] | None = None,
    ) -> Operation[ModelResponse]:
        """Start a background operation.

        Args:
            input: The input request.
            context: Optional run context. Per-request keys go in
                ``context['secrets']``.

        Returns:
            An Operation with an ID to track the job.
        """
        return await super().start(input, context=context)

actions property

The start, check and (if any) cancel actions, for registering or listing.

A background action is three registered actions, not one. Register all of them, or a poll fails later with the check action not found.

input_schema property

The start action's input JSON schema.

kind property

The action kind of the start action.

metadata property

The start action's metadata.

name property

The name of the start action.

output_schema property

The start action's output JSON schema (the Operation).

supports_cancel property

Whether this background action supports cancellation.

__init__(name, start, check, *, cancel=None, label=None, info=None, config_schema=None, metadata=None, description=None)

Build a background model without registering it.

Plugin init / resolve return this; define_background_model registers the start, check, and cancel actions.

Source code in packages/genkit/src/genkit/_ai/_background_model.py
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
def __init__(
    self,
    name: str,
    start: StartModelOpFn,
    check: CheckModelOpFn,
    *,
    cancel: CancelModelOpFn | None = None,
    label: str | None = None,
    info: ModelInfo | None = None,
    config_schema: type[BaseModel] | dict[str, Any] | None = None,
    metadata: dict[str, Any] | None = None,
    description: str | None = None,
) -> None:
    """Build a background model without registering it.

    Plugin ``init`` / ``resolve`` return this; ``define_background_model``
    registers the start, check, and cancel actions.
    """
    model_meta: dict[str, Any] = metadata.copy() if metadata else {}
    model_options: dict[str, Any] = {}
    if info:
        model_options.update(info.model_dump(by_alias=True, exclude_none=True))

    # generate_operation looks at this flag. A background model is a
    # poll-handle model, so the flag is set when the action is built.
    supports = model_options.get('supports')
    supports = dict(supports) if isinstance(supports, dict) else {}
    supports['longRunning'] = True
    model_options['supports'] = supports

    resolved_label = label or model_options.get('label') or name
    model_options['label'] = resolved_label
    if config_schema:
        model_options['customOptions'] = custom_options_schema(config_schema)
    model_meta['model'] = model_options

    start_action, check_action, cancel_action = operation_actions(
        type(self),
        name,
        kind=ActionKind.BACKGROUND_MODEL,
        start=start,
        check=check,
        cancel=cancel,
        metadata=model_meta,
        description=description or f'Background model: {resolved_label}',
        label=resolved_label,
        config_schema=config_schema,
    )
    # Annotation only: the Dev UI form comes from ModelRequest[Cfg]. Start,
    # check and cancel share this dict, so all three see it.
    if 'customOptions' not in model_options and start_action.config_schema is not None:
        model_options['customOptions'] = custom_options_schema(start_action.config_schema)
    # BackgroundAction.__init__ takes no model options; build, then bind.
    self._bind(start_action, check_action, cancel_action)

__init_subclass__(**kwargs)

Read InT / OutT off class X(BackgroundAction[In, Out]).

Source code in packages/genkit/src/genkit/_core/_background.py
234
235
236
237
238
239
240
241
242
243
def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
    """Read InT / OutT off ``class X(BackgroundAction[In, Out])``."""
    super().__init_subclass__(**kwargs)
    for base in getattr(cls, '__orig_bases__', ()):
        origin = get_origin(base)
        if isinstance(origin, type) and issubclass(origin, BackgroundAction):
            args = get_args(base)
            if len(args) == 2:
                cls._input_type = _concrete_type(args[0])
                cls._output_type = _concrete_type(args[1])

cancel(operation, *, context=None) async

Cancel a background operation.

Parameters:

Name Type Description Default
operation genkit._core._operation.Operation | collections.abc.Mapping[str, typing.Any]

The operation to cancel, or the dict a stored one dumped to.

required
context dict[str, typing.Any] | None

Optional run context (secrets, folded client config).

None

Raises:

Type Description
genkit._core._error.GenkitError

UNIMPLEMENTED if this action does not implement cancel, INVALID_ARGUMENT if operation is not an Operation or a dict that validates as one.

Source code in packages/genkit/src/genkit/_core/_background.py
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
async def cancel(
    self,
    operation: Operation | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
) -> Operation[OutT]:
    """Cancel a background operation.

    Args:
        operation: The operation to cancel, or the dict a stored one
            dumped to.
        context: Optional run context (secrets, folded client config).

    Raises:
        GenkitError: UNIMPLEMENTED if this action does not implement
            cancel, INVALID_ARGUMENT if ``operation`` is not an
            ``Operation`` or a dict that validates as one.
    """
    operation = self._require_handle(operation)
    # Raising here is deliberate: returning the operation unchanged would
    # make "can't cancel" indistinguishable from "cancelled".
    if self.cancel_action is None:
        raise GenkitError(
            status='UNIMPLEMENTED',
            message=f'{self._noun} {operation.action} does not support cancellation.',
            reason=self._cancel_unsupported_reason,
        )
    result = await self.cancel_action.run(operation, context=context)
    return self._ensure_operation(response=result.response, name=self.cancel_action.name)

check(operation, *, context=None) async

Check the status of a background operation.

Parameters:

Name Type Description Default
operation genkit._core._operation.Operation | collections.abc.Mapping[str, typing.Any]

The operation to check, or the dict a stored one dumped to.

required
context dict[str, typing.Any] | None

Optional run context (secrets, folded client config).

None

Raises:

Type Description
genkit._core._error.GenkitError

INVALID_ARGUMENT if operation is not an Operation or a dict that validates as one.

Source code in packages/genkit/src/genkit/_core/_background.py
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
async def check(
    self,
    operation: Operation | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
) -> Operation[OutT]:
    """Check the status of a background operation.

    Args:
        operation: The operation to check, or the dict a stored one
            dumped to.
        context: Optional run context (secrets, folded client config).

    Raises:
        GenkitError: INVALID_ARGUMENT if ``operation`` is not an
            ``Operation`` or a dict that validates as one.
    """
    operation = self._require_handle(operation)
    result = await self.check_action.run(operation, context=context)
    return self._ensure_operation(response=result.response, name=self.check_action.name)

lookup(registry, key) async classmethod

Look up a background action by its start action key.

Matches JS lookupBackgroundAction. The key format is /{actionType}/{name}, e.g. /background-model/video-gen.

Source code in packages/genkit/src/genkit/_core/_background.py
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
@classmethod
async def lookup(cls, registry: Registry, key: str) -> Self | None:
    """Look up a background action by its start action key.

    Matches JS ``lookupBackgroundAction``. The key format is
    ``/{actionType}/{name}``, e.g. ``/background-model/video-gen``.
    """
    start_action = await registry.resolve_action_by_key(key)
    if start_action is None:
        return None
    # JS: const actionName = key.substring(key.indexOf('/', 1) + 1);
    parts = key.split('/', 2)  # ['', 'background-model', 'name']
    if len(parts) < 3:
        return None
    action_name = parts[2]
    check_action = await registry.resolve_action_by_key(f'/{ActionKind.CHECK_OPERATION}/{action_name}/check')
    if check_action is None:
        return None
    cancel_action = await registry.resolve_action_by_key(f'/{ActionKind.CANCEL_OPERATION}/{action_name}/cancel')
    return cls._from_actions(start_action, check_action, cancel_action)

start(input=None, *, context=None) async

Start a background operation.

Parameters:

Name Type Description Default
input genkit._core._model.ModelRequest | None

The input request.

None
context dict[str, typing.Any] | None

Optional run context. Per-request keys go in context['secrets'].

None

Returns:

Type Description
genkit._core._operation.Operation[genkit._core._model.ModelResponse]

An Operation with an ID to track the job.

Source code in packages/genkit/src/genkit/_ai/_background_model.py
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
async def start(
    self,
    input: ModelRequest | None = None,  # noqa: A002
    *,
    context: dict[str, Any] | None = None,
) -> Operation[ModelResponse]:
    """Start a background operation.

    Args:
        input: The input request.
        context: Optional run context. Per-request keys go in
            ``context['secrets']``.

    Returns:
        An Operation with an ID to track the job.
    """
    return await super().start(input, context=context)

ConstrainedSupport

Bases: genkit._core._compat.StrEnum

Constrained generation support (none, all, no-tools).

Source code in packages/genkit/src/genkit/_core/_typing.py
1226
1227
1228
1229
1230
1231
class ConstrainedSupport(StrEnum):
    """Constrained generation support (none, all, no-tools)."""

    NONE = 'none'
    ALL = 'all'
    NO_TOOLS = 'no-tools'

GenerateActionOptions

Bases: genkit._core._base.GenkitModel

Generate options with messages as list[Message] for type-safe use with ai.generate().

Source code in packages/genkit/src/genkit/_core/_model.py
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
class GenerateActionOptions(GenkitModel):
    """Generate options with messages as list[Message] for type-safe use with ai.generate()."""

    model: str | None = None
    messages: list[Message]
    docs: list[Document] | None = None
    tools: list[str] | None = None
    resources: list[str] | None = None
    tool_choice: ToolChoice | None = None
    config: Any | None = Field(default=None)
    output: GenerateActionOutputConfig | None = None
    resume: Resume | None = None
    return_tool_requests: bool | None = None
    max_turns: float | None = None
    step_name: str | None = None
    use: list[MiddlewareRef] | None = None

    @field_validator('max_turns', mode='before')
    @classmethod
    def _check_max_turns(cls, v: object) -> object:
        check_max_turns(v)
        return v

    @field_validator('messages', mode='before')
    @classmethod
    def _wrap_messages(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_message(m) for m in v]

    @field_validator('docs', mode='before')
    @classmethod
    def _wrap_docs(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_document(d) for d in v]

    @field_validator('resume', mode='before')
    @classmethod
    def _wrap_resume(cls, v: object) -> object:
        if v is None:
            return v
        return as_resume(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

GenerationUsage

Bases: genkit._core._base.GenkitModel

Model for generationusage data.

Source code in packages/genkit/src/genkit/_core/_typing.py
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
class GenerationUsage(GenkitModel):
    """Model for generationusage data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    input_tokens: float | None = None
    output_tokens: float | None = None
    total_tokens: float | None = None
    input_characters: float | None = None
    output_characters: float | None = None
    input_images: float | None = None
    output_images: float | None = None
    input_videos: float | None = None
    output_videos: float | None = None
    input_audio_files: float | None = None
    output_audio_files: float | None = None
    custom: Custom | None = None
    thoughts_tokens: float | None = None
    cached_content_tokens: float | None = None
    cache_write_tokens: float | None = None

    @classmethod
    def from_messages(cls, messages: Sequence[_model.Message], response: _model.Message) -> GenerationUsage:
        """Character and media counts for the request messages and the model reply."""
        from genkit._core._model import count_message_usage  # noqa: PLC0415 - _model imports this module

        return cls.model_validate(count_message_usage(messages, response))

from_messages(messages, response) classmethod

Character and media counts for the request messages and the model reply.

Source code in packages/genkit/src/genkit/_core/_typing.py
567
568
569
570
571
572
@classmethod
def from_messages(cls, messages: Sequence[_model.Message], response: _model.Message) -> GenerationUsage:
    """Character and media counts for the request messages and the model reply."""
    from genkit._core._model import count_message_usage  # noqa: PLC0415 - _model imports this module

    return cls.model_validate(count_message_usage(messages, response))

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Model

Bases: genkit._core._action.Action[genkit._core._model.ModelRequest, genkit._core._model.ModelResponse, genkit._core._model.ModelResponseChunk]

A model action returned from a plugin's init / resolve / list_actions or define_model.

Plugin init / resolve / list_actions return this without registering it; define_model registers it. The config class stays on the action so generate(model='name', config=...) can isinstance-check a Pydantic instance against a string model name. It comes from config_schema or the fn's ModelRequest[Cfg] annotation; given both, they must be the same class.

Source code in packages/genkit/src/genkit/_ai/_model.py
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
class Model(Action[ModelRequest, ModelResponse, ModelResponseChunk]):
    """A model action returned from a plugin's ``init`` / ``resolve`` / ``list_actions`` or ``define_model``.

    Plugin ``init`` / ``resolve`` / ``list_actions`` return this without registering it;
    ``define_model`` registers it.
    The config class stays on the action so ``generate(model='name', config=...)``
    can ``isinstance``-check a Pydantic instance against a string model name.
    It comes from ``config_schema`` or the fn's ``ModelRequest[Cfg]``
    annotation; given both, they must be the same class.
    """

    @overload
    def __init__(
        self,
        name: str,
        fn: ModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        name: str,
        fn: CtxFirstModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> None: ...

    def __init__(
        self,
        name: str,
        fn: ModelFn | CtxFirstModelFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: ModelInfo | None = None,
        description: str | None = None,
    ) -> None:
        """Build a model action."""
        model_options = _model_options(name=name, info=info, config_schema=config_schema, metadata=metadata)
        model_meta: dict[str, object] = metadata.copy() if metadata else {}
        model_meta['model'] = model_options
        config_class = python_config_schema(config_schema)
        # Built at runtime, so checkers can't read ``ModelRequest[config_class]`` as a type.
        request_type = cast(Any, ModelRequest)[config_class] if config_class is not None else ModelRequest
        super().__init__(
            kind=ActionKind.MODEL,
            name=name,
            # An unannotated request parameter would get the raw JSON dict from
            # a Dev UI or CLI run; give it ModelRequest (typed by config_schema
            # when there is one), like Embedder does.
            fn=with_request_annotation(fn, request_type, kind=ActionKind.MODEL),
            metadata=model_meta,
            description=get_func_description(fn, description),
            config_schema=config_schema,
            _io_schemas=_model_io_schemas(),
        )
        # Annotation only: the Dev UI form comes from ModelRequest[Cfg].
        if 'customOptions' not in model_options and self.config_schema is not None:
            model_options['customOptions'] = custom_options_schema(self.config_schema)

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

__init__(name, fn, *, config_schema=None, metadata=None, info=None, description=None)

__init__(
    name: str,
    fn: ModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> None
__init__(
    name: str,
    fn: CtxFirstModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> None

Build a model action.

Source code in packages/genkit/src/genkit/_ai/_model.py
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
def __init__(
    self,
    name: str,
    fn: ModelFn | CtxFirstModelFn,
    *,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None,
) -> None:
    """Build a model action."""
    model_options = _model_options(name=name, info=info, config_schema=config_schema, metadata=metadata)
    model_meta: dict[str, object] = metadata.copy() if metadata else {}
    model_meta['model'] = model_options
    config_class = python_config_schema(config_schema)
    # Built at runtime, so checkers can't read ``ModelRequest[config_class]`` as a type.
    request_type = cast(Any, ModelRequest)[config_class] if config_class is not None else ModelRequest
    super().__init__(
        kind=ActionKind.MODEL,
        name=name,
        # An unannotated request parameter would get the raw JSON dict from
        # a Dev UI or CLI run; give it ModelRequest (typed by config_schema
        # when there is one), like Embedder does.
        fn=with_request_annotation(fn, request_type, kind=ActionKind.MODEL),
        metadata=model_meta,
        description=get_func_description(fn, description),
        config_schema=config_schema,
        _io_schemas=_model_io_schemas(),
    )
    # Annotation only: the Dev UI form comes from ModelRequest[Cfg].
    if 'customOptions' not in model_options and self.config_schema is not None:
        model_options['customOptions'] = custom_options_schema(self.config_schema)

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

ModelConfig

Bases: genkit._core._base.GenkitConfig

Settings every model understands, plus extra for provider-only ones.

Unknown keyword arguments raise, so ModelConfig(temprature=0.2) fails where it was typed instead of being sent or silently dropped. A per-request API key goes in context={'secrets': {'api_key': ...}}, not here.

Source code in packages/genkit/src/genkit/_core/_model.py
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
class ModelConfig(GenkitConfig):
    """Settings every model understands, plus ``extra`` for provider-only ones.

    Unknown keyword arguments raise, so ``ModelConfig(temprature=0.2)`` fails
    where it was typed instead of being sent or silently dropped. A
    per-request API key goes in ``context={'secrets': {'api_key': ...}}``, not
    here.
    """

    version: str | None = Field(default=None, description='Model version to call, for providers that pin one.')
    """Model version to call, for providers that pin one per request."""

    temperature: float | None = Field(default=None, description='Sampling temperature. Higher is more random.')
    """Sampling temperature. Higher is more random."""

    max_output_tokens: int | None = Field(default=None, description='Maximum number of tokens to generate.')
    """Upper bound on tokens in the reply."""

    top_k: int | None = Field(default=None, description='The maximum number of tokens to consider when sampling.')
    """Sample only from the k most likely tokens."""

    top_p: float | None = Field(
        default=None, description='The maximum cumulative probability of tokens to consider when sampling.'
    )
    """Sample from the smallest token set whose probability reaches p."""

    stop_sequences: list[str] | None = Field(default=None, description='Strings that end the reply when generated.')
    """Strings that end the reply when the model emits one."""

    common_field_bounds: ClassVar[Mapping[str, tuple[float, float]]] = {}
    """Inclusive ``(min, max)`` a provider allows for a numeric common field.

    A plugin narrows a common field here instead of re-declaring it. Values
    outside the range fail validation, and the Dev UI schema advertises the
    range as ``minimum``/``maximum``.

    Example:
        ```python
        class OpenAIConfig(ModelConfig):
            common_field_bounds = {'temperature': (0.0, 2.0), 'top_p': (0.0, 1.0)}


        OpenAIConfig(temperature=3.0)
        # => ValidationError: temperature must be between 0.0 and 2.0, got 3.0
        ```
    """

    _NUMERIC_COMMON_FIELDS: ClassVar[frozenset[str]] = frozenset({
        'temperature',
        'max_output_tokens',
        'top_k',
        'top_p',
    })

    @classmethod
    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
        """Reject ``common_field_bounds`` entries that name unknown fields or invert ``(min, max)``."""
        super().__pydantic_init_subclass__(**kwargs)
        for name, (low, high) in cls.common_field_bounds.items():
            if name not in cls._NUMERIC_COMMON_FIELDS:
                raise ValueError(
                    f'{cls.__name__}.common_field_bounds key {name!r} must be one of '
                    f'{sorted(cls._NUMERIC_COMMON_FIELDS)}'
                )
            if low > high:
                raise ValueError(f'{cls.__name__}.common_field_bounds[{name!r}] min {low} > max {high}')

    @field_validator('temperature', 'max_output_tokens', 'top_k', 'top_p')
    @classmethod
    def _check_common_field_bounds(cls, value: float | None, info: ValidationInfo) -> float | None:
        bounds = cls.common_field_bounds.get(info.field_name or '')
        if value is not None and bounds is not None and not bounds[0] <= value <= bounds[1]:
            # A custom error type keeps pydantic's 'Value error, ' prefix off the message.
            raise PydanticCustomError(
                'common_field_bounds',
                '{field} must be between {low} and {high}, got {value}',
                {'field': info.field_name, 'low': bounds[0], 'high': bounds[1], 'value': value},
            )
        return value

    @classmethod
    def __get_pydantic_json_schema__(cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler) -> JsonSchemaValue:
        """Advertise ``common_field_bounds`` on the matching schema properties."""
        json_schema = handler(core_schema)
        resolved = handler.resolve_ref_schema(json_schema)
        properties = resolved.get('properties')
        if isinstance(properties, dict):
            for name, (low, high) in cls.common_field_bounds.items():
                field = cls.model_fields.get(name)
                if field is None:
                    continue
                alias = field.alias
                prop = properties.get(alias) if alias in properties else properties.get(name)
                if isinstance(prop, dict):
                    prop['minimum'] = low
                    prop['maximum'] = high
        return json_schema

    extra: dict[str, Any] | None = None
    """Provider settings the model's config class doesn't declare, sent as-is.

    Keys are the provider's wire names. The plugin merges them into its
    request after the declared fields, so a colliding key wins. Fields Genkit
    builds from the request (messages, tools) are rejected rather than
    overwritten. Where the map lands depends on the provider: the request
    body for Gemini, OpenAI and Anthropic, ``options`` for Ollama, and
    ``additionalModelRequestFields`` for Bedrock chat models (the InvokeModel
    body for Bedrock image models).

    Keys aren't validated, except that an API key here raises like one at the
    top level: config travels with the request into traces. Don't put other
    secrets here either.
    """

common_field_bounds = {} class-attribute

Inclusive (min, max) a provider allows for a numeric common field.

A plugin narrows a common field here instead of re-declaring it. Values outside the range fail validation, and the Dev UI schema advertises the range as minimum/maximum.

Example
class OpenAIConfig(ModelConfig):
    common_field_bounds = {'temperature': (0.0, 2.0), 'top_p': (0.0, 1.0)}


OpenAIConfig(temperature=3.0)
# => ValidationError: temperature must be between 0.0 and 2.0, got 3.0

extra = None class-attribute instance-attribute

Provider settings the model's config class doesn't declare, sent as-is.

Keys are the provider's wire names. The plugin merges them into its request after the declared fields, so a colliding key wins. Fields Genkit builds from the request (messages, tools) are rejected rather than overwritten. Where the map lands depends on the provider: the request body for Gemini, OpenAI and Anthropic, options for Ollama, and additionalModelRequestFields for Bedrock chat models (the InvokeModel body for Bedrock image models).

Keys aren't validated, except that an API key here raises like one at the top level: config travels with the request into traces. Don't put other secrets here either.

max_output_tokens = Field(default=None, description='Maximum number of tokens to generate.') class-attribute instance-attribute

Upper bound on tokens in the reply.

stop_sequences = Field(default=None, description='Strings that end the reply when generated.') class-attribute instance-attribute

Strings that end the reply when the model emits one.

temperature = Field(default=None, description='Sampling temperature. Higher is more random.') class-attribute instance-attribute

Sampling temperature. Higher is more random.

top_k = Field(default=None, description='The maximum number of tokens to consider when sampling.') class-attribute instance-attribute

Sample only from the k most likely tokens.

top_p = Field(default=None, description='The maximum cumulative probability of tokens to consider when sampling.') class-attribute instance-attribute

Sample from the smallest token set whose probability reaches p.

version = Field(default=None, description='Model version to call, for providers that pin one.') class-attribute instance-attribute

Model version to call, for providers that pin one per request.

__get_pydantic_json_schema__(core_schema, handler) classmethod

Advertise common_field_bounds on the matching schema properties.

Source code in packages/genkit/src/genkit/_core/_model.py
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
@classmethod
def __get_pydantic_json_schema__(cls, core_schema: CoreSchema, handler: GetJsonSchemaHandler) -> JsonSchemaValue:
    """Advertise ``common_field_bounds`` on the matching schema properties."""
    json_schema = handler(core_schema)
    resolved = handler.resolve_ref_schema(json_schema)
    properties = resolved.get('properties')
    if isinstance(properties, dict):
        for name, (low, high) in cls.common_field_bounds.items():
            field = cls.model_fields.get(name)
            if field is None:
                continue
            alias = field.alias
            prop = properties.get(alias) if alias in properties else properties.get(name)
            if isinstance(prop, dict):
                prop['minimum'] = low
                prop['maximum'] = high
    return json_schema

__pydantic_init_subclass__(**kwargs) classmethod

Reject common_field_bounds entries that name unknown fields or invert (min, max).

Source code in packages/genkit/src/genkit/_core/_model.py
153
154
155
156
157
158
159
160
161
162
163
164
@classmethod
def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
    """Reject ``common_field_bounds`` entries that name unknown fields or invert ``(min, max)``."""
    super().__pydantic_init_subclass__(**kwargs)
    for name, (low, high) in cls.common_field_bounds.items():
        if name not in cls._NUMERIC_COMMON_FIELDS:
            raise ValueError(
                f'{cls.__name__}.common_field_bounds key {name!r} must be one of '
                f'{sorted(cls._NUMERIC_COMMON_FIELDS)}'
            )
        if low > high:
            raise ValueError(f'{cls.__name__}.common_field_bounds[{name!r}] min {low} > max {high}')

ModelContext

Bases: genkit._core._action.ActionContext[genkit._core._model.ModelResponseChunk]

Execution context passed to model and background-model functions.

  • ctx.send_chunk(chunk) streams a :class:~genkit.ModelResponseChunk to the caller.
  • ctx.is_streaming is True when the caller requested streaming.
  • ctx.context holds the caller's context dict (e.g. ctx.context.get('secrets')).
Source code in packages/genkit/src/genkit/_core/_action.py
1097
1098
1099
1100
1101
1102
1103
class ModelContext(ActionContext[ModelResponseChunk]):
    """Execution context passed to model and background-model functions.

    - ``ctx.send_chunk(chunk)`` streams a :class:`~genkit.ModelResponseChunk` to the caller.
    - ``ctx.is_streaming`` is ``True`` when the caller requested streaming.
    - ``ctx.context`` holds the caller's context dict (e.g. ``ctx.context.get('secrets')``).
    """

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

ModelInfo

Bases: genkit._core._base.GenkitModel

Model for modelinfo data.

Source code in packages/genkit/src/genkit/_core/_typing.py
603
604
605
606
607
608
609
610
611
612
class ModelInfo(GenkitModel):
    """Model for modelinfo data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    versions: list[str] | None = None
    label: str | None = None
    supports: ModelSupports | None = None
    stage: ModelStage | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ModelRef dataclass

Bases: typing.Generic[genkit._core._model.ModelRefConfigT]

Handle for a model tied to a config schema.

Fields cannot be rebound. config and info are copied at construction so later mutations of the caller's objects don't change the ref; the copies themselves stay ordinary mutable Pydantic models.

Source code in packages/genkit/src/genkit/_core/_model.py
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
@dataclass(frozen=True, kw_only=True)
class ModelRef(Generic[ModelRefConfigT]):
    """Handle for a model tied to a config schema.

    Fields cannot be rebound. config and info are copied at construction so later
    mutations of the caller's objects don't change the ref; the copies themselves
    stay ordinary mutable Pydantic models.
    """

    name: str
    config_schema: type[ModelRefConfigT]
    info: ModelInfo | None = None
    version: str | None = None
    config: ModelRefConfigT | None = None

    # Explicitly opt out of hashing: Pydantic configs are unhashable, so an
    # auto-generated __hash__ would fail once set.
    __hash__ = None  # type: ignore[assignment]

    def __post_init__(self) -> None:
        # Callers often keep the config/info they passed in. The checks copy
        # them so later mutations of those objects don't change the ref's defaults.
        config = check_ref_config(name=self.name, schema=self.config_schema, config=self.config, schema_required=True)
        object.__setattr__(self, 'config', config)
        info = check_ref_info(name=self.name, info=self.info, info_type=ModelInfo)
        object.__setattr__(self, 'info', info)

ModelRequest

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._model.ModelRequestConfigT]

Hand-written model request with veneer types and flat output accessors.

Output settings live nested as output: OutputConfig so dump/validate round-trips the wire shape, while flat properties (output_format etc.) stay the plugin-author convenience surface. Messages and docs use veneer types (Message, Document) for helpers like .text.

Example

from genkit.model import ModelConfig

class GeminiConfig(ModelConfig): safety_settings: dict[str, str] | None = None

def gemini_model(request: ModelRequest[GeminiConfig]) -> ModelResponse: temp = request.config.temperature # inherited from ModelConfig for msg in request.messages: print(msg.text) # Message veneer property if request.output_format == 'json': schema = request.output_schema

Note

Pass output settings as output=OutputConfig(...). The flat names (output_format etc.) are convenience properties you read and write after construction — they are not constructor arguments, so passing them there leaves output unset.

Source code in packages/genkit/src/genkit/_core/_model.py
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
class ModelRequest(GenkitModel, Generic[ModelRequestConfigT]):
    """Hand-written model request with veneer types and flat output accessors.

    Output settings live nested as ``output: OutputConfig`` so dump/validate
    round-trips the wire shape, while flat properties (``output_format`` etc.)
    stay the plugin-author convenience surface. Messages and docs use veneer
    types (Message, Document) for helpers like ``.text``.

    Example:
        from genkit.model import ModelConfig

        class GeminiConfig(ModelConfig):
            safety_settings: dict[str, str] | None = None

        def gemini_model(request: ModelRequest[GeminiConfig]) -> ModelResponse:
            temp = request.config.temperature  # inherited from ModelConfig
            for msg in request.messages:
                print(msg.text)  # Message veneer property
            if request.output_format == 'json':
                schema = request.output_schema

    Note:
        Pass output settings as ``output=OutputConfig(...)``. The flat
        names (``output_format`` etc.) are convenience properties you read
        and write after construction — they are not constructor arguments,
        so passing them there leaves output unset.
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='allow', validate_by_name=True, validate_by_alias=True
    )
    messages: list[Message]
    docs: list[Document] | None = None
    config: ModelRequestConfigT | None = None
    tools: list[ToolDefinition] | None = None
    tool_choice: ToolChoice | None = Field(default=None)
    # Wire-shaped output storage; flat access via the properties below.
    output: OutputConfig = Field(default_factory=OutputConfig)

    def __class_getitem__(cls, typevar_values: type[Any] | tuple[type[Any], ...]) -> Any:  # noqa: ANN401
        """``ModelRequest[Cfg]``, where ``Cfg`` must be a pydantic model class.

        Checked here, where the annotation is evaluated, so a TypedDict or
        dict config fails when the model function is defined, with the same
        error on every Python version.
        """
        check_config_type_arg(request='ModelRequest', field='config', typevar_values=typevar_values)
        return super().__class_getitem__(typevar_values)

    @field_validator('config', mode='before')
    @classmethod
    def _check_config_type(cls, v: object) -> object:
        """A mapping is the bag the plugin schema coerces.

        A Pydantic instance is only legal if it is that schema. OpenAIConfig
        on a Gemini request is a caller mistake — pass a mapping instead.
        """
        return check_config_value(cls, v, field='config')

    @field_validator('messages', mode='before')
    @classmethod
    def _wrap_messages(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_message(m) for m in v]

    @field_validator('docs', mode='before')
    @classmethod
    def _wrap_docs(cls, v: object) -> object:
        """A dumped request sends docs as dicts.

        Messages already take a mapping; this wrap has to as well or a bad
        config plus docs= never reaches the GenkitError for the config.
        """
        if v is None:
            return None
        if not isinstance(v, list):
            return v
        return [as_document(d) for d in v]

    @field_validator('output', mode='before')
    @classmethod
    def _wrap_output(cls, v: object) -> object:
        if v is None:
            return v
        return as_output_config(v)

    # Flat accessors: the plugin-author convenience surface over nested output.

    @property
    def output_format(self) -> str | None:
        """Output format (e.g. 'json'); reads ``output.format``."""
        return self.output.format

    @output_format.setter
    def output_format(self, v: str | None) -> None:
        self.output.format = v

    @property
    def output_schema(self) -> dict[str, Any] | None:
        """Output JSON schema; reads ``output.json_schema``."""
        return self.output.json_schema

    @output_schema.setter
    def output_schema(self, v: dict[str, Any] | None) -> None:
        self.output.json_schema = v

    @property
    def output_constrained(self) -> bool | None:
        """Whether constrained decoding is requested; reads ``output.constrained``."""
        return self.output.constrained

    @output_constrained.setter
    def output_constrained(self, v: bool | None) -> None:
        self.output.constrained = v

    @property
    def output_content_type(self) -> str | None:
        """Output content type; reads ``output.content_type``."""
        return self.output.content_type

    @output_content_type.setter
    def output_content_type(self, v: str | None) -> None:
        self.output.content_type = v

output_constrained property writable

Whether constrained decoding is requested; reads output.constrained.

output_content_type property writable

Output content type; reads output.content_type.

output_format property writable

Output format (e.g. 'json'); reads output.format.

output_schema property writable

Output JSON schema; reads output.json_schema.

__class_getitem__(typevar_values)

ModelRequest[Cfg], where Cfg must be a pydantic model class.

Checked here, where the annotation is evaluated, so a TypedDict or dict config fails when the model function is defined, with the same error on every Python version.

Source code in packages/genkit/src/genkit/_core/_model.py
1637
1638
1639
1640
1641
1642
1643
1644
1645
def __class_getitem__(cls, typevar_values: type[Any] | tuple[type[Any], ...]) -> Any:  # noqa: ANN401
    """``ModelRequest[Cfg]``, where ``Cfg`` must be a pydantic model class.

    Checked here, where the annotation is evaluated, so a TypedDict or
    dict config fails when the model function is defined, with the same
    error on every Python version.
    """
    check_config_type_arg(request='ModelRequest', field='config', typevar_values=typevar_values)
    return super().__class_getitem__(typevar_values)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ModelStage

Bases: genkit._core._compat.StrEnum

Model stage (featured, stable, unstable, legacy, deprecated).

Source code in packages/genkit/src/genkit/_core/_typing.py
1234
1235
1236
1237
1238
1239
1240
1241
class ModelStage(StrEnum):
    """Model stage (featured, stable, unstable, legacy, deprecated)."""

    FEATURED = 'featured'
    STABLE = 'stable'
    UNSTABLE = 'unstable'
    LEGACY = 'legacy'
    DEPRECATED = 'deprecated'

ModelSupports

Bases: genkit._core._base.GenkitModel

Model for modelsupports data.

Source code in packages/genkit/src/genkit/_core/_typing.py
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
class ModelSupports(GenkitModel):
    """Model for modelsupports data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    multiturn: bool | None = None
    media: bool | None = None
    tools: bool | None = None
    system_role: bool | None = None
    output: list[str] | None = None
    content_type: list[str] | None = None
    constrained: ConstrainedSupport | None = None
    tool_choice: bool | None = None
    long_running: bool | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

OutputConfig

Bases: genkit._core._base.GenkitModel

Output settings for a model request.

Construct with json_schema=; the serialized key on the wire is schema.

Source code in packages/genkit/src/genkit/_core/_model.py
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
class OutputConfig(GenkitModel):
    """Output settings for a model request.

    Construct with ``json_schema=``; the serialized key on the wire is
    ``schema``.
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True, protected_namespaces=()
    )
    format: str | None = None
    json_schema: dict[str, Any] | None = Field(default=None, validation_alias='schema', serialization_alias='schema')
    constrained: bool | None = None
    content_type: str | None = None

    @property
    def schema(self) -> dict[str, Any] | None:  # pyright: ignore[reportIncompatibleMethodOverride]  # pyrefly: ignore[bad-override]
        """Read-only alias for ``json_schema``, matching the wire key and JS.

        Shadows Pydantic's deprecated ``BaseModel.schema()`` classmethod so
        ``request.output.schema`` returns the schema dict, or ``None``.
        """
        return self.json_schema

schema property

Read-only alias for json_schema, matching the wire key and JS.

Shadows Pydantic's deprecated BaseModel.schema() classmethod so request.output.schema returns the schema dict, or None.

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ToolDefinition

Bases: genkit._core._base.GenkitModel

Model for tooldefinition data.

Source code in packages/genkit/src/genkit/_core/_typing.py
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
class ToolDefinition(GenkitModel):
    """Model for tooldefinition data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    name: str = Field(...)
    key: str | None = None
    description: str = Field(...)
    input_schema: Any | dict[str, Any] | None = Field(
        default=None, description='Valid JSON Schema representing the input of the tool.'
    )
    output_schema: Any | dict[str, Any] | None = Field(
        default=None, description='Valid JSON Schema describing the output of the tool.'
    )
    metadata: Metadata | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ToolRequest

Bases: genkit._core._base.GenkitModel

Model for toolrequest data.

Source code in packages/genkit/src/genkit/_core/_typing.py
774
775
776
777
778
779
780
781
782
783
class ToolRequest(GenkitModel):
    """Model for toolrequest data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    ref: str | None = None
    name: str = Field(...)
    input: Any | None = Field(default=None)
    partial: bool | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ToolResponse

Bases: genkit._core._base.GenkitModel

Model for toolresponse data.

Source code in packages/genkit/src/genkit/_core/_typing.py
786
787
788
789
790
791
792
793
794
795
class ToolResponse(GenkitModel):
    """Model for toolresponse data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    ref: str | None = None
    name: str = Field(...)
    output: Any | None = Field(default=None)
    content: list[Any] | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

genkit.embedder

Embedder namespace module for Genkit.

This module provides embedder-related types and utilities for plugin authors and advanced users who need access to the embedder protocol types.

Example

from genkit.embedder import ( EmbedContext, EmbedRequest, EmbedResponse, Embedder, EmbedderRef, )

EmbedContext

Bases: genkit._core._action.ActionContext[typing_extensions.Never]

Execution context passed to embedder functions.

ctx.context holds the caller's context dict. Embedders return one response and never emit chunks, so send_chunk accepts nothing. ctx.is_streaming still reports whether the caller asked to stream (Embedder.stream(), a Dev UI run with stream=true).

A per-tenant key passed on embed reaches the embedder here:

# 1. Read the tenant's key from the call's context
async def embed_menu(req: EmbedRequest, ctx: EmbedContext) -> EmbedResponse:
    api_key = ctx.context['secrets']['api_key']
    return await crm_embeddings(req.input, api_key=api_key)

ai.define_embedder(name='bistro/menu-embedder', fn=embed_menu)

# 2. Each call carries its own tenant's key
await ai.embed(
    embedder='bistro/menu-embedder',
    content=Document.from_text('Smoked Salmon Tartine'),
    context={'secrets': {'api_key': tenant_key}},
)
# => [Embedding(embedding=[0.12, -0.03, ...])]
Source code in packages/genkit/src/genkit/_core/_action.py
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
class EmbedContext(ActionContext[Never]):
    """Execution context passed to embedder functions.

    ``ctx.context`` holds the caller's context dict. Embedders return one
    response and never emit chunks, so ``send_chunk`` accepts nothing.
    ``ctx.is_streaming`` still reports whether the caller asked to stream
    (``Embedder.stream()``, a Dev UI run with ``stream=true``).

    A per-tenant key passed on ``embed`` reaches the embedder here:

        # 1. Read the tenant's key from the call's context
        async def embed_menu(req: EmbedRequest, ctx: EmbedContext) -> EmbedResponse:
            api_key = ctx.context['secrets']['api_key']
            return await crm_embeddings(req.input, api_key=api_key)

        ai.define_embedder(name='bistro/menu-embedder', fn=embed_menu)

        # 2. Each call carries its own tenant's key
        await ai.embed(
            embedder='bistro/menu-embedder',
            content=Document.from_text('Smoked Salmon Tartine'),
            context={'secrets': {'api_key': tenant_key}},
        )
        # => [Embedding(embedding=[0.12, -0.03, ...])]
    """

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

EmbedRequest

Bases: genkit._core._base.GenkitModel, typing.Generic[genkit._core._model.RequestOptionsT]

Embed request whose documents are the public Document type.

What options holds depends on how the embedder annotates request:

  • No annotation: Genkit infers EmbedRequest[Cfg] from the embedder's Pydantic config_schema, so options is a Cfg.
  • EmbedRequest[CrmEmbedConfig]: options is a validated CrmEmbedConfig.
  • Bare EmbedRequest: options is a dict. An explicit annotation is honored as written, the same as ModelRequest.

Bare EmbedRequest means EmbedRequest[Any] to type checkers, so a helper annotated with it accepts any typed request.

Source code in packages/genkit/src/genkit/_core/_model.py
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
class EmbedRequest(GenkitModel, Generic[RequestOptionsT]):
    """Embed request whose documents are the public Document type.

    What ``options`` holds depends on how the embedder annotates ``request``:

    * **No annotation**: Genkit infers ``EmbedRequest[Cfg]`` from the
      embedder's Pydantic ``config_schema``, so ``options`` is a ``Cfg``.
    * ``EmbedRequest[CrmEmbedConfig]``: ``options`` is a validated
      ``CrmEmbedConfig``.
    * Bare ``EmbedRequest``: ``options`` is a ``dict``. An explicit annotation
      is honored as written, the same as ``ModelRequest``.

    Bare ``EmbedRequest`` means ``EmbedRequest[Any]`` to type checkers, so a
    helper annotated with it accepts any typed request.
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(json_schema_extra=_untyped_options_schema)
    input: list[Document]
    # validate_default so EmbedRequest[Cfg]() builds Cfg() instead of keeping {}.
    options: RequestOptionsT = Field(default_factory=dict, validate_default=True)

    def __class_getitem__(cls, typevar_values: type[Any] | tuple[type[Any], ...]) -> Any:  # noqa: ANN401
        """``EmbedRequest[Cfg]``, where ``Cfg`` must be a pydantic model class."""
        check_config_type_arg(request='EmbedRequest', field='options', typevar_values=typevar_values)
        return super().__class_getitem__(typevar_values)

    @field_validator('input', mode='before')
    @classmethod
    def _wrap_docs(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_document(d) for d in v]

    @field_validator('options', mode='before')
    @classmethod
    def _check_options_type(cls, v: object) -> object:
        return check_options_value(cls, v)

__class_getitem__(typevar_values)

EmbedRequest[Cfg], where Cfg must be a pydantic model class.

Source code in packages/genkit/src/genkit/_core/_model.py
1363
1364
1365
1366
def __class_getitem__(cls, typevar_values: type[Any] | tuple[type[Any], ...]) -> Any:  # noqa: ANN401
    """``EmbedRequest[Cfg]``, where ``Cfg`` must be a pydantic model class."""
    check_config_type_arg(request='EmbedRequest', field='options', typevar_values=typevar_values)
    return super().__class_getitem__(typevar_values)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

EmbedResponse

Bases: genkit._core._base.GenkitModel

Model for embedresponse data.

Source code in packages/genkit/src/genkit/_core/_typing.py
316
317
318
319
320
321
322
class EmbedResponse(GenkitModel):
    """Model for embedresponse data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    embeddings: list[Embedding] = Field(...)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Embedder

Bases: genkit._core._action.Action[genkit._core._model.EmbedRequest, genkit._core._typing.EmbedResponse, typing_extensions.Never]

An embedder action that converts documents into vector embeddings.

Plugin init / resolve return this without registering it. define_embedder constructs and registers it on the registry.

The options class comes from config_schema or the fn's EmbedRequest[Cfg] annotation; given both, they must be the same class. An unannotated fn still gets an EmbedRequest, typed by config_schema when that is a Pydantic class.

Source code in packages/genkit/src/genkit/_ai/_embedding.py
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class Embedder(Action[EmbedRequest, EmbedResponse, Never]):
    """An embedder action that converts documents into vector embeddings.

    Plugin ``init`` / ``resolve`` return this without registering it.
    ``define_embedder`` constructs and registers it on the registry.

    The options class comes from ``config_schema`` or the fn's
    ``EmbedRequest[Cfg]`` annotation; given both, they must be the same class.
    An unannotated fn still gets an ``EmbedRequest``, typed by ``config_schema``
    when that is a Pydantic class.
    """

    @overload
    def __init__(
        self,
        name: str,
        fn: EmbedderFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: EmbedderInfo | None = None,
        description: str | None = None,
    ) -> None: ...

    @overload
    def __init__(
        self,
        name: str,
        fn: CtxFirstEmbedderFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: EmbedderInfo | None = None,
        description: str | None = None,
    ) -> None: ...

    def __init__(
        self,
        name: str,
        fn: EmbedderFn | CtxFirstEmbedderFn,
        *,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        info: EmbedderInfo | None = None,
        description: str | None = None,
    ) -> None:
        embedder_info: dict[str, object] = {}

        if metadata and 'embedder' in metadata:
            existing = metadata['embedder']
            if isinstance(existing, dict):
                existing_dict = cast(dict[str, object], existing)
                for key, value in existing_dict.items():
                    if isinstance(key, str) and key not in embedder_info:
                        embedder_info[key] = value

        if info:
            if info.label:
                embedder_info['label'] = info.label
            embedder_info['dimensions'] = info.dimensions
            if info.supports:
                embedder_info['supports'] = info.supports.model_dump(exclude_none=True, by_alias=True)
            embedder_info['customOptions'] = info.config_schema if info.config_schema else None

        if 'label' not in embedder_info or not embedder_info['label']:
            embedder_info['label'] = name

        if embedder_info.get('customOptions') is None and isinstance(config_schema, dict):
            embedder_info['customOptions'] = config_schema

        if 'dimensions' not in embedder_info:
            embedder_info['dimensions'] = None
        if 'customOptions' not in embedder_info:
            embedder_info['customOptions'] = None

        embedder_meta: dict[str, object] = metadata.copy() if metadata else {}
        embedder_meta['embedder'] = embedder_info

        # An unannotated request gets EmbedRequest[Cfg] when config_schema is a
        # Pydantic class, so options arrive as Cfg on every call path (ai.embed,
        # Dev UI, CLI); an explicit ``request: EmbedRequest`` annotation keeps
        # dict options. Built at runtime, so checkers can't read
        # EmbedRequest[options_class] as a type.
        from genkit._ai._model import python_config_schema  # noqa: PLC0415

        options_class = python_config_schema(config_schema)
        request_type = cast(Any, EmbedRequest)[options_class] if options_class is not None else EmbedRequest
        super().__init__(
            kind=ActionKind.EMBEDDER,
            name=name,
            fn=with_request_annotation(fn, request_type, kind=ActionKind.EMBEDDER),
            metadata=embedder_meta,
            description=get_func_description(fn, description),
            config_schema=config_schema,
            # Every embedder publishes EmbedRequest/EmbedResponse.
            _io_schemas=(fixed_json_schema(EmbedRequest), fixed_json_schema(EmbedResponse)),
        )
        # EmbedderInfo.config_schema is an explicit Dev UI override; else the class.
        if embedder_info.get('customOptions') is None and self.config_schema is not None:
            embedder_info['customOptions'] = custom_options_schema(self.config_schema)

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

EmbedderInfo

Bases: pydantic.BaseModel

Catalog card for an embedder: label, vector width, and input kinds.

Source code in packages/genkit/src/genkit/_ai/_embedding.py
43
44
45
46
47
48
49
50
51
class EmbedderInfo(BaseModel):
    """Catalog card for an embedder: label, vector width, and input kinds."""

    model_config: ClassVar[ConfigDict] = ConfigDict(extra='forbid', populate_by_name=True, alias_generator=to_camel)

    config_schema: dict[str, Any] | None = None
    label: str | None = None
    supports: EmbedderSupports | None = None
    dimensions: int | None = None

EmbedderRef dataclass

Bases: typing.Generic[genkit._ai._embedding.EmbedderRefConfigT]

Handle for an embedder, shaped like ModelRef.

config_schema is optional: embedders have no generic base config the way models have ModelConfig. Without it, config is a plain mapping and the call is not checked against a class. With it, config must be an instance, and ai.embed requires the embedder to declare the same class. version is the lowest caller layer, below config and the call's config, the same as ModelRef.version.

Fields cannot be rebound. config and info are copied at construction.

Source code in packages/genkit/src/genkit/_ai/_embedding.py
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
@dataclass(frozen=True, kw_only=True)
class EmbedderRef(Generic[EmbedderRefConfigT]):
    """Handle for an embedder, shaped like ModelRef.

    ``config_schema`` is optional: embedders have no generic base config the
    way models have ModelConfig. Without it, ``config`` is a plain mapping
    and the call is not checked against a class. With it, ``config`` must be
    an instance, and ``ai.embed`` requires the embedder to declare the same
    class. ``version`` is the lowest caller layer, below ``config`` and the
    call's config, the same as ModelRef.version.

    Fields cannot be rebound. config and info are copied at construction.
    """

    name: str
    config_schema: type[EmbedderRefConfigT] | None = None
    info: EmbedderInfo | None = None
    version: str | None = None
    config: EmbedderRefConfigT | Mapping[str, Any] | None = None

    __hash__ = None  # type: ignore[assignment]

    def __post_init__(self) -> None:
        config = check_ref_config(name=self.name, schema=self.config_schema, config=self.config, schema_required=False)
        object.__setattr__(self, 'config', config)
        object.__setattr__(self, 'info', check_ref_info(name=self.name, info=self.info, info_type=EmbedderInfo))

EmbedderSupports

Bases: pydantic.BaseModel

Embedder capability support.

Source code in packages/genkit/src/genkit/_ai/_embedding.py
34
35
36
37
38
39
40
class EmbedderSupports(BaseModel):
    """Embedder capability support."""

    model_config: ClassVar[ConfigDict] = ConfigDict(extra='forbid', populate_by_name=True)

    input: list[str] | None = None
    multilingual: bool | None = None

genkit.formats

Custom output formats. Register a Formatter subclass with ai.define_format().

Example
from genkit.formats import FormatHandler, Formatter, FormatterConfig

FormatHandler

Bases: typing.Generic[genkit._ai._formats._types.OutputT, genkit._ai._formats._types.ChunkT]

Per-request parsers and prompt instructions returned by Formatter.handle().

message_parser builds response.output; chunk_parser builds chunk.output. instructions, when set, is added to the prompt, except on a natively constrained JSON request, where the model already follows the schema. A request is natively constrained when format='json', constrained is on, there is a schema, and the model declares supports.constrained (all, or no-tools with no tools). A caller overrides it per request with output_instructions: True adds it, False adds nothing, a string replaces it.

Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
class FormatHandler(Generic[OutputT, ChunkT]):
    """Per-request parsers and prompt instructions returned by `Formatter.handle()`.

    `message_parser` builds `response.output`; `chunk_parser` builds `chunk.output`.
    `instructions`, when set, is added to the prompt, except on a natively constrained
    JSON request, where the model already follows the schema. A request is natively
    constrained when `format='json'`, `constrained` is on, there is a schema, and the
    model declares `supports.constrained` (`all`, or `no-tools` with no tools). A caller
    overrides it per request with `output_instructions`: `True` adds it, `False` adds
    nothing, a string replaces it.
    """

    def __init__(
        self,
        message_parser: Callable[[Message], OutputT],
        chunk_parser: Callable[[ModelResponseChunk], ChunkT],
        instructions: str | None = None,
    ) -> None:
        """Initializes a FormatHandler.

        Args:
            message_parser: Parses the final model message into the output value.
            chunk_parser: Parses a streamed chunk into the chunk output value.
            instructions: Text appended to the prompt, or None for no instructions.
        """
        self.instructions: str | None = instructions
        self.__message_parser = message_parser
        self.__chunk_parser = chunk_parser

    def parse_message(self, message: Message) -> OutputT:
        """Parses the final model message."""
        return self.__message_parser(message)

    def parse_chunk(self, chunk: ModelResponseChunk) -> ChunkT:
        """Parses one streamed chunk."""
        return self.__chunk_parser(chunk)

__init__(message_parser, chunk_parser, instructions=None)

Initializes a FormatHandler.

Parameters:

Name Type Description Default
message_parser collections.abc.Callable[[genkit._ai._model.Message], genkit._ai._formats._types.OutputT]

Parses the final model message into the output value.

required
chunk_parser collections.abc.Callable[[genkit._ai._model.ModelResponseChunk], genkit._ai._formats._types.ChunkT]

Parses a streamed chunk into the chunk output value.

required
instructions str | None

Text appended to the prompt, or None for no instructions.

None
Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
def __init__(
    self,
    message_parser: Callable[[Message], OutputT],
    chunk_parser: Callable[[ModelResponseChunk], ChunkT],
    instructions: str | None = None,
) -> None:
    """Initializes a FormatHandler.

    Args:
        message_parser: Parses the final model message into the output value.
        chunk_parser: Parses a streamed chunk into the chunk output value.
        instructions: Text appended to the prompt, or None for no instructions.
    """
    self.instructions: str | None = instructions
    self.__message_parser = message_parser
    self.__chunk_parser = chunk_parser

parse_chunk(chunk)

Parses one streamed chunk.

Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
82
83
84
def parse_chunk(self, chunk: ModelResponseChunk) -> ChunkT:
    """Parses one streamed chunk."""
    return self.__chunk_parser(chunk)

parse_message(message)

Parses the final model message.

Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
78
79
80
def parse_message(self, message: Message) -> OutputT:
    """Parses the final model message."""
    return self.__message_parser(message)

Formatter

Bases: abc.ABC

A named output format. Subclass it, implement handle(), register with ai.define_format().

handle() runs once per generate call with the request's JSON schema (or None).

Example
import csv
import io

from genkit import Genkit
from genkit.formats import FormatHandler, Formatter, FormatterConfig
from genkit_google_genai import GoogleAI


class CsvFormat(Formatter):
    def __init__(self) -> None:
        super().__init__('csv', FormatterConfig(content_type='text/csv'))

    def handle(self, schema: dict[str, object] | None) -> FormatHandler:
        return FormatHandler(
            message_parser=lambda msg: list(csv.DictReader(io.StringIO(msg.text))),
            chunk_parser=lambda chunk: chunk.text,
            instructions='Reply only with CSV. First row is the header.',
        )


# 1. Register the format
ai = Genkit(plugins=[GoogleAI()], model='googleai/gemini-flash-latest')
ai.define_format(CsvFormat())

# 2. Request it by name
response = await ai.generate(prompt='List 2 dishes with price.', output_format='csv')

# 3. response.output is what message_parser returned
print(response.output)
# => [{'dish': 'Ramen', 'price': '14.50'}, {'dish': 'Pho', 'price': '13.00'}]
Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
class Formatter(abc.ABC):
    """A named output format. Subclass it, implement `handle()`, register with `ai.define_format()`.

    `handle()` runs once per generate call with the request's JSON schema (or None).

    Example:
        ```python
        import csv
        import io

        from genkit import Genkit
        from genkit.formats import FormatHandler, Formatter, FormatterConfig
        from genkit_google_genai import GoogleAI


        class CsvFormat(Formatter):
            def __init__(self) -> None:
                super().__init__('csv', FormatterConfig(content_type='text/csv'))

            def handle(self, schema: dict[str, object] | None) -> FormatHandler:
                return FormatHandler(
                    message_parser=lambda msg: list(csv.DictReader(io.StringIO(msg.text))),
                    chunk_parser=lambda chunk: chunk.text,
                    instructions='Reply only with CSV. First row is the header.',
                )


        # 1. Register the format
        ai = Genkit(plugins=[GoogleAI()], model='googleai/gemini-flash-latest')
        ai.define_format(CsvFormat())

        # 2. Request it by name
        response = await ai.generate(prompt='List 2 dishes with price.', output_format='csv')

        # 3. response.output is what message_parser returned
        print(response.output)
        # => [{'dish': 'Ramen', 'price': '14.50'}, {'dish': 'Pho', 'price': '13.00'}]
        ```
    """

    def __init__(self, name: str, config: FormatterConfig) -> None:
        """Initializes a Formatter.

        Args:
            name: Name passed as `output_format=` to select this format.
            config: Request settings applied when this format is selected.
        """
        self.name: str = name
        self.config: FormatterConfig = config

    @abc.abstractmethod
    def handle(self, schema: dict[str, object] | None) -> FormatHandler[Any, Any]:
        """Returns the FormatHandler for one generate call.

        Args:
            schema: The request's output JSON schema, or None.
        """
        pass

    def __call__(self, schema: dict[str, object] | None) -> FormatHandler[Any, Any]:
        """Same as `handle(schema)`."""
        return self.handle(schema)

__call__(schema)

Same as handle(schema).

Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
146
147
148
def __call__(self, schema: dict[str, object] | None) -> FormatHandler[Any, Any]:
    """Same as `handle(schema)`."""
    return self.handle(schema)

__init__(name, config)

Initializes a Formatter.

Parameters:

Name Type Description Default
name str

Name passed as output_format= to select this format.

required
config genkit._ai._formats._types.FormatterConfig

Request settings applied when this format is selected.

required
Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
127
128
129
130
131
132
133
134
135
def __init__(self, name: str, config: FormatterConfig) -> None:
    """Initializes a Formatter.

    Args:
        name: Name passed as `output_format=` to select this format.
        config: Request settings applied when this format is selected.
    """
    self.name: str = name
    self.config: FormatterConfig = config

handle(schema) abstractmethod

Returns the FormatHandler for one generate call.

Parameters:

Name Type Description Default
schema dict[str, object] | None

The request's output JSON schema, or None.

required
Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
137
138
139
140
141
142
143
144
@abc.abstractmethod
def handle(self, schema: dict[str, object] | None) -> FormatHandler[Any, Any]:
    """Returns the FormatHandler for one generate call.

    Args:
        schema: The request's output JSON schema, or None.
    """
    pass

FormatterConfig

Bases: genkit._core._base.GenkitModel

Request settings a Formatter applies to every generate call that uses it.

format and content_type replace the request's values. constrained asks for the model's native JSON mode, and the request can override it. It only takes effect when there is a schema and the model declares supports.constrained.

Source code in packages/genkit/src/genkit/_ai/_formats/_types.py
32
33
34
35
36
37
38
39
40
41
42
class FormatterConfig(GenkitModel):
    """Request settings a Formatter applies to every generate call that uses it.

    `format` and `content_type` replace the request's values. `constrained` asks for the
    model's native JSON mode, and the request can override it. It only takes effect when
    there is a schema and the model declares `supports.constrained`.
    """

    format: str | None = None
    content_type: str | None = None
    constrained: bool | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

genkit.plugin_api

Framework primitives for plugin authors.

GENKIT_USER_AGENT = f'genkit-python/{GENKIT_VERSION}' module-attribute

Header value plugins send in x-goog-api-client and user-agent.

StatusName = Literal['OK', 'CANCELLED', 'UNKNOWN', 'INVALID_ARGUMENT', 'DEADLINE_EXCEEDED', 'NOT_FOUND', 'ALREADY_EXISTS', 'PERMISSION_DENIED', 'UNAUTHENTICATED', 'RESOURCE_EXHAUSTED', 'FAILED_PRECONDITION', 'ABORTED', 'OUT_OF_RANGE', 'UNIMPLEMENTED', 'INTERNAL', 'UNAVAILABLE', 'DATA_LOSS'] module-attribute

Canonical gRPC status name a GenkitError carries, e.g. 'NOT_FOUND'.

Action

Bases: typing.Generic[genkit._core._action.InputT, genkit._core._action.OutputT, genkit._core._action.ChunkT, genkit._core._action.InitT]

A named, traced, remotely callable function.

Source code in packages/genkit/src/genkit/_core/_action.py
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
class Action(Generic[InputT, OutputT, ChunkT, InitT]):
    """A named, traced, remotely callable function."""

    def __init__(
        self,
        kind: ActionKind,
        name: str,
        fn: Callable[..., Awaitable[OutputT]],
        *,
        metadata_fn: Callable[..., object] | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
        span_metadata: dict[str, SpanAttributeValue] | None = None,
        init_schema: type[BaseModel] | dict[str, object] | None = None,
        input_schema: type[BaseModel] | dict[str, object] | None = None,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        _strict_io: bool = False,
        _io_schemas: tuple[dict[str, object], dict[str, object]] | None = None,
        _context_kind: ActionKind | None = None,
    ) -> None:
        self._kind: ActionKind = kind
        self._name: str = name
        context_kind = _context_kind if _context_kind is not None else kind
        self._context_cls: type[ActionContext[Any]] = _context_cls_for_kind(context_kind)
        # Flows treat None as a real value and check the return against the
        # annotation. Tools take None as a value too (see _run) but check
        # their own return. Other actions treat None as omitted.
        self._strict_io: bool = _strict_io
        self._metadata: dict[str, object] = metadata if metadata is not None else {}
        self._description: str | None = description
        # What config_schema= declared: a Pydantic class or a JSON-schema dict.
        # generate checks config against it. Not in metadata — that bag is
        # JSON for the Dev UI.
        self._config_schema: type[BaseModel] | dict[str, object] | None = config_schema
        if isinstance(config_schema, dict):
            check_config_json_schema(cast(dict[str, Any], config_schema), model=name)
        self._span_metadata: dict[str, SpanAttributeValue] = span_metadata if span_metadata is not None else {}

        # All action handlers must be async
        if not inspect.iscoroutinefunction(fn):
            raise TypeError(f"Action handlers must be async functions. Got sync function for '{name}'.")

        # Genkit calls fn. With a metadata_fn, fn is a wrapper (the tool wrapper
        # is one) and metadata_fn is the user's function, whose signature
        # decides the input and context.
        user_fn: Callable[..., object] = metadata_fn if metadata_fn else fn
        hints = resolve_type_hints(user_fn, known_annotation_names(kind, context_kind=context_kind))
        self._params: ActionParams = find_input_and_context(
            user_fn, hints, kind=kind, name=name, context_kind=context_kind
        )
        self._fn: Callable[..., Awaitable[OutputT]] = fn
        self._user_fn: Callable[..., object] = user_fn
        self._fn_is_wrapper: bool = metadata_fn is not None
        # _io_schemas: the (input, output) JSON schemas to publish, from a
        # subclass whose kind always publishes the same ones (Model publishes
        # ModelRequest/ModelResponse whatever the fn's ModelRequest[Cfg]).
        # Skips generating schemas from the annotations only to discard them.
        self._initialize_io_schemas(hints, _io_schemas)
        self._config_schema = self._resolve_config_class(self._config_schema)
        self._initialize_init_schema(init_schema)
        if input_schema is not None:
            self._override_input_schema(input_schema)

    def _resolve_config_class(
        self, declared: type[BaseModel] | dict[str, object] | None
    ) -> type[BaseModel] | dict[str, object] | None:
        """The one config class this action takes, from ``config_schema=`` and/or the fn annotation.

        Both must name the same class. With a subclass, a dict would validate
        into the annotated class and drop the other class's fields, so only
        the identical class is accepted. A JSON-schema dict next to an
        annotated class is rejected too: the class would win and the dict
        would never be checked.
        """
        field = config_field(self._kind)
        annotated = declared_config_type(self._input_class) if field and self._input_class is not None else None
        if annotated is None:
            return declared
        if isinstance(declared, dict):
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=(
                    f'{describe_action(self._kind, self._name)}: config_schema is a JSON schema, '
                    f'but the function takes {field} as {config_type_path(annotated)}. '
                    'Pass the class or the JSON schema, not both.'
                ),
            )
        if isinstance(declared, type) and declared is not annotated:
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=(
                    f'{describe_action(self._kind, self._name)}: config_schema is {config_type_path(declared)}, '
                    f'but the function takes {field} as {config_type_path(annotated)}. '
                    'Pass the same class to both, or only one of them.'
                ),
            )
        return annotated

    @property
    def config_schema(self) -> type[BaseModel] | dict[str, object] | None:
        """The config class set at definition time, from ``config_schema=`` or the fn annotation."""
        return self._config_schema

    @property
    def params(self) -> ActionParams:
        """The function's input and context parameters, as Genkit passes them."""
        return self._params

    @property
    def kind(self) -> ActionKind:
        return self._kind

    @property
    def name(self) -> str:
        return self._name

    @property
    def description(self) -> str | None:
        return self._description

    @property
    def metadata(self) -> dict[str, object]:
        return self._metadata

    def _action_metadata(self) -> ActionMetadata:
        """Return the ActionMetadata descriptor for Registry.list_actions()."""
        meta = {
            k: v
            for k, v in self._metadata.items()
            if k not in (ActionMetadataKey.INPUT_KEY, ActionMetadataKey.OUTPUT_KEY)
        }
        return ActionMetadata(
            key=create_action_key(self._kind, self._name),
            action_type=self._kind,
            name=self._name,
            description=self._description,
            input_schema=self._input_schema,
            output_schema=self._output_schema,
            metadata=meta or None,
        )

    @property
    def input_type(self) -> TypeAdapter[Any] | None:
        return self._input_type

    @property
    def input_class(self) -> type | None:
        """The action's input annotation as a concrete class, when it is one."""
        return getattr(self, '_input_class', None)

    @property
    def input_schema(self) -> dict[str, object]:
        return self._input_schema

    @input_schema.setter
    def input_schema(self, value: dict[str, object]) -> None:
        self._input_schema = value
        self._metadata[ActionMetadataKey.INPUT_KEY] = value

    @property
    def output_schema(self) -> dict[str, object] | None:
        return self._output_schema

    @output_schema.setter
    def output_schema(self, value: dict[str, object] | None) -> None:
        self._set_output_schema(value)

    def _set_output_schema(self, value: dict[str, object] | None) -> None:
        self._output_schema = value
        if value is None:
            self._metadata.pop(ActionMetadataKey.OUTPUT_KEY, None)
        else:
            self._metadata[ActionMetadataKey.OUTPUT_KEY] = value

    def _override_input_schema(
        self,
        input_schema: type[BaseModel] | dict[str, object],
    ) -> None:
        """Replace inferred input JSON Schema and validation type (e.g. tool schema overrides)."""
        in_js = to_json_schema(input_schema)
        self.input_schema = in_js
        if isinstance(input_schema, dict):
            self._input_type = None
        else:
            self._input_type = cast(TypeAdapter[InputT], TypeAdapter(input_schema))

    @overload
    async def __call__(
        self: Action[None, OutputT, ChunkT, InitT],
        input: None = None,
        *,
        context: dict[str, Any] | None = None,
    ) -> OutputT: ...

    @overload
    async def __call__(
        self,
        input: InputT,
        *,
        context: dict[str, Any] | None = None,
    ) -> OutputT: ...

    async def __call__(
        self: Action[Any, OutputT, ChunkT, InitT],
        input: InputT | None = NO_INPUT,
        *,
        context: dict[str, Any] | None = None,
    ) -> OutputT:
        """Call the action directly, returning just the response value."""
        return (await self._run(input, context=context)).response

    @overload
    async def run(
        self: Action[None, OutputT, ChunkT, InitT],
        input: None = None,
        *,
        on_chunk: Callable[[ChunkT], None] | None = None,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> ActionResponse[OutputT]: ...

    @overload
    async def run(
        self,
        input: InputT,
        *,
        on_chunk: Callable[[ChunkT], None] | None = None,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> ActionResponse[OutputT]: ...

    async def run(
        self: Action[Any, OutputT, ChunkT, InitT],
        input: InputT | None = NO_INPUT,
        *,
        on_chunk: Callable[[ChunkT], None] | None = None,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> ActionResponse[OutputT]:
        """Run the action and return its result with trace ids.

        Args:
            input: The input, validated against the input schema. Required
                unless the action takes no input or its function gives the
                input a default; omit it to use that default. On a flow or
                tool, an explicit None is a value and is validated like any
                other.
            on_chunk: Called with each chunk the action streams.
            context: Request context (auth, headers, ...), read as ``ctx.context``.
            telemetry_labels: Custom labels set as span attributes.
            init: Session init value for a bidi action (e.g. a served agent's
                session identity). Validated against the init schema; plain
                actions ignore it.

        Returns:
            ActionResponse with the result, trace id and span id.

        Raises:
            GenkitError: If input validation fails (INVALID_ARGUMENT status).
        """
        return await self._run(
            input,
            on_chunk=on_chunk,
            context=context,
            telemetry_labels=telemetry_labels,
            init=init,
        )

    async def _run(
        self,
        input: InputT | None = NO_INPUT,
        *,
        on_chunk: Callable[[ChunkT], None] | None = None,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
        on_trace_start: Callable[[str, str], Awaitable[None]] | None = None,
        input_stream: AsyncIterator[InputT] | None = None,
    ) -> ActionResponse[OutputT]:
        """``run`` plus the hooks only the Dev UI and bidi plumbing use.

        on_trace_start: Called with (trace_id, span_id) once the span opens, so
            the reflection server can show the live trace and wire up cancel.
        input_stream: Live stream of per-turn inputs for a bidi action. When
            omitted, a one-shot run is exactly the single ``input``. Stored on
            ``ctx._input_stream``; only bidi actions read it.
        """
        # From Python, None is a value for flows and tools; omit the input to
        # use the function's default. JSON can't tell null from omitted, so the
        # wire boundaries (reflection, web adapters, a model's tool request)
        # turn null into NO_INPUT with input_from_json before calling here.
        # Models, embedders and the rest take a request object, where None
        # still means no input.
        if input is None and not (self._strict_io or self._kind in (ActionKind.TOOL, ActionKind.TOOL_V2)):
            input = NO_INPUT
        # With a live input_stream, `input` isn't the payload — the stream
        # carries the per-turn inputs — so there's nothing to validate up front.
        if input_stream is None:
            # Checked ahead of validation so a strict config class reports the
            # secrets slot instead of an unknown key. Runs on every model call,
            # including ones that never went through generate.
            if self._kind in (ActionKind.MODEL, ActionKind.BACKGROUND_MODEL):
                reject_config_api_key(_request_config(input))
            input = self._layer_config_defaults(input)
            input = self._validate_input(input)
            # docs= become a context part on the last user message here, in
            # the model action, after every wrap_model has run. A middleware
            # that clears request.docs keeps them from the model, and a model
            # called directly (Fallback's backup, a judge) still gets them.
            # No-op when the message already carries a rendered context part.
            if (
                self._kind in (ActionKind.MODEL, ActionKind.BACKGROUND_MODEL)
                and isinstance(input, ModelRequest)
                and input.docs
            ):
                input = cast(InputT, augment_with_context(input))
        init = self._validate_init(init)

        if context is None:
            # Inherit the enclosing action's context as a shallow copy, so
            # concurrent child flows setting top-level keys on ctx.context
            # don't clobber each other or the parent (matching run_tool_request).
            ambient = _action_context.get(None)
            context = dict(ambient) if ambient is not None else None
        token = None
        if context is not None:
            token = _action_context.set(context)
        inside_token = _inside_action.set(True)

        streaming_cb = cast(StreamingCallback, on_chunk) if on_chunk else None
        action_ctx: ActionContext[Any] = self._context_cls(
            context=_action_context.get(None),
            streaming_callback=streaming_cb,
            init=init,
            input_stream=input_stream,
        )

        try:
            result = await self._run_with_telemetry(
                input,
                action_ctx,
                on_trace_start,
                telemetry_labels,
            )
            if self._kind == ActionKind.MODEL:
                _report_model_usage(result.response)
            return result

        finally:
            _inside_action.reset(inside_token)
            if token is not None:
                _action_context.reset(token)

    @overload
    def stream(
        self: Action[None, OutputT, ChunkT, InitT],
        input: None = None,
        *,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> StreamResponse[ChunkT, OutputT]: ...

    @overload
    def stream(
        self,
        input: InputT,
        *,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> StreamResponse[ChunkT, OutputT]: ...

    def stream(
        self: Action[Any, OutputT, ChunkT, InitT],
        input: InputT | None = NO_INPUT,
        *,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
    ) -> StreamResponse[ChunkT, OutputT]:
        """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

        Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
        action raises, both the loop and ``.response`` raise.
        """
        return self._stream(
            input,
            context=context,
            telemetry_labels=telemetry_labels,
            init=init,
        )

    def _stream(
        self,
        input: InputT | None = NO_INPUT,
        *,
        context: dict[str, Any] | None = None,
        telemetry_labels: dict[str, object] | None = None,
        init: InitT | None = None,
        input_stream: AsyncIterator[InputT] | None = None,
    ) -> StreamResponse[ChunkT, OutputT]:
        """Run the action and return a StreamResponse to read its chunks and result.

        Iterate ``.stream`` for chunks and await ``.response`` for the output.
        Closing early via ``async with my_flow.stream(x) as res:`` (or
        ``await res.aclose()``) cancels the run and awaits ``finally:`` cleanup,
        and ``.response`` then raises ``GenkitError`` with status ``CANCELLED``. Cancelling
        the reader mid-``async for`` stops the run the same way. Python does not
        tear down an ``AsyncIterator`` on ``break`` alone: the run stops once the
        stream is dropped, so wrap it in ``async with`` when the stop should
        happen (and finish) right at the ``break``.

        Example:
            async with my_flow.stream(x) as res:
                async for chunk in res.stream:
                    if done_with(chunk):
                        break
        """
        return self._start_stream(
            input=input,
            context=context,
            telemetry_labels=telemetry_labels,
            init=init,
            input_stream=input_stream,
            stop_on_early_exit=True,
        )

    def _start_stream(
        self,
        *,
        input: InputT | None,
        context: dict[str, Any] | None,
        telemetry_labels: dict[str, object] | None,
        init: InitT | None,
        input_stream: AsyncIterator[InputT] | None,
        stop_on_early_exit: bool,
    ) -> StreamResponse[ChunkT, OutputT]:
        channel: Channel[ChunkT, ActionResponse[OutputT]] = Channel()

        def send_chunk(c: ChunkT) -> None:
            channel.send(c)

        resp = self._run(
            input,
            on_chunk=send_chunk,
            context=context,
            telemetry_labels=telemetry_labels,
            init=init,
            input_stream=input_stream,
        )
        child_stops: set[asyncio.Task[None]] = set()

        def _create_run_task() -> asyncio.Task[ActionResponse[OutputT]]:
            _stop_scope.set(child_stops)
            return asyncio.create_task(resp)

        run_task = copy_context().run(_create_run_task)
        channel.set_close_future(run_task)
        reader_stopped = asyncio.Event()

        async def stop() -> None:
            if not run_task.done():
                if not reader_stopped.is_set():
                    reader_stopped.set()
                    run_task.cancel()
                # waiting here is what lets aclosing(...) promise the run is over
                # once the block exits.
                await asyncio.wait([run_task])
            # Let done-callbacks on run_task (e.g. inner StoppableStream._on_reader_done)
            # schedule their _spawn_stop tasks, then drain any stops spawned in this scope.
            await asyncio.sleep(0)
            while child_stops:
                await asyncio.wait(list(child_stops))
                await asyncio.sleep(0)

        # Mirror the run's terminal state onto .response so a caller awaiting it
        # sees the same success/error/cancel the run ended with, instead of
        # hanging (or dropping the error on the floor) when the run raises.
        result_future: asyncio.Future[OutputT] = asyncio.Future()

        def resolve_response(closed: asyncio.Future[ActionResponse[OutputT]]) -> None:
            if result_future.done():
                return
            if closed.cancelled():
                if reader_stopped.is_set():
                    result_future.set_exception(
                        GenkitError(status='CANCELLED', message='The stream was closed before the run finished.')
                    )
                    # the reader chose to stop, so leaving .response unread
                    # shouldn't log "exception was never retrieved".
                    _ = result_future.exception()
                else:
                    result_future.cancel()
            elif (exc := closed.exception()) is not None:
                result_future.set_exception(exc)
                _ = result_future.exception()
            else:
                result_future.set_result(closed.result().response)

        channel.closed.add_done_callback(resolve_response)

        chunks = StoppableStream(chunks=channel, stop=stop if stop_on_early_exit else None)
        stream_response = StreamResponse(stream=chunks, response=result_future)
        stream_response._action_name = self.name
        return stream_response

    def _initialize_io_schemas(
        self,
        annotations: dict[str, Any],
        published: tuple[dict[str, object], dict[str, object]] | None = None,
    ) -> None:
        published_input, published_output = published if published is not None else (None, None)
        if self._params.input is not None:
            input_type = annotations.get(self._params.input.name, Any)
            type_adapter, self._input_schema = json_schema_for(
                input_type,
                kind=self._kind,
                name=self._name,
                label=f"input '{self._params.input.name}'",
                schema=published_input,
            )
            self._input_type: TypeAdapter[InputT] | None = cast(TypeAdapter[InputT], type_adapter)
            self._input_class: type | None = input_type if isinstance(input_type, type) else None
        else:
            self._input_schema = published_input or TypeAdapter(object).json_schema()
            self._input_type = None
            self._input_class = None
        self._metadata[ActionMetadataKey.INPUT_KEY] = self._input_schema

        if ActionMetadataKey.RETURN in annotations:
            output_adapter, self._output_schema = json_schema_for(
                annotations[ActionMetadataKey.RETURN],
                kind=self._kind,
                name=self._name,
                label='output',
                schema=published_output,
            )
            self._output_type: TypeAdapter[OutputT] | None = cast(TypeAdapter[OutputT], output_adapter)
        else:
            self._output_type = None
            self._output_schema = published_output or TypeAdapter(object).json_schema()
        self._metadata[ActionMetadataKey.OUTPUT_KEY] = self._output_schema

    def _initialize_init_schema(
        self,
        init_schema: type[BaseModel] | dict[str, object] | None,
    ) -> None:
        """Register the schema for per-run ``init`` data, if the action declares one.

        Mirrors the input/output schema setup: a Pydantic model gives us a
        validator plus a published JSON schema; a raw dict is published as-is
        but can't be validated.
        """
        if init_schema is None:
            self._init_type: TypeAdapter[InitT] | None = None
            return
        self._init_schema: dict[str, object] = to_json_schema(init_schema)
        self._metadata[ActionMetadataKey.INIT_KEY] = self._init_schema
        if isinstance(init_schema, dict):
            self._init_type = None
        else:
            self._init_type = cast(TypeAdapter[InitT], TypeAdapter(init_schema))

    @property
    def _kind_label(self) -> str:
        """What the caller calls this action in an error: `flow`, `model`, `tool`, `background model`."""
        return _kind_label(self._kind)

    def _validate_init(self, init: InitT | None) -> InitT | None:
        """Validate per-run ``init`` against the init schema when one is registered.

        A missing ``init`` is validated as an empty object so a schema whose
        fields are all optional (like an agent's session identity) still produces
        a sensible default. A schema with required fields instead surfaces a clear
        "init required" error rather than a raw validation dump about ``{}``.
        """
        if self._init_type is None:
            return init
        try:
            return self._init_type.validate_python(init if init is not None else {})
        except ValidationError as e:
            if init is None:
                raise _request_error(
                    GenkitError(
                        message=(f"{self._kind_label.capitalize()} '{self.name}' requires init but none was provided."),
                        status='INVALID_ARGUMENT',
                        reason=ErrorReason.INVALID_INPUT,
                    )
                ) from e
            raise _request_error(
                GenkitError(
                    message=f"Invalid init for {self._kind_label} '{self.name}'",
                    status='INVALID_ARGUMENT',
                    cause=e,
                    reason=ErrorReason.INVALID_INPUT,
                )
            ) from e

    def _layer_config_defaults(self, input: InputT | None) -> Any:  # noqa: ANN401 - InputT is contravariant
        """Normalize the request's config against the definition-time class.

        Every caller (ai.* by name or ref, the Dev UI, the CLI) reaches the fn
        through here, so they all see the same values. Only actions with a
        config class are touched, and defaults come only from that class.

        - Typed fn: a missing config (``config=None``) becomes the class
          built from its defaults, so the fn always gets an instance. A class
          that can't build from defaults raises INVALID_ARGUMENT. Otherwise
          request validation fills defaults and checks values.
        - Untyped fn: non-None defaults < the request's config, folded to the
          keys the class accepts and validated against the class, so a bad
          value raises INVALID_ARGUMENT the same as through ai.*. For models,
          the fn gets the merged dict as written, not pydantic's coerced values:
          ModelConfig declares ``temperature`` as a float, and an untyped
          plugin should still send the caller's ``1``, not ``1.0``. (Embedders
          with an unannotated request parameter are upgraded to
          ``EmbedRequest[Cfg]`` via ``with_request_annotation``.)

        An explicit None in the config is a value: it wins over the default
        and goes to validation.
        """
        field = config_field(self._kind)
        schema = self._config_schema
        if field is None or schema is None:
            return input
        if isinstance(input, Mapping):
            current = cast(Mapping[str, Any], input).get(field)
        elif isinstance(input, BaseModel):
            current = getattr(input, field, None)
        else:
            return input
        try:
            value = self._normalized_config(current, schema=schema, field=field)
        except GenkitError as e:
            raise mark_request_error(error=e)  # noqa: B904 - same error, marked as the caller's
        if value is current:
            return input
        if isinstance(input, Mapping):
            return cast(InputT, {**cast(Mapping[str, Any], input), field: value})
        return cast(InputT, cast(BaseModel, input).model_copy(update={field: value}))

    def _normalized_config(self, current: object, *, schema: type[BaseModel] | dict[str, Any], field: str) -> object:
        """The config value _layer_config_defaults puts on the request (``current`` when unchanged)."""
        if isinstance(schema, dict):
            # A JSON-schema dict has no defaults to layer; it is only checked.
            validate_whole_config(config=current, schema=schema, model=self.name)
            return current
        if self._input_class is not None and declared_config_type(self._input_class) is not None:
            if current is None:
                return validate_whole_config(config={}, schema=schema, model=self.name)
            if isinstance(current, Mapping) and not isinstance(current, BaseModel):
                # The same check an untyped fn gets, so a typed fn reports
                # problems in the same words; the fn gets the validated instance.
                return validate_whole_config(
                    config=dict(cast(Mapping[str, Any], current)), schema=schema, model=self.name
                )
            return current
        if isinstance(current, BaseModel) and not isinstance(current, schema):
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message=(
                    f'{self.name}: {field} must be {config_type_path(schema)} or a mapping, '
                    f'got {config_type_path(type(current))}'
                ),
                reason=ErrorReason.INVALID_INPUT,
            )
        if current is not None and not isinstance(current, (Mapping, BaseModel)):
            return current  # request validation reports the wrong type
        defaults = config_defaults(schema)
        request_layer = normalize_config(config=current)
        # Folding keeps whichever spelling of a setting came last, so the
        # request's own dict is checked first: both spellings in it raise.
        check_config_values(config=request_layer, schema=schema, model=self.name)
        merged = overlay_config(layers=[defaults, request_layer], schema=schema)
        validate_whole_config(config=merged, schema=schema, model=self.name)
        return merged

    def _validate_input(self, input: InputT | None) -> Any:  # noqa: ANN401 - InputT is contravariant
        """Validate caller input against the action schema when one is registered."""
        omitted = input is NO_INPUT
        # Skip validation when the caller passed nothing AND the wrapped
        # function declares a Python default for its input — that's the
        # signal that "no input" is a legitimate way to invoke this action.
        if omitted and self._params.input_optional:
            return input
        # The sentinel isn't a value. A required parameter gets None, so
        # `str | None` runs with None and plain `str` reports the missing input.
        payload: object = None if omitted else input
        if self._input_type is None:
            return None if omitted else input
        # A differently-typed ModelRequest with a mapping config is dumped and
        # re-parsed into the plugin class. A Pydantic config instance of the
        # wrong class is a caller mistake — dump would silently coerce it.
        if isinstance(input, BaseModel):
            try:
                return self._input_type.validate_python(input)
            except ValidationError:
                config = getattr(input, config_field(self._kind) or 'config', None)
                if isinstance(config, BaseModel):
                    expected = declared_config_type(self._input_class) if self._input_class is not None else None
                    want = config_type_path(expected) if isinstance(expected, type) else 'the plugin config class'
                    raise _request_error(
                        GenkitError(
                            message=(
                                f"Invalid input for {self._kind_label} '{self.name}': "
                                f'{config_field(self._kind) or "config"} must be {want} or a mapping, '
                                f'got {config_type_path(type(config))}'
                            ),
                            status='INVALID_ARGUMENT',
                            reason=ErrorReason.INVALID_INPUT,
                        )
                    ) from None
                payload = input.model_dump(mode='python')

        try:
            return self._input_type.validate_python(payload)
        except ValidationError as e:
            msg = (
                f"{self._kind_label.capitalize()} '{self.name}' requires input but none was provided."
                if omitted
                else f"Invalid input for {self._kind_label} '{self.name}'"
            )
            raise _request_error(
                GenkitError(
                    message=msg,
                    status='INVALID_ARGUMENT',
                    # Nothing was passed, so Pydantic's "got None" would only mislead.
                    cause=None if omitted else e,
                    reason=ErrorReason.INVALID_INPUT,
                )
            ) from e

    async def _run_with_telemetry(
        self,
        input: object | None,
        ctx: ActionContext,
        on_trace_start: Callable[[str, str], Awaitable[None]] | None,
        telemetry_labels: dict[str, object] | None,
        *,
        execute: Callable[[], Awaitable[OutputT]] | None = None,
    ) -> ActionResponse[OutputT]:
        """Open the action span via ``run_in_new_span``, dispatch ``self._fn``, re-raise what it raised."""
        start_time = time.perf_counter()

        # ``telemetry_labels`` are caller-controlled passthrough attrs (e.g.
        # genkitx:ignore-trace, which the Developer UI filters on).
        # ``self._span_metadata`` uses short keys that land as genkit:metadata:<k>.
        extra_metadata: dict[str, str] = {k: str(v) for k, v in self._span_metadata.items()}
        # The Dev UI Context panel shows this dict. auth / secrets are what
        # the caller handed the action for the model or tools — write
        # placeholders so a shared trace dump does not leak them.
        if ctx.context:
            traced_context = context_for_telemetry(ctx.context)
            try:
                extra_metadata['context'] = json.dumps(traced_context)
            except Exception:
                try:
                    cleaned_context = _sanitize_value(traced_context)
                    extra_metadata['context'] = json.dumps(cleaned_context)
                except Exception:
                    extra_metadata['context'] = str(traced_context)

        trace_id: str = ''
        span_id: str = ''

        async def body(span: SpanContext) -> OutputT:
            nonlocal trace_id, span_id
            trace_id = span.trace_id
            span_id = span.span_id
            if on_trace_start:
                await on_trace_start(trace_id, span_id)

            is_tool = self._kind in (ActionKind.TOOL, ActionKind.TOOL_V2)
            tool_token = _inside_tool.set(True) if is_tool else None
            try:
                if execute is not None:
                    output = await execute()
                else:
                    output = await self._invoke(input, ctx)
            except Interrupt as e:
                # the Dev UI shows the interrupted icon off this key, so a bare
                # interrupt with nothing to say still needs it.
                span.set_metadata({'interrupt': e.metadata or True})
                # Only generate's tool loop turns an Interrupt into a pause.
                # With no tool above, it is a BaseException that `except
                # Exception` handlers (web adapters, agent transports) would
                # miss, so it becomes an error. Under a tool (a flow the tool
                # calls) it stays raw, so the tool's own catch-all can't
                # swallow the approval.
                if not is_tool and not _inside_tool.get():
                    raise interrupt_outside_tool_error(e) from e
                raise
            except TaskGroupError as e:
                # asyncio.TaskGroup / anyio wrap a child's Interrupt in a
                # BaseExceptionGroup, which every `except Exception` misses.
                failure = interrupt_escape_error(e)
                if failure is None:
                    raise
                raise failure from e
            finally:
                if tool_token is not None:
                    _inside_tool.reset(tool_token)
            if self._strict_io:
                output = self._validate_output(output)
            latency_ms = (time.perf_counter() - start_time) * 1000
            return cast(OutputT, _record_latency(output, latency_ms))

        attributes = {k: str(v) for k, v in (telemetry_labels or {}).items()}
        attributes.update({metadata_key(k): v for k, v in extra_metadata.items()})
        if ctx._init is not None:
            attributes[Attr.INIT] = to_json_attr(ctx._init)

        # A failure propagates as the body raised it. The trace id stays on
        # the span; nothing is written onto the caller's exception.
        output = await run_in_new_span(
            self._name,
            body,
            action_type=str(self._kind),
            input=None if input is NO_INPUT else input,
            attributes=attributes,
            is_action=True,
        )
        latency_ms = (time.perf_counter() - start_time) * 1000
        return ActionResponse(
            response=output,
            trace_id=trace_id,
            span_id=span_id,
            latency_ms=latency_ms,
        )

    def _validate_output(self, output: object) -> OutputT:
        """Give the caller what the flow's return annotation promises, or fail the run."""
        if self._output_type is None:
            return cast(OutputT, output)
        try:
            return self._output_type.validate_python(output)
        except ValidationError as e:
            # A bad return is the flow author's bug, not the caller's, so it's
            # INTERNAL rather than INVALID_ARGUMENT.
            raise GenkitError(
                message=f"Flow '{self.name}' returned a value that doesn't match its return annotation",
                status='INTERNAL',
                cause=e,
                reason=ErrorReason.INVALID_OUTPUT,
            ) from e

    async def _invoke(self, input: object | None, ctx: ActionContext) -> OutputT:
        """Call ``self._fn`` with the input and context.

        A missing input stays ``NO_INPUT`` so a defaulted parameter gets its
        default. An explicit None on a flow or tool is passed through as a value.
        """
        if self._fn_is_wrapper:
            # The wrapper takes (input, ctx) and forwards to the user's
            # function with self.params.call. Keep the sentinel so a
            # defaulted tool input is omitted there instead of becoming None.
            coro = self._fn(input, ctx)
        else:
            coro = self._params.call(self._fn, input, ctx)
        return await coro

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

ActionContext

Bases: typing.Generic[genkit._core._action.ChunkT]

Base execution context for a running action: request context and chunk streaming.

Exported in genkit.plugin_api for custom actions and BackgroundAction handlers, and subclassed publicly as genkit.FlowContext, genkit.ToolContext, genkit.model.ModelContext, genkit.embedder.EmbedContext, and genkit.exp.agent.AgentContext. ChunkT is the type send_chunk accepts.

@ai.flow
async def plate_dish(dish: str, ctx: FlowContext[str]) -> str:
    ctx.send_chunk('searing')
    return f'{dish} for {ctx.context.get("table", "walk-in")}'
Source code in packages/genkit/src/genkit/_core/_action.py
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
class ActionContext(Generic[ChunkT]):
    """Base execution context for a running action: request context and chunk streaming.

    Exported in ``genkit.plugin_api`` for custom actions and
    ``BackgroundAction`` handlers, and subclassed publicly as
    ``genkit.FlowContext``, ``genkit.ToolContext``,
    ``genkit.model.ModelContext``, ``genkit.embedder.EmbedContext``, and
    ``genkit.exp.agent.AgentContext``.
    ``ChunkT`` is the type ``send_chunk`` accepts.

        @ai.flow
        async def plate_dish(dish: str, ctx: FlowContext[str]) -> str:
            ctx.send_chunk('searing')
            return f'{dish} for {ctx.context.get("table", "walk-in")}'
    """

    def __init__(
        self,
        *,
        context: dict[str, Any] | None = None,
        streaming_callback: Callable[[ChunkT], None] | None = None,
        init: object | None = None,
        input_stream: AsyncIterator[object] | None = None,
    ) -> None:
        self._context: dict[str, Any] = context if context is not None else {}
        self._streaming_callback = streaming_callback
        # Bidi plumbing, read only by BidiAction: the session init value sent
        # on connection open, and the live stream of per-turn inputs.
        self._init: object | None = init
        self._input_stream: AsyncIterator[object] | None = input_stream

    @property
    def context(self) -> dict[str, Any]:
        """The request context (auth, headers, ...) the caller attached."""
        return self._context

    @property
    def is_streaming(self) -> bool:
        """True if a streaming callback is registered."""
        return self._streaming_callback is not None

    @property
    def streaming_callback(self) -> Callable[[ChunkT], None] | None:
        """The streaming callback, if any.

        Use this when you need to pass the callback to another action.
        For sending chunks directly, use send_chunk() instead.
        """
        return self._streaming_callback

    def send_chunk(self, chunk: ChunkT) -> None:
        """Send a streaming chunk to the client.

        Args:
            chunk: The chunk data to stream.
        """
        if self._streaming_callback is not None:
            self._streaming_callback(chunk)

    @staticmethod
    def _current_context() -> dict[str, Any] | None:
        return _action_context.get(None)

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

ActionKind

Bases: genkit._core._compat.StrEnum

Types of actions that can be registered.

Source code in packages/genkit/src/genkit/_core/_action.py
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
class ActionKind(StrEnum):
    """Types of actions that can be registered."""

    BACKGROUND_MODEL = 'background-model'
    AGENT = 'agent'
    AGENT_ABORT = 'agent-abort'
    AGENT_SNAPSHOT = 'agent-snapshot'
    CANCEL_OPERATION = 'cancel-operation'
    CHECK_OPERATION = 'check-operation'
    CUSTOM = 'custom'
    DYNAMIC_ACTION_PROVIDER = 'dynamic-action-provider'
    EMBEDDER = 'embedder'
    EVALUATOR = 'evaluator'
    EXECUTABLE_PROMPT = 'executable-prompt'
    FLOW = 'flow'
    MODEL = 'model'
    PROMPT = 'prompt'
    # A tool: run returns what the function returned. Generate runs this one.
    TOOL = 'tool'
    # The same tool returning the MultipartToolResponse envelope. The Dev UI
    # lists and runs this one when both exist (same as JS and Go).
    TOOL_V2 = 'tool.v2'
    UTIL = 'util'

BackgroundAction

Bases: typing.Generic[genkit._core._background.InT, genkit._core._background.OutT]

A handle over a background job's start, check and cancel actions.

A composite, not an Action: start, check and cancel each have their own registry key. start returns an Operation[OutT]; pass it to check until done. Subclass with concrete type arguments, e.g. class ReportJob(BackgroundAction[ReportRequest, Report]), and the handle's output validates as Report.

Every attribute is either a ClassVar derived from the type arguments or derived from the three actions in _bind, so a handle rebuilt from the registry (_from_actions) behaves like the one that was defined.

Example
# 1. Type the job by subclassing with concrete type arguments
class ReportJob(BackgroundAction[RenderRequest, Report]):
    pass


async def start(request: RenderRequest, ctx: ActionContext) -> Operation:
    return Operation(id=await renderer.submit(request.quarter))


async def check(op: Operation[Report], ctx: ActionContext) -> Operation:
    return await renderer.poll(op.id)


# 2. Build it; plugins return it from init() or resolve()
job = ReportJob('render-report', start, check, kind=ActionKind.CUSTOM)

# 3. The handle's output validates as Report
op = await job.check(await job.start(RenderRequest(quarter='q3')))
print(type(op.output).__name__)
# => Report
Source code in packages/genkit/src/genkit/_core/_background.py
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
class BackgroundAction(Generic[InT, OutT]):
    """A handle over a background job's start, check and cancel actions.

    A composite, not an ``Action``: start, check and cancel each have their
    own registry key. ``start`` returns an ``Operation[OutT]``; pass it to
    ``check`` until ``done``. Subclass with concrete type arguments, e.g.
    ``class ReportJob(BackgroundAction[ReportRequest, Report])``, and the
    handle's ``output`` validates as ``Report``.

    Every attribute is either a ClassVar derived from the type arguments or
    derived from the three actions in ``_bind``, so a handle rebuilt from the
    registry (``_from_actions``) behaves like the one that was defined.

    Example:
        ```python
        # 1. Type the job by subclassing with concrete type arguments
        class ReportJob(BackgroundAction[RenderRequest, Report]):
            pass


        async def start(request: RenderRequest, ctx: ActionContext) -> Operation:
            return Operation(id=await renderer.submit(request.quarter))


        async def check(op: Operation[Report], ctx: ActionContext) -> Operation:
            return await renderer.poll(op.id)


        # 2. Build it; plugins return it from init() or resolve()
        job = ReportJob('render-report', start, check, kind=ActionKind.CUSTOM)

        # 3. The handle's output validates as Report
        op = await job.check(await job.start(RenderRequest(quarter='q3')))
        print(type(op.output).__name__)
        # => Report
        ```
    """

    # Derived from the type arguments in __init_subclass__. None means Any.
    _input_type: ClassVar[type[Any] | None] = None
    _output_type: ClassVar[type[Any] | None] = None
    # How error messages name this kind of job.
    _noun: ClassVar[str] = 'Background action'
    _cancel_unsupported_reason: ClassVar[ErrorReason | None] = None

    start_action: Action
    check_action: Action
    cancel_action: Action | None

    def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
        """Read InT / OutT off ``class X(BackgroundAction[In, Out])``."""
        super().__init_subclass__(**kwargs)
        for base in getattr(cls, '__orig_bases__', ()):
            origin = get_origin(base)
            if isinstance(origin, type) and issubclass(origin, BackgroundAction):
                args = get_args(base)
                if len(args) == 2:
                    cls._input_type = _concrete_type(args[0])
                    cls._output_type = _concrete_type(args[1])

    def __init__(
        self,
        name: str,
        start: StartOpFn[InT],
        check: Callable[[Operation[OutT], ActionContext], Awaitable[Operation]],
        *,
        kind: ActionKind,
        cancel: Callable[[Operation[OutT], ActionContext], Awaitable[Operation]] | None = None,
        metadata: dict[str, Any] | None = None,
        description: str | None = None,
    ) -> None:
        """Build a background action without registering it.

        Args:
            name: The start action's name. Check and cancel are
                ``{name}/check`` and ``{name}/cancel``.
            start: Starts the job and returns an ``Operation``.
            check: Polls an ``Operation[OutT]``.
            kind: The start action's kind; it is the first segment of the
                ``action`` key stamped on every handle.
            cancel: Optional; without it ``cancel`` raises UNIMPLEMENTED.
            metadata: Copied onto all three actions, like JS/Go.
            description: The start action's description.
        """
        self._bind(
            *operation_actions(
                type(self),
                name,
                kind=kind,
                start=start,
                check=check,
                cancel=cancel,
                metadata=metadata,
                description=description,
            )
        )

    def _bind(self, start: Action, check: Action, cancel: Action | None) -> None:
        """The only writer of instance state. Subclasses derive extra fields here."""
        self.start_action = start
        self.check_action = check
        self.cancel_action = cancel

    @classmethod
    def _from_actions(cls, start: Action, check: Action, cancel: Action | None = None) -> Self:
        """Rebuild from registered actions without re-running the fn wrapping."""
        obj = cls.__new__(cls)
        obj._bind(start, check, cancel)
        return obj

    @classmethod
    async def lookup(cls, registry: Registry, key: str) -> Self | None:
        """Look up a background action by its start action key.

        Matches JS ``lookupBackgroundAction``. The key format is
        ``/{actionType}/{name}``, e.g. ``/background-model/video-gen``.
        """
        start_action = await registry.resolve_action_by_key(key)
        if start_action is None:
            return None
        # JS: const actionName = key.substring(key.indexOf('/', 1) + 1);
        parts = key.split('/', 2)  # ['', 'background-model', 'name']
        if len(parts) < 3:
            return None
        action_name = parts[2]
        check_action = await registry.resolve_action_by_key(f'/{ActionKind.CHECK_OPERATION}/{action_name}/check')
        if check_action is None:
            return None
        cancel_action = await registry.resolve_action_by_key(f'/{ActionKind.CANCEL_OPERATION}/{action_name}/cancel')
        return cls._from_actions(start_action, check_action, cancel_action)

    @property
    def name(self) -> str:
        """The name of the start action."""
        return self.start_action.name

    @property
    def kind(self) -> ActionKind:
        """The action kind of the start action."""
        return self.start_action.kind

    @property
    def metadata(self) -> dict[str, Any]:
        """The start action's metadata."""
        return self.start_action.metadata

    @property
    def input_schema(self) -> dict[str, Any] | None:
        """The start action's input JSON schema."""
        return self.start_action.input_schema

    @property
    def output_schema(self) -> dict[str, Any] | None:
        """The start action's output JSON schema (the Operation)."""
        return self.start_action.output_schema

    @property
    def supports_cancel(self) -> bool:
        """Whether this background action supports cancellation."""
        return self.cancel_action is not None

    @property
    def actions(self) -> list[Action]:
        """The start, check and (if any) cancel actions, for registering or listing.

        A background action is three registered actions, not one. Register all
        of them, or a poll fails later with the check action not found.
        """
        actions = [self.start_action, self.check_action]
        if self.cancel_action is not None:
            actions.append(self.cancel_action)
        return actions

    def _action_metadata(self) -> ActionMetadata:
        """Listed once, as the start action, for Registry.list_actions()."""
        return self.start_action._action_metadata()

    def _rename(self, name: str) -> None:
        """Name start ``name``, check ``name/check``, cancel ``name/cancel``."""
        set_action_name(self.start_action, name)
        set_action_name(self.check_action, f'{name}/check')
        if self.cancel_action is not None:
            set_action_name(self.cancel_action, f'{name}/cancel')

    def _action_for(self, kind: ActionKind) -> Action | None:
        """The member action a lookup of ``kind`` wants: check, cancel, or start."""
        if kind == ActionKind.CHECK_OPERATION:
            return self.check_action
        if kind == ActionKind.CANCEL_OPERATION:
            return self.cancel_action
        return self.start_action

    def _require_handle(self, value: object) -> Operation[OutT]:
        """A caller's handle (Operation or stored dict) as ``Operation[OutT]``."""
        return require_operation(value=value, output_type=self._output_type)

    def _ensure_operation(self, *, response: object, name: str) -> Operation[OutT]:
        """A start/check/cancel fn returns an Operation, not a dict."""
        if isinstance(response, Operation):
            return validate_operation(response, output_type=self._output_type, name=name, status='INTERNAL')
        raise missing_operation_error(name=name)

    async def start(
        self,
        input: InT | None = None,  # noqa: A002
        *,
        context: dict[str, Any] | None = None,
    ) -> Operation[OutT]:
        """Start a background operation.

        Args:
            input: The start request.
            context: Optional run context. Per-request keys go in
                ``context['secrets']``.

        Returns:
            An Operation with an ID to track the job.
        """
        # Same pocket as check/cancel: a tenant key on start has to reach the
        # plugin, not die on this wrapper.
        result = await self.start_action.run(input, context=context)
        return self._ensure_operation(response=result.response, name=self.start_action.name)

    async def check(
        self,
        operation: Operation | Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
    ) -> Operation[OutT]:
        """Check the status of a background operation.

        Args:
            operation: The operation to check, or the dict a stored one
                dumped to.
            context: Optional run context (secrets, folded client config).

        Raises:
            GenkitError: INVALID_ARGUMENT if ``operation`` is not an
                ``Operation`` or a dict that validates as one.
        """
        operation = self._require_handle(operation)
        result = await self.check_action.run(operation, context=context)
        return self._ensure_operation(response=result.response, name=self.check_action.name)

    async def cancel(
        self,
        operation: Operation | Mapping[str, Any],
        *,
        context: dict[str, Any] | None = None,
    ) -> Operation[OutT]:
        """Cancel a background operation.

        Args:
            operation: The operation to cancel, or the dict a stored one
                dumped to.
            context: Optional run context (secrets, folded client config).

        Raises:
            GenkitError: UNIMPLEMENTED if this action does not implement
                cancel, INVALID_ARGUMENT if ``operation`` is not an
                ``Operation`` or a dict that validates as one.
        """
        operation = self._require_handle(operation)
        # Raising here is deliberate: returning the operation unchanged would
        # make "can't cancel" indistinguishable from "cancelled".
        if self.cancel_action is None:
            raise GenkitError(
                status='UNIMPLEMENTED',
                message=f'{self._noun} {operation.action} does not support cancellation.',
                reason=self._cancel_unsupported_reason,
            )
        result = await self.cancel_action.run(operation, context=context)
        return self._ensure_operation(response=result.response, name=self.cancel_action.name)

actions property

The start, check and (if any) cancel actions, for registering or listing.

A background action is three registered actions, not one. Register all of them, or a poll fails later with the check action not found.

input_schema property

The start action's input JSON schema.

kind property

The action kind of the start action.

metadata property

The start action's metadata.

name property

The name of the start action.

output_schema property

The start action's output JSON schema (the Operation).

supports_cancel property

Whether this background action supports cancellation.

__init__(name, start, check, *, kind, cancel=None, metadata=None, description=None)

Build a background action without registering it.

Parameters:

Name Type Description Default
name str

The start action's name. Check and cancel are {name}/check and {name}/cancel.

required
start genkit._core._background.StartOpFn[genkit._core._background.InT]

Starts the job and returns an Operation.

required
check collections.abc.Callable[[genkit._core._operation.Operation[genkit._core._background.OutT], genkit._core._action.ActionContext], collections.abc.Awaitable[genkit._core._operation.Operation]]

Polls an Operation[OutT].

required
kind genkit._core._action.ActionKind

The start action's kind; it is the first segment of the action key stamped on every handle.

required
cancel collections.abc.Callable[[genkit._core._operation.Operation[genkit._core._background.OutT], genkit._core._action.ActionContext], collections.abc.Awaitable[genkit._core._operation.Operation]] | None

Optional; without it cancel raises UNIMPLEMENTED.

None
metadata dict[str, typing.Any] | None

Copied onto all three actions, like JS/Go.

None
description str | None

The start action's description.

None
Source code in packages/genkit/src/genkit/_core/_background.py
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
def __init__(
    self,
    name: str,
    start: StartOpFn[InT],
    check: Callable[[Operation[OutT], ActionContext], Awaitable[Operation]],
    *,
    kind: ActionKind,
    cancel: Callable[[Operation[OutT], ActionContext], Awaitable[Operation]] | None = None,
    metadata: dict[str, Any] | None = None,
    description: str | None = None,
) -> None:
    """Build a background action without registering it.

    Args:
        name: The start action's name. Check and cancel are
            ``{name}/check`` and ``{name}/cancel``.
        start: Starts the job and returns an ``Operation``.
        check: Polls an ``Operation[OutT]``.
        kind: The start action's kind; it is the first segment of the
            ``action`` key stamped on every handle.
        cancel: Optional; without it ``cancel`` raises UNIMPLEMENTED.
        metadata: Copied onto all three actions, like JS/Go.
        description: The start action's description.
    """
    self._bind(
        *operation_actions(
            type(self),
            name,
            kind=kind,
            start=start,
            check=check,
            cancel=cancel,
            metadata=metadata,
            description=description,
        )
    )

__init_subclass__(**kwargs)

Read InT / OutT off class X(BackgroundAction[In, Out]).

Source code in packages/genkit/src/genkit/_core/_background.py
234
235
236
237
238
239
240
241
242
243
def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
    """Read InT / OutT off ``class X(BackgroundAction[In, Out])``."""
    super().__init_subclass__(**kwargs)
    for base in getattr(cls, '__orig_bases__', ()):
        origin = get_origin(base)
        if isinstance(origin, type) and issubclass(origin, BackgroundAction):
            args = get_args(base)
            if len(args) == 2:
                cls._input_type = _concrete_type(args[0])
                cls._output_type = _concrete_type(args[1])

cancel(operation, *, context=None) async

Cancel a background operation.

Parameters:

Name Type Description Default
operation genkit._core._operation.Operation | collections.abc.Mapping[str, typing.Any]

The operation to cancel, or the dict a stored one dumped to.

required
context dict[str, typing.Any] | None

Optional run context (secrets, folded client config).

None

Raises:

Type Description
genkit._core._error.GenkitError

UNIMPLEMENTED if this action does not implement cancel, INVALID_ARGUMENT if operation is not an Operation or a dict that validates as one.

Source code in packages/genkit/src/genkit/_core/_background.py
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
async def cancel(
    self,
    operation: Operation | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
) -> Operation[OutT]:
    """Cancel a background operation.

    Args:
        operation: The operation to cancel, or the dict a stored one
            dumped to.
        context: Optional run context (secrets, folded client config).

    Raises:
        GenkitError: UNIMPLEMENTED if this action does not implement
            cancel, INVALID_ARGUMENT if ``operation`` is not an
            ``Operation`` or a dict that validates as one.
    """
    operation = self._require_handle(operation)
    # Raising here is deliberate: returning the operation unchanged would
    # make "can't cancel" indistinguishable from "cancelled".
    if self.cancel_action is None:
        raise GenkitError(
            status='UNIMPLEMENTED',
            message=f'{self._noun} {operation.action} does not support cancellation.',
            reason=self._cancel_unsupported_reason,
        )
    result = await self.cancel_action.run(operation, context=context)
    return self._ensure_operation(response=result.response, name=self.cancel_action.name)

check(operation, *, context=None) async

Check the status of a background operation.

Parameters:

Name Type Description Default
operation genkit._core._operation.Operation | collections.abc.Mapping[str, typing.Any]

The operation to check, or the dict a stored one dumped to.

required
context dict[str, typing.Any] | None

Optional run context (secrets, folded client config).

None

Raises:

Type Description
genkit._core._error.GenkitError

INVALID_ARGUMENT if operation is not an Operation or a dict that validates as one.

Source code in packages/genkit/src/genkit/_core/_background.py
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
async def check(
    self,
    operation: Operation | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
) -> Operation[OutT]:
    """Check the status of a background operation.

    Args:
        operation: The operation to check, or the dict a stored one
            dumped to.
        context: Optional run context (secrets, folded client config).

    Raises:
        GenkitError: INVALID_ARGUMENT if ``operation`` is not an
            ``Operation`` or a dict that validates as one.
    """
    operation = self._require_handle(operation)
    result = await self.check_action.run(operation, context=context)
    return self._ensure_operation(response=result.response, name=self.check_action.name)

lookup(registry, key) async classmethod

Look up a background action by its start action key.

Matches JS lookupBackgroundAction. The key format is /{actionType}/{name}, e.g. /background-model/video-gen.

Source code in packages/genkit/src/genkit/_core/_background.py
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
@classmethod
async def lookup(cls, registry: Registry, key: str) -> Self | None:
    """Look up a background action by its start action key.

    Matches JS ``lookupBackgroundAction``. The key format is
    ``/{actionType}/{name}``, e.g. ``/background-model/video-gen``.
    """
    start_action = await registry.resolve_action_by_key(key)
    if start_action is None:
        return None
    # JS: const actionName = key.substring(key.indexOf('/', 1) + 1);
    parts = key.split('/', 2)  # ['', 'background-model', 'name']
    if len(parts) < 3:
        return None
    action_name = parts[2]
    check_action = await registry.resolve_action_by_key(f'/{ActionKind.CHECK_OPERATION}/{action_name}/check')
    if check_action is None:
        return None
    cancel_action = await registry.resolve_action_by_key(f'/{ActionKind.CANCEL_OPERATION}/{action_name}/cancel')
    return cls._from_actions(start_action, check_action, cancel_action)

start(input=None, *, context=None) async

Start a background operation.

Parameters:

Name Type Description Default
input genkit._core._background.InT | None

The start request.

None
context dict[str, typing.Any] | None

Optional run context. Per-request keys go in context['secrets'].

None

Returns:

Type Description
genkit._core._operation.Operation[genkit._core._background.OutT]

An Operation with an ID to track the job.

Source code in packages/genkit/src/genkit/_core/_background.py
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
async def start(
    self,
    input: InT | None = None,  # noqa: A002
    *,
    context: dict[str, Any] | None = None,
) -> Operation[OutT]:
    """Start a background operation.

    Args:
        input: The start request.
        context: Optional run context. Per-request keys go in
            ``context['secrets']``.

    Returns:
        An Operation with an ID to track the job.
    """
    # Same pocket as check/cancel: a tenant key on start has to reach the
    # plugin, not die on this wrapper.
    result = await self.start_action.run(input, context=context)
    return self._ensure_operation(response=result.response, name=self.start_action.name)

DynamicActionProvider

Lazily resolves actions from an external source with TTL caching.

The cached actions are shared by every event loop that lists this provider, so an action returned by dap_fn must resolve any loop-bound resource of its own when it is called, not when it is listed. In-flight fetches are coalesced per loop, because a task cannot be awaited from a loop other than the one that created it.

The cache is one attribute holding both the value and its expiry, so a reader takes a consistent pair in a single read and an invalidation from another thread cannot land between the two.

Source code in packages/genkit/src/genkit/_core/_dap.py
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
class DynamicActionProvider:
    """Lazily resolves actions from an external source with TTL caching.

    The cached actions are shared by every event loop that lists this provider,
    so an action returned by ``dap_fn`` must resolve any loop-bound resource of
    its own when it is called, not when it is listed. In-flight fetches are
    coalesced per loop, because a task cannot be awaited from a loop other than
    the one that created it.

    The cache is one attribute holding both the value and its expiry, so a
    reader takes a consistent pair in a single read and an invalidation from
    another thread cannot land between the two.
    """

    def __init__(
        self,
        action: Action[Any, Any],
        dap_fn: DapFn,
        cache_ttl_millis: int | None = None,
    ) -> None:
        self.action = action
        # Stamp the provider on its action so a ``dap.action`` returned from
        # ``Plugin.init()`` expands in ``list_actions`` and DAP-qualified lookups,
        # not only one registered through ``define_dynamic_action_provider``.
        setattr(action, GENKIT_DYNAMIC_ACTION_PROVIDER_ATTR, self)
        self._dap_fn = dap_fn
        self._cache: tuple[DapValue, float] | None = None
        self._fetch_tasks: dict[asyncio.AbstractEventLoop, asyncio.Task[DapValue]] = {}
        self._fetch_tasks_lock = threading.Lock()
        self._ttl_millis = (
            _DEFAULT_CACHE_TTL_MS if cache_ttl_millis is None or cache_ttl_millis == 0 else cache_ttl_millis
        )

    def invalidate_cache(self) -> None:
        """Drop the cached actions so the next call fetches them again."""
        self._cache = None

    async def _get_or_fetch(self, skip_trace: bool = False) -> DapValue:
        """Get cached value or fetch fresh data, coalescing concurrent fetches per loop."""
        cached = self._cache
        if cached is not None and self._ttl_millis >= 0:
            value, expires_at = cached
            if time.time() * 1000 <= expires_at:
                return value

        loop = asyncio.get_running_loop()
        with self._fetch_tasks_lock:
            # A pending task strongly references its loop, so weak keys never fire.
            for ended in [known for known in self._fetch_tasks if known.is_closed()]:
                del self._fetch_tasks[ended]
            task = self._fetch_tasks.get(loop)
            if task is None:
                task = asyncio.create_task(self._do_fetch(skip_trace))
                self._fetch_tasks[loop] = task
                task.add_done_callback(self._forget_fetch(loop))

        # Shielded, so a caller that is cancelled cannot cancel the fetch every
        # other caller on this loop is waiting on.
        return await asyncio.shield(task)

    def _forget_fetch(self, loop: asyncio.AbstractEventLoop) -> Callable[[asyncio.Task[DapValue]], None]:
        """Build the callback that drops a finished fetch from the per-loop table.

        Cleanup belongs to the task rather than to whichever caller started it,
        because a shielded caller can be cancelled while the fetch it started
        keeps running, and dropping the entry then would uncoalesce it.
        """

        def forget(task: asyncio.Task[DapValue]) -> None:
            with self._fetch_tasks_lock:
                if self._fetch_tasks.get(loop) is task:
                    del self._fetch_tasks[loop]
            # Cancelling the last shielded caller unhooks shield's own retrieval,
            # so the fetch must take its outcome or asyncio reports it unretrieved.
            if not task.cancelled():
                task.exception()

        return forget

    async def _do_fetch(self, skip_trace: bool) -> DapValue:
        try:
            value = await self._dap_fn()
            self._cache = (value, time.time() * 1000 + self._ttl_millis)
            if not skip_trace:
                metadata = {k: [a.metadata or {} for a in v] for k, v in value.items()}
                await self.action.run(metadata)
            return value
        except Exception:
            self.invalidate_cache()
            raise

    async def get_action(self, action_type: str, action_name: str) -> Action[Any, Any] | None:
        result = await self._get_or_fetch()
        for action in result.get(action_type, []):
            if action.name == action_name:
                return action
        return None

    async def list_action_metadata(self, action_type: str, action_name: str) -> list[ActionMetadataLike]:
        """List metadata matching pattern: '*'=all, 'prefix*'=prefix match, else exact."""
        result = await self._get_or_fetch()
        actions: list[Action[Any, Any]] = []
        seen: set[str] = set()
        for action in result.get(action_type, []):
            if action.name in seen:
                continue
            seen.add(action.name)
            actions.append(action)
        if not actions:
            return []

        metadata_list: list[ActionMetadataLike] = [action.metadata or {} for action in actions]

        if action_name == '*':
            return metadata_list
        if action_name.endswith('*'):
            prefix = action_name[:-1]
            return [m for m in metadata_list if str(m.get('name', '')).startswith(prefix)]
        return [m for m in metadata_list if m.get('name') == action_name]

    async def list_action_metadata_by_key(self, dap_prefix: str) -> dict[str, ActionMetadata]:
        """List every child action's reflection metadata, keyed by its fully-qualified DAP key."""
        result = await self._get_or_fetch(skip_trace=True)
        dap_actions: dict[str, ActionMetadata] = {}
        for action_type, actions in result.items():
            for action in actions:
                if not action.name:
                    raise ValueError(f'Invalid metadata from {dap_prefix} - name required')
                listed_type = action_type
                key = create_action_key(
                    ActionKind.DYNAMIC_ACTION_PROVIDER,
                    f'{dap_prefix}:{listed_type}/{action.name}',
                )
                dap_actions[key] = ActionMetadata(
                    key=key,
                    action_type=listed_type,
                    name=action.name,
                    description=action.description,
                    input_schema=action.input_schema,
                    output_schema=action.output_schema,
                    metadata=dict(action.metadata) if action.metadata else None,
                )
        return dap_actions

invalidate_cache()

Drop the cached actions so the next call fetches them again.

Source code in packages/genkit/src/genkit/_core/_dap.py
75
76
77
def invalidate_cache(self) -> None:
    """Drop the cached actions so the next call fetches them again."""
    self._cache = None

list_action_metadata(action_type, action_name) async

List metadata matching pattern: ''=all, 'prefix'=prefix match, else exact.

Source code in packages/genkit/src/genkit/_core/_dap.py
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
async def list_action_metadata(self, action_type: str, action_name: str) -> list[ActionMetadataLike]:
    """List metadata matching pattern: '*'=all, 'prefix*'=prefix match, else exact."""
    result = await self._get_or_fetch()
    actions: list[Action[Any, Any]] = []
    seen: set[str] = set()
    for action in result.get(action_type, []):
        if action.name in seen:
            continue
        seen.add(action.name)
        actions.append(action)
    if not actions:
        return []

    metadata_list: list[ActionMetadataLike] = [action.metadata or {} for action in actions]

    if action_name == '*':
        return metadata_list
    if action_name.endswith('*'):
        prefix = action_name[:-1]
        return [m for m in metadata_list if str(m.get('name', '')).startswith(prefix)]
    return [m for m in metadata_list if m.get('name') == action_name]

list_action_metadata_by_key(dap_prefix) async

List every child action's reflection metadata, keyed by its fully-qualified DAP key.

Source code in packages/genkit/src/genkit/_core/_dap.py
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
async def list_action_metadata_by_key(self, dap_prefix: str) -> dict[str, ActionMetadata]:
    """List every child action's reflection metadata, keyed by its fully-qualified DAP key."""
    result = await self._get_or_fetch(skip_trace=True)
    dap_actions: dict[str, ActionMetadata] = {}
    for action_type, actions in result.items():
        for action in actions:
            if not action.name:
                raise ValueError(f'Invalid metadata from {dap_prefix} - name required')
            listed_type = action_type
            key = create_action_key(
                ActionKind.DYNAMIC_ACTION_PROVIDER,
                f'{dap_prefix}:{listed_type}/{action.name}',
            )
            dap_actions[key] = ActionMetadata(
                key=key,
                action_type=listed_type,
                name=action.name,
                description=action.description,
                input_schema=action.input_schema,
                output_schema=action.output_schema,
                metadata=dict(action.metadata) if action.metadata else None,
            )
    return dap_actions

GenkitConfig

Bases: pydantic.BaseModel

Base for settings passed to a Genkit action: model and middleware config.

Python callers construct it with field names (snake_case), and plugins hand model_dump() output to provider SDKs. Genkit's tooling sees camelCase JSON: the Developer UI renders the JSON schema as a form, pre-fills it from traces and .prompt files by exact key, and exports .prompt files from it. Those formats are shared with the JS and Go SDKs, so the schema keys, trace keys and .prompt keys must use one spelling.

  • alias_generator=to_camel: camelCase wire names and schema properties.
  • validate_by_name / validate_by_alias: accept either spelling; all three type checkers take the snake_case kwarg.
  • extra='forbid': an unknown key raises instead of being dropped, and so does a second spelling of a key already given (maxOutputTokens and max_output_tokens in one input).

model_dump() is not overridden: standalone dumps return snake_case field names and keep None values. Pass by_alias=True for Genkit JSON. Nested inside a GenkitModel (such as ModelRequest.config), _serialize_in_genkit_model applies wire defaults (by_alias=True, exclude_none=True) automatically, even when the outer dump started from a plain BaseModel.

Use plain BaseModel for flow and tool input/output; that data is the app's, and Genkit does not rename it. An app's own middleware config may also be a plain BaseModel: its keys are its field names everywhere, and unknown keys still raise.

Source code in packages/genkit/src/genkit/_core/_base.py
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
class GenkitConfig(BaseModel):
    """Base for settings passed to a Genkit action: model and middleware config.

    Python callers construct it with field names (snake_case), and plugins
    hand model_dump() output to provider SDKs. Genkit's tooling sees
    camelCase JSON: the Developer UI renders the JSON schema as a form,
    pre-fills it from traces and .prompt files by exact key, and exports
    .prompt files from it. Those formats are shared with the JS and Go SDKs,
    so the schema keys, trace keys and .prompt keys must use one spelling.

    - alias_generator=to_camel: camelCase wire names and schema properties.
    - validate_by_name / validate_by_alias: accept either spelling; all three
      type checkers take the snake_case kwarg.
    - extra='forbid': an unknown key raises instead of being dropped, and so
      does a second spelling of a key already given (maxOutputTokens and
      max_output_tokens in one input).

    model_dump() is not overridden: standalone dumps return snake_case field
    names and keep None values. Pass by_alias=True for Genkit JSON. Nested
    inside a GenkitModel (such as ModelRequest.config), _serialize_in_genkit_model
    applies wire defaults (by_alias=True, exclude_none=True) automatically,
    even when the outer dump started from a plain BaseModel.

    Use plain BaseModel for flow and tool input/output; that data is the
    app's, and Genkit does not rename it. An app's own middleware config may
    also be a plain BaseModel: its keys are its field names everywhere, and
    unknown keys still raise.
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel,
        extra='forbid',
        validate_by_name=True,
        validate_by_alias=True,
    )

    # No return annotation for the same schema reason as GenkitModel._serialize_wire.
    @model_serializer(mode='wrap')
    def _serialize_in_genkit_model(  # noqa: ANN202
        self,
        handler: SerializerFunctionWrapHandler,
        info: SerializationInfo,
    ):
        if _IN_GENKIT_MODEL_SERIALIZE.get() and (info.by_alias is None or not info.exclude_none):
            return _dump_config_as_wire(self, info)
        return handler(self)

Plugin

Bases: abc.ABC

Abstract base class for Genkit plugins.

Source code in packages/genkit/src/genkit/_core/_plugin.py
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
class Plugin(abc.ABC):
    """Abstract base class for Genkit plugins."""

    name: str  # plugin namespace

    @abc.abstractmethod
    async def init(self) -> Sequence[Action | BackgroundAction[Any, Any]]:
        """Lazy warm-up called once per plugin; return actions to pre-register.

        A ``BackgroundAction`` (e.g. a ``BackgroundModel``) registers its start,
        check and cancel actions together. ``Sequence`` so an override that
        returns ``list[Action]`` still type-checks.

        Return names with or without the ``{plugin.name}/`` prefix. A name that
        doesn't start with it is registered under ``{plugin.name}/{name}`` with
        the whole name kept: ``endpoints/123`` becomes ``myplug/endpoints/123``,
        and ``other/x`` becomes ``myplug/other/x``. See :meth:`resolve`.
        """
        ...

    @abc.abstractmethod
    async def resolve(self, action_type: ActionKind, name: str) -> Action | BackgroundAction[Any, Any] | None:
        """Resolve a single action by kind and its id inside this plugin.

        Return a ``BackgroundAction`` (e.g. a ``BackgroundModel``) for a
        background job. Genkit registers its start, check and cancel actions
        together, so a later ``/check-operation/{name}/check`` lookup finds the
        check action without the plugin routing it. If ``resolve`` returns
        ``None`` for a check or cancel key, Genkit asks again with
        ``ActionKind.BACKGROUND_MODEL`` and the start id.

        Naming rule. When an app asks for ``{plugin.name}/{rest}``:

        1. Genkit removes exactly one ``{plugin.name}/`` from the front and
           passes ``rest`` as ``name``. That's the provider's id, verbatim:
           send it upstream unchanged and don't strip anything from it.
           Provider ids may contain slashes (publisher paths, tuned
           endpoints, ARNs, OpenRouter ids).
        2. The returned action is renamed to exactly what the app asked for
           and stored there, whatever name the plugin gave it, so the same
           string always looks up the same action.

        Return ``None`` to decline; the caller then gets NOT_FOUND.

        Example:
            ```python
            from genkit import Genkit
            from genkit.plugin_api import ActionKind
            from genkit_openai import OpenAI

            # 1. Point the OpenAI plugin at OpenRouter, whose ids carry a vendor
            ai = Genkit(plugins=[OpenAI(base_url='https://openrouter.ai/api/v1')])

            # 2. One `openai/` is the plugin; the rest is the OpenRouter id
            response = await ai.generate(model='openai/openai/gpt-4o', prompt='Suggest a dish.')
            # => resolve(ActionKind.MODEL, 'openai/gpt-4o')
            #    request sent with model='openai/gpt-4o'

            # 3. The action lives under the id the app typed
            action = await ai.lookup_model('openai/openai/gpt-4o')
            print(action.name)
            # => openai/openai/gpt-4o
            ```
        """
        ...

    @abc.abstractmethod
    async def list_actions(self) -> Sequence[Action | BackgroundAction[Any, Any]]:
        """Return advertised actions for dev UI/reflection listing.

        A ``BackgroundAction`` is listed once, under its start action. Each
        returned action's ``name`` must match resolution keys (typically
        ``{plugin.name}/localName`` for plugin-backed actions).
        """
        ...

    def list_middleware(self) -> Sequence[type[Middleware]]:
        """Return middleware classes this plugin registers on the app. Defaults to none.

        Runs once while :class:`Genkit` is constructed, after built-in
        middleware. Each returned :class:`~genkit.middleware.Middleware`
        subclass is registered under its ``cls.name`` via
        :meth:`Genkit.define_middleware() <genkit.Genkit.define_middleware>`.

        Example:
            ```python
            from genkit import Genkit
            from genkit.middleware import Middleware
            from typing import Any

            from genkit.plugin_api import Action, ActionKind, BackgroundAction, Plugin


            # 1. Define a middleware class with a registry name
            class AllergyCheck(Middleware):
                name = 'allergy_check'


            # 2. A plugin that contributes the middleware class
            class AllergyGuard(Plugin):
                name = 'allergy-guard'

                async def init(self) -> list[Action | BackgroundAction[Any, Any]]:
                    return []

                async def resolve(self, kind: ActionKind, name: str) -> Action | BackgroundAction[Any, Any] | None:
                    return None

                async def list_actions(self) -> list[Action]:
                    return []

                def list_middleware(self) -> list[type[Middleware]]:
                    return [AllergyCheck]


            # 3. Register the plugin and pass the middleware in use=[...]
            ai = Genkit(plugins=[AllergyGuard()])
            res = await ai.generate(prompt='Suggest a dish.', use=[AllergyCheck()])
            # => AllergyCheck runs around the model call
            ```
        """
        return []

init() abstractmethod async

Lazy warm-up called once per plugin; return actions to pre-register.

A BackgroundAction (e.g. a BackgroundModel) registers its start, check and cancel actions together. Sequence so an override that returns list[Action] still type-checks.

Return names with or without the {plugin.name}/ prefix. A name that doesn't start with it is registered under {plugin.name}/{name} with the whole name kept: endpoints/123 becomes myplug/endpoints/123, and other/x becomes myplug/other/x. See :meth:resolve.

Source code in packages/genkit/src/genkit/_core/_plugin.py
45
46
47
48
49
50
51
52
53
54
55
56
57
58
@abc.abstractmethod
async def init(self) -> Sequence[Action | BackgroundAction[Any, Any]]:
    """Lazy warm-up called once per plugin; return actions to pre-register.

    A ``BackgroundAction`` (e.g. a ``BackgroundModel``) registers its start,
    check and cancel actions together. ``Sequence`` so an override that
    returns ``list[Action]`` still type-checks.

    Return names with or without the ``{plugin.name}/`` prefix. A name that
    doesn't start with it is registered under ``{plugin.name}/{name}`` with
    the whole name kept: ``endpoints/123`` becomes ``myplug/endpoints/123``,
    and ``other/x`` becomes ``myplug/other/x``. See :meth:`resolve`.
    """
    ...

list_actions() abstractmethod async

Return advertised actions for dev UI/reflection listing.

A BackgroundAction is listed once, under its start action. Each returned action's name must match resolution keys (typically {plugin.name}/localName for plugin-backed actions).

Source code in packages/genkit/src/genkit/_core/_plugin.py
106
107
108
109
110
111
112
113
114
@abc.abstractmethod
async def list_actions(self) -> Sequence[Action | BackgroundAction[Any, Any]]:
    """Return advertised actions for dev UI/reflection listing.

    A ``BackgroundAction`` is listed once, under its start action. Each
    returned action's ``name`` must match resolution keys (typically
    ``{plugin.name}/localName`` for plugin-backed actions).
    """
    ...

list_middleware()

Return middleware classes this plugin registers on the app. Defaults to none.

Runs once while :class:Genkit is constructed, after built-in middleware. Each returned :class:~genkit.middleware.Middleware subclass is registered under its cls.name via :meth:Genkit.define_middleware() <genkit.Genkit.define_middleware>.

Example
from genkit import Genkit
from genkit.middleware import Middleware
from typing import Any

from genkit.plugin_api import Action, ActionKind, BackgroundAction, Plugin


# 1. Define a middleware class with a registry name
class AllergyCheck(Middleware):
    name = 'allergy_check'


# 2. A plugin that contributes the middleware class
class AllergyGuard(Plugin):
    name = 'allergy-guard'

    async def init(self) -> list[Action | BackgroundAction[Any, Any]]:
        return []

    async def resolve(self, kind: ActionKind, name: str) -> Action | BackgroundAction[Any, Any] | None:
        return None

    async def list_actions(self) -> list[Action]:
        return []

    def list_middleware(self) -> list[type[Middleware]]:
        return [AllergyCheck]


# 3. Register the plugin and pass the middleware in use=[...]
ai = Genkit(plugins=[AllergyGuard()])
res = await ai.generate(prompt='Suggest a dish.', use=[AllergyCheck()])
# => AllergyCheck runs around the model call
Source code in packages/genkit/src/genkit/_core/_plugin.py
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
def list_middleware(self) -> Sequence[type[Middleware]]:
    """Return middleware classes this plugin registers on the app. Defaults to none.

    Runs once while :class:`Genkit` is constructed, after built-in
    middleware. Each returned :class:`~genkit.middleware.Middleware`
    subclass is registered under its ``cls.name`` via
    :meth:`Genkit.define_middleware() <genkit.Genkit.define_middleware>`.

    Example:
        ```python
        from genkit import Genkit
        from genkit.middleware import Middleware
        from typing import Any

        from genkit.plugin_api import Action, ActionKind, BackgroundAction, Plugin


        # 1. Define a middleware class with a registry name
        class AllergyCheck(Middleware):
            name = 'allergy_check'


        # 2. A plugin that contributes the middleware class
        class AllergyGuard(Plugin):
            name = 'allergy-guard'

            async def init(self) -> list[Action | BackgroundAction[Any, Any]]:
                return []

            async def resolve(self, kind: ActionKind, name: str) -> Action | BackgroundAction[Any, Any] | None:
                return None

            async def list_actions(self) -> list[Action]:
                return []

            def list_middleware(self) -> list[type[Middleware]]:
                return [AllergyCheck]


        # 3. Register the plugin and pass the middleware in use=[...]
        ai = Genkit(plugins=[AllergyGuard()])
        res = await ai.generate(prompt='Suggest a dish.', use=[AllergyCheck()])
        # => AllergyCheck runs around the model call
        ```
    """
    return []

resolve(action_type, name) abstractmethod async

Resolve a single action by kind and its id inside this plugin.

Return a BackgroundAction (e.g. a BackgroundModel) for a background job. Genkit registers its start, check and cancel actions together, so a later /check-operation/{name}/check lookup finds the check action without the plugin routing it. If resolve returns None for a check or cancel key, Genkit asks again with ActionKind.BACKGROUND_MODEL and the start id.

Naming rule. When an app asks for {plugin.name}/{rest}:

  1. Genkit removes exactly one {plugin.name}/ from the front and passes rest as name. That's the provider's id, verbatim: send it upstream unchanged and don't strip anything from it. Provider ids may contain slashes (publisher paths, tuned endpoints, ARNs, OpenRouter ids).
  2. The returned action is renamed to exactly what the app asked for and stored there, whatever name the plugin gave it, so the same string always looks up the same action.

Return None to decline; the caller then gets NOT_FOUND.

Example
from genkit import Genkit
from genkit.plugin_api import ActionKind
from genkit_openai import OpenAI

# 1. Point the OpenAI plugin at OpenRouter, whose ids carry a vendor
ai = Genkit(plugins=[OpenAI(base_url='https://openrouter.ai/api/v1')])

# 2. One `openai/` is the plugin; the rest is the OpenRouter id
response = await ai.generate(model='openai/openai/gpt-4o', prompt='Suggest a dish.')
# => resolve(ActionKind.MODEL, 'openai/gpt-4o')
#    request sent with model='openai/gpt-4o'

# 3. The action lives under the id the app typed
action = await ai.lookup_model('openai/openai/gpt-4o')
print(action.name)
# => openai/openai/gpt-4o
Source code in packages/genkit/src/genkit/_core/_plugin.py
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
@abc.abstractmethod
async def resolve(self, action_type: ActionKind, name: str) -> Action | BackgroundAction[Any, Any] | None:
    """Resolve a single action by kind and its id inside this plugin.

    Return a ``BackgroundAction`` (e.g. a ``BackgroundModel``) for a
    background job. Genkit registers its start, check and cancel actions
    together, so a later ``/check-operation/{name}/check`` lookup finds the
    check action without the plugin routing it. If ``resolve`` returns
    ``None`` for a check or cancel key, Genkit asks again with
    ``ActionKind.BACKGROUND_MODEL`` and the start id.

    Naming rule. When an app asks for ``{plugin.name}/{rest}``:

    1. Genkit removes exactly one ``{plugin.name}/`` from the front and
       passes ``rest`` as ``name``. That's the provider's id, verbatim:
       send it upstream unchanged and don't strip anything from it.
       Provider ids may contain slashes (publisher paths, tuned
       endpoints, ARNs, OpenRouter ids).
    2. The returned action is renamed to exactly what the app asked for
       and stored there, whatever name the plugin gave it, so the same
       string always looks up the same action.

    Return ``None`` to decline; the caller then gets NOT_FOUND.

    Example:
        ```python
        from genkit import Genkit
        from genkit.plugin_api import ActionKind
        from genkit_openai import OpenAI

        # 1. Point the OpenAI plugin at OpenRouter, whose ids carry a vendor
        ai = Genkit(plugins=[OpenAI(base_url='https://openrouter.ai/api/v1')])

        # 2. One `openai/` is the plugin; the rest is the OpenRouter id
        response = await ai.generate(model='openai/openai/gpt-4o', prompt='Suggest a dish.')
        # => resolve(ActionKind.MODEL, 'openai/gpt-4o')
        #    request sent with model='openai/gpt-4o'

        # 3. The action lives under the id the app typed
        action = await ai.lookup_model('openai/openai/gpt-4o')
        print(action.name)
        # => openai/openai/gpt-4o
        ```
    """
    ...

is_dev_environment()

Check if running in development mode (GENKIT_ENV=dev).

Source code in packages/genkit/src/genkit/_core/_environment.py
34
35
36
def is_dev_environment() -> bool:
    """Check if running in development mode (GENKIT_ENV=dev)."""
    return os.getenv(GENKIT_ENV) == GenkitEnvironment.DEV

loop_local_client(factory)

loop_local_client(
    factory: Callable[[], T],
) -> Callable[[], T]
loop_local_client(
    factory: Callable[[S], T],
) -> _LoopLocal[S, T]

Cache a long-lived client per event loop. Use it as a decorator on a factory.

Use it for a client you reuse across calls that code on different event loops may call. Async clients (httpx, the OpenAI and Anthropic SDKs) are bound to the loop they first run on, so one shared client breaks when Genkit runs on a second loop. Each loop gets its own client, built on first use there and returned on every later call there.

The client is shared, so don't close it; it lives as long as its loop. For a client scoped to one call, skip the cache and use async with httpx.AsyncClient() as client: inside the call.

import httpx
from genkit.plugin_api import loop_local_client


# 1. Decorate a factory
@loop_local_client
def http_client() -> httpx.AsyncClient:
    return httpx.AsyncClient(timeout=60.0)


# 2. Call it wherever you need the client
response = await http_client().get('https://example.com/menu.json')

# 3. Same loop, same client
print(http_client() is http_client())
# => True

Where the client lives depends on whether it carries plugin settings:

  • Module level (the decorator above): the client is a plain transport and the API key, URL, headers, and timeout go on each request. Every plugin instance shares one connection pool per loop.
  • On the plugin instance: the client is built from plugin settings, as with SDK clients that take api_key or base_url. Decorate a method; each plugin instance gets its own client per loop:
from openai import AsyncOpenAI


class Bistro(Plugin):
    def __init__(self, api_key: str) -> None:
        self._api_key = api_key

    @loop_local_client
    def _client(self) -> AsyncOpenAI:
        return AsyncOpenAI(api_key=self._api_key)

    async def _generate(self, request: ModelRequest) -> ModelResponse:
        completion = await self._client().chat.completions.create(...)

Plain callables work too, e.g. loop_local_client(asyncio.Lock).

Source code in packages/genkit/src/genkit/_core/_loop_cache.py
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def loop_local_client(factory: Callable[..., T]) -> Any:  # noqa: ANN401
    """Cache a long-lived client per event loop. Use it as a decorator on a factory.

    Use it for a client you reuse across calls that code on different event
    loops may call. Async clients (httpx, the OpenAI and Anthropic SDKs) are
    bound to the loop they first run on, so one shared client breaks when Genkit
    runs on a second loop. Each loop gets its own client, built on first use
    there and returned on every later call there.

    The client is shared, so don't close it; it lives as long as its loop. For a
    client scoped to one call, skip the cache and use
    ``async with httpx.AsyncClient() as client:`` inside the call.

    ```python
    import httpx
    from genkit.plugin_api import loop_local_client


    # 1. Decorate a factory
    @loop_local_client
    def http_client() -> httpx.AsyncClient:
        return httpx.AsyncClient(timeout=60.0)


    # 2. Call it wherever you need the client
    response = await http_client().get('https://example.com/menu.json')

    # 3. Same loop, same client
    print(http_client() is http_client())
    # => True
    ```

    Where the client lives depends on whether it carries plugin settings:

    - **Module level** (the decorator above): the client is a plain transport
      and the API key, URL, headers, and timeout go on each request. Every
      plugin instance shares one connection pool per loop.
    - **On the plugin instance**: the client is built from plugin settings, as
      with SDK clients that take ``api_key`` or ``base_url``. Decorate a method;
      each plugin instance gets its own client per loop:

    ```python
    from openai import AsyncOpenAI


    class Bistro(Plugin):
        def __init__(self, api_key: str) -> None:
            self._api_key = api_key

        @loop_local_client
        def _client(self) -> AsyncOpenAI:
            return AsyncOpenAI(api_key=self._api_key)

        async def _generate(self, request: ModelRequest) -> ModelResponse:
            completion = await self._client().chat.completions.create(...)
    ```

    Plain callables work too, e.g. ``loop_local_client(asyncio.Lock)``.
    """
    return cast(Any, _LoopLocal(factory))

provider_error(error, *, http_status=None, status=None, headers=None, retry_after_ms=None, message=None, reason=None)

Turn a model provider's failure into a GenkitError that Retry and Fallback can act on.

Raise the result from a model or embedder when the provider call fails:

except httpx.HTTPStatusError as e:
    raise provider_error(e, http_status=e.response.status_code, headers=e.response.headers) from e

Status: status if given, else mapped from http_status (400 is INVALID_ARGUMENT, 429 RESOURCE_EXHAUSTED, 503 UNAVAILABLE, any other 5xx INTERNAL). A 4xx with no matching status (413, 422) or no usable code at all is UNKNOWN, which default Retry and Fallback don't act on.

Retry delay: retry_after_ms if given, else the Retry-After header (seconds or an HTTP date). Retry waits at least that long before the next attempt. A missing or malformed header just means no floor.

The message is message, else str(error), else the error's type name, and error is kept as the cause; str() appends the cause's text unless the message already contains it. A served flow still answers 500 Internal Error: a dead API key on the server isn't the caller's 401. Raise PublicError to show the caller a status.

Parameters:

Name Type Description Default
error BaseException

What the provider SDK raised.

required
http_status int | None

The provider's HTTP status code, if there was one.

None
status genkit._core._error.StatusName | None

A Genkit status to use instead of mapping http_status.

None
headers collections.abc.Mapping[str, str] | None

The provider's response headers.

None
retry_after_ms float | None

How long to wait before retrying, instead of reading headers.

None
message str | None

Message to use instead of str(error).

None
reason genkit._core._error.ErrorReason | None

Set when the plugin can tell why the provider failed, such as ErrorReason.INVALID_CREDENTIALS for a rejected key. App code reads it from GenkitError.reason or Failure.reason.

None

Returns:

Type Description
genkit._core._error.GenkitError

A GenkitError to raise.

Source code in packages/genkit/src/genkit/_core/_error.py
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
def provider_error(
    error: BaseException,
    *,
    http_status: int | None = None,
    status: StatusName | None = None,
    headers: Mapping[str, str] | None = None,
    retry_after_ms: float | None = None,
    message: str | None = None,
    reason: ErrorReason | None = None,
) -> GenkitError:
    """Turn a model provider's failure into a GenkitError that Retry and Fallback can act on.

    Raise the result from a model or embedder when the provider call fails:

        except httpx.HTTPStatusError as e:
            raise provider_error(e, http_status=e.response.status_code, headers=e.response.headers) from e

    Status: ``status`` if given, else mapped from ``http_status`` (400 is
    INVALID_ARGUMENT, 429 RESOURCE_EXHAUSTED, 503 UNAVAILABLE, any other 5xx
    INTERNAL). A 4xx with no matching status (413, 422) or no usable code at
    all is UNKNOWN, which default Retry and Fallback don't act on.

    Retry delay: ``retry_after_ms`` if given, else the ``Retry-After`` header
    (seconds or an HTTP date). Retry waits at least that long before the next
    attempt. A missing or malformed header just means no floor.

    The message is ``message``, else ``str(error)``, else the error's type
    name, and ``error`` is kept as the cause; ``str()`` appends the cause's
    text unless the message already contains it. A served flow still answers
    500 Internal Error: a dead API key on the server isn't the caller's 401.
    Raise PublicError to show the caller a status.

    Args:
        error: What the provider SDK raised.
        http_status: The provider's HTTP status code, if there was one.
        status: A Genkit status to use instead of mapping ``http_status``.
        headers: The provider's response headers.
        retry_after_ms: How long to wait before retrying, instead of reading headers.
        message: Message to use instead of ``str(error)``.
        reason: Set when the plugin can tell why the provider failed, such as
            ``ErrorReason.INVALID_CREDENTIALS`` for a rejected key. App code
            reads it from ``GenkitError.reason`` or ``Failure.reason``.

    Returns:
        A GenkitError to raise.
    """
    if status is None:
        code = http_code(http_status)
        # A 2xx/3xx on an exception isn't a failure status we can trust.
        status = from_http_code(code) if code is not None and code >= 400 else 'UNKNOWN'
    if retry_after_ms is None:
        retry_after_ms = retry_after_ms_from_headers(headers)
    # A bare TimeoutError() or httpx.ReadTimeout often has empty str(); the type
    # name at least says what failed.
    text = message if message is not None else (str(error) or type(error).__name__)
    result = GenkitError(status=status, message=text, cause=error, reason=reason, retry_after_ms=retry_after_ms)
    return mark_provider_error(error=result)

to_json_schema(schema)

Convert a Python type to JSON schema. Pass-through if already a dict.

Source code in packages/genkit/src/genkit/_core/_schema.py
44
45
46
47
48
49
50
51
def to_json_schema(schema: type | dict[str, Any] | str | None) -> dict[str, Any]:
    """Convert a Python type to JSON schema. Pass-through if already a dict."""
    if schema is None:
        return {'type': 'null'}
    if isinstance(schema, dict):
        return schema
    type_adapter = TypeAdapter(schema)
    return type_adapter.json_schema()

genkit.evaluator

Evaluator namespace module for Genkit.

Everything needed to call or write an evaluator lives here.

Example
from genkit import Genkit
from genkit.evaluator import BaseDataPoint, EvaluatorResponse, Score

ai = Genkit()


# 1. Score one datapoint
async def allergen_check(datapoint: BaseDataPoint, _options: object | None = None) -> EvaluatorResponse:
    ok = 'peanut' not in str(datapoint.output).lower()
    return EvaluatorResponse(test_case_id=datapoint.test_case_id or '', evaluation=[Score(score=ok)])


ai.define_evaluator(
    name='allergen_check', display_name='Allergen check', definition='Flags peanuts.', fn=allergen_check
)

# 2. Run it over a dataset
results = await ai.evaluate(
    evaluator='allergen_check',
    dataset=[BaseDataPoint(input='Suggest a dish.', output='Peanut noodles')],
)
print(results[0].evaluation[0].score)
# => False

BaseDataPoint

Bases: genkit._core._base.GenkitModel

Model for basedatapoint data.

Source code in packages/genkit/src/genkit/_core/_typing.py
335
336
337
338
339
340
341
342
343
344
345
346
class BaseDataPoint(GenkitModel):
    """Model for basedatapoint data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    input: Any | None = Field(default=None)
    output: Any | None = Field(default=None)
    context: list[Any] | None = None
    reference: Any | None = Field(default=None)
    test_case_id: str | None = None
    trace_ids: list[str] | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

BatchEvaluator

Bases: genkit._core._action.Action[genkit._core._typing.EvaluatorRequest, genkit._core._typing.EvalResponse, typing_extensions.Never]

Batch evaluator action that runs fn once on the whole EvaluatorRequest, without registering it.

fn returns list[EvaluatorResponse]. The action wraps the list so action.run(...).response is an EvalResponse. Plugin init / resolve / list_actions return this. define_batch_evaluator registers it.

Source code in packages/genkit/src/genkit/_ai/_evaluator.py
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
class BatchEvaluator(Action[EvaluatorRequest, EvalResponse, Never]):
    """Batch evaluator action that runs ``fn`` once on the whole ``EvaluatorRequest``, without registering it.

    ``fn`` returns ``list[EvaluatorResponse]``. The action wraps the list so
    ``action.run(...).response`` is an ``EvalResponse``.
    Plugin ``init`` / ``resolve`` / ``list_actions`` return this.
    ``define_batch_evaluator`` registers it.
    """

    def __init__(
        self,
        name: str,
        fn: BatchEvaluatorFn,
        *,
        display_name: str,
        definition: str,
        is_billed: bool = False,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
    ) -> None:
        if not inspect.iscoroutinefunction(fn):
            raise TypeError(f"Action handlers must be async functions. Got sync function for '{name}'.")

        evaluator_meta = _evaluator_metadata(name, display_name, definition, is_billed, config_schema, metadata)
        evaluator_description = _get_func_description(fn, description)

        # the action hands back the rows as one model so the Dev UI and
        # `genkit eval:run` get a JSON array, the same as a per-row evaluator.
        # fn stays the metadata_fn, so its signature is still checked when built.
        async def batch_fn(req: EvaluatorRequest, ctx: ActionContext) -> EvalResponse:
            warn_evaluators_deprecated()
            return EvalResponse(await self.params.call(fn, req, ctx))

        super().__init__(
            kind=ActionKind.EVALUATOR,
            name=name,
            fn=batch_fn,
            metadata_fn=fn,
            metadata=evaluator_meta,
            description=evaluator_description,
        )

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

Evaluator

Bases: genkit._core._action.Action[genkit._core._typing.EvaluatorRequest, genkit._core._typing.EvalResponse, typing_extensions.Never]

Evaluator action that runs fn on each dataset sample, without registering it.

Plugin init / resolve / list_actions return this. define_evaluator registers it.

Source code in packages/genkit/src/genkit/_ai/_evaluator.py
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
class Evaluator(Action[EvaluatorRequest, EvalResponse, Never]):
    """Evaluator action that runs ``fn`` on each dataset sample, without registering it.

    Plugin ``init`` / ``resolve`` / ``list_actions`` return this.
    ``define_evaluator`` registers it.
    """

    def __init__(
        self,
        name: str,
        fn: EvaluatorFn[Any],
        *,
        display_name: str,
        definition: str,
        is_billed: bool = False,
        config_schema: type[BaseModel] | dict[str, object] | None = None,
        metadata: dict[str, object] | None = None,
        description: str | None = None,
    ) -> None:
        if not inspect.iscoroutinefunction(fn):
            raise TypeError(f"Action handlers must be async functions. Got sync function for '{name}'.")

        evaluator_meta = _evaluator_metadata(name, display_name, definition, is_billed, config_schema, metadata)
        evaluator_description = _get_func_description(fn, description)

        async def eval_stepper_fn(req: EvaluatorRequest) -> EvalResponse:
            warn_evaluators_deprecated()
            eval_responses: list[EvaluatorResponse] = []
            for index in range(len(req.dataset)):
                datapoint = req.dataset[index]
                case_id = datapoint.test_case_id or str(uuid.uuid4())
                datapoint.test_case_id = case_id
                try:

                    async def body(
                        span: SpanContext, point: BaseDataPoint = datapoint, test_case_id: str = case_id
                    ) -> EvaluatorResponse:
                        try:
                            test_case_output = await fn(point, req.options)
                            test_case_output.span_id = span.span_id
                            test_case_output.trace_id = span.trace_id
                            return test_case_output
                        except Exception as e:
                            logger.debug(f'eval_stepper_fn error: {e!s}')
                            logger.debug(traceback.format_exc())
                            evaluation = Score(
                                error=f'Evaluation of test case {test_case_id} failed: \n{e!s}',
                                status=ScoreStatus.FAIL,
                            )
                            eval_responses.append(
                                EvaluatorResponse(
                                    span_id=span.span_id,
                                    trace_id=span.trace_id,
                                    test_case_id=test_case_id,
                                    evaluation=[evaluation],
                                )
                            )
                            raise e

                    eval_responses.append(
                        await run_in_new_span(
                            f'Test Case {datapoint.test_case_id}',
                            body,
                            action_type='evaluator',
                            input=datapoint,
                            attributes={metadata_key('evaluator:evalRunId'): str(req.eval_run_id)},
                        )
                    )
                except Exception:  # noqa: S112 - intentionally continue processing other datapoints
                    continue
            return EvalResponse(eval_responses)

        super().__init__(
            kind=ActionKind.EVALUATOR,
            name=name,
            fn=eval_stepper_fn,
            metadata=evaluator_meta,
            description=evaluator_description,
        )

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

EvaluatorRef

Bases: pydantic.BaseModel

Reference to an evaluator.

Source code in packages/genkit/src/genkit/_ai/_evaluator.py
105
106
107
108
109
110
111
class EvaluatorRef(BaseModel):
    """Reference to an evaluator."""

    model_config: ClassVar[ConfigDict] = ConfigDict(extra='forbid', populate_by_name=True, alias_generator=to_camel)

    name: str
    config: dict[str, object] | None = None

EvaluatorRequest

Bases: genkit._core._base.GenkitModel

Model for evaluatorrequest data.

Source code in packages/genkit/src/genkit/_core/_typing.py
383
384
385
386
387
388
389
390
391
class EvaluatorRequest(GenkitModel):
    """Model for evaluatorrequest data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    dataset: list[BaseDataPoint] = Field(...)
    eval_run_id: str = Field(...)
    options: Any | None = Field(default=None)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

EvaluatorResponse

Bases: genkit._core._base.GenkitModel

Model for evaluatorresponse data.

Source code in packages/genkit/src/genkit/_core/_typing.py
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
class EvaluatorResponse(GenkitModel):
    """Model for evaluatorresponse data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    sample_index: float | None = None
    test_case_id: str = Field(...)
    trace_id: str | None = None
    span_id: str | None = None
    evaluation: list[Score] = Field(...)

    @field_validator('evaluation', mode='before')
    @classmethod
    def _wrap_single_score_object(cls, value: Any) -> Any:  # noqa: ANN401
        # saved runs may store one score object. wrap that dict;
        # a Score built in code must already be a list.
        return [value] if isinstance(value, dict) else value

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Score

Bases: genkit._core._base.GenkitModel

Model for score data.

Source code in packages/genkit/src/genkit/_core/_typing.py
394
395
396
397
398
399
400
401
402
403
404
class Score(GenkitModel):
    """Model for score data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    id: str | None = None
    score: bool | float | str | None = Field(default=None)
    status: ScoreStatus | None = None
    error: str | None = None
    details: ScoreDetails | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ScoreDetails

Bases: genkit._core._base.GenkitModel

Model for scoredetails data.

Source code in packages/genkit/src/genkit/_core/_typing.py
1098
1099
1100
1101
1102
1103
1104
class ScoreDetails(GenkitModel):
    """Model for scoredetails data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='allow', validate_by_name=True, validate_by_alias=True
    )
    reasoning: str | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

ScoreStatus

Bases: genkit._core._compat.StrEnum

ScoreStatus data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
80
81
82
83
84
85
class ScoreStatus(StrEnum):
    """ScoreStatus data type class."""

    UNKNOWN = 'UNKNOWN'
    PASS = 'PASS'
    FAIL = 'FAIL'

genkit.telemetry

On-switch for Genkit traces, and the protocol for a recording backend.

Application code should call :class:genkit.Genkit. genkit start records to the Developer UI. configure_instrumentation is the hook for a recording backend; reset_instrumentation starts over between tests. set_custom_metadata_attributes stamps the active span (tenant_id), and flush_instrumentations drains exports before a serverless shutdown.

DisposableInstrumentation

Bases: typing.Protocol

Optional: a provider that holds a subscription or client.

reset_instrumentation calls dispose so an exporter from the last run cannot keep posting after tests tear down.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
101
102
103
104
105
106
107
108
109
@runtime_checkable
class DisposableInstrumentation(Protocol):
    """Optional: a provider that holds a subscription or client.

    ``reset_instrumentation`` calls ``dispose`` so an exporter from the
    last run cannot keep posting after tests tear down.
    """

    def dispose(self) -> None: ...

FlushableInstrumentation

Bases: typing.Protocol

Optional: a provider that buffers exports.

flush_instrumentations calls flush so buffered telemetry is on the wire before a serverless process freezes (or in tests).

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
112
113
114
115
116
117
118
119
120
@runtime_checkable
class FlushableInstrumentation(Protocol):
    """Optional: a provider that buffers exports.

    ``flush_instrumentations`` calls ``flush`` so buffered telemetry is on the
    wire before a serverless process freezes (or in tests).
    """

    def flush(self) -> None: ...

Instrumentation

Bases: typing.Protocol

Pluggable provider. run_in_new_span wraps next like middleware.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
90
91
92
93
94
95
96
97
98
@runtime_checkable
class Instrumentation(Protocol):
    """Pluggable provider. ``run_in_new_span`` wraps ``next`` like middleware."""

    async def run_in_new_span(
        self,
        metadata: SpanMetadata,
        next: SpanNext[T],
    ) -> T: ...

SpanContext

Bases: typing.Protocol

Handle to a live span. No backend types leak through.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
class SpanContext(Protocol):
    """Handle to a live span. No backend types leak through."""

    @property
    def trace_id(self) -> str:
        """Trace id, or empty when not instrumented."""
        ...

    @property
    def span_id(self) -> str:
        """Span id, or empty when not instrumented."""
        ...

    def set_metadata(self, metadata: Mapping[str, object]) -> None:
        """Attach custom metadata. Safe to call multiple times."""
        ...

    def set_state(self, state: SpanState, *, message: str | None = None) -> None:
        """Override genkit:state. ``error`` marks a failed generate that returned."""
        ...

span_id property

Span id, or empty when not instrumented.

trace_id property

Trace id, or empty when not instrumented.

set_metadata(metadata)

Attach custom metadata. Safe to call multiple times.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
81
82
83
def set_metadata(self, metadata: Mapping[str, object]) -> None:
    """Attach custom metadata. Safe to call multiple times."""
    ...

set_state(state, *, message=None)

Override genkit:state. error marks a failed generate that returned.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
85
86
87
def set_state(self, state: SpanState, *, message: str | None = None) -> None:
    """Override genkit:state. ``error`` marks a failed generate that returned."""
    ...

SpanMetadata dataclass

Description of a span about to be created.

action_type is the action kind ('model', 'flow', 'tool'...) for action spans, or the span's own type ('util', 'flowStep'...) for plain spans. Providers decide how to encode values.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
53
54
55
56
57
58
59
60
61
62
63
64
65
@dataclass(frozen=True)
class SpanMetadata:
    """Description of a span about to be created.

    ``action_type`` is the action kind (``'model'``, ``'flow'``, ``'tool'``...)
    for action spans, or the span's own type (``'util'``, ``'flowStep'``...)
    for plain spans. Providers decide how to encode values.
    """

    name: str
    action_type: str | None = None
    input: object | None = None
    attributes: Mapping[str, SpanAttributeValue] = field(default_factory=dict)

SpanNext

Bases: typing.Protocol[genkit._core._telemetry._instrumentation.T_co]

next() or next(span). A logger that does not mint ids calls next().

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
47
48
49
50
class SpanNext(Protocol[T_co]):
    """``next()`` or ``next(span)``. A logger that does not mint ids calls ``next()``."""

    def __call__(self, span: SpanContext | None = None) -> Awaitable[T_co]: ...

configure_instrumentation(instrumentation)

Turn on a telemetry backend. Call before Genkit() to stack backends.

Each provider wraps the next. genkit start installs the Developer UI HTTP poster when a collector URL is set. enable_google_cloud_telemetry() hangs Cloud's exporter; it does not mint spans.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
189
190
191
192
193
194
195
196
197
198
199
200
201
202
def configure_instrumentation(instrumentation: Instrumentation) -> None:
    """Turn on a telemetry backend. Call before ``Genkit()`` to stack backends.

    Each provider wraps the next. ``genkit start`` installs the Developer UI
    HTTP poster when a collector URL is set. ``enable_google_cloud_telemetry()``
    hangs Cloud's exporter; it does not mint spans.
    """
    # The class itself has run_in_new_span, so a forgotten () would pass a
    # Protocol check and then fail on the first span.
    if isinstance(instrumentation, type) or not isinstance(instrumentation, Instrumentation):
        raise TypeError(
            'configure_instrumentation expected an Instrumentation instance, got ' + describe_value(instrumentation)
        )
    instrumentations.append(instrumentation)

flush_instrumentations()

Wait for in-flight exports on every configured backend.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
215
216
217
218
219
def flush_instrumentations() -> None:
    """Wait for in-flight exports on every configured backend."""
    for inst in instrumentations:
        if isinstance(inst, FlushableInstrumentation):
            inst.flush()

is_instrumented_by(kind)

True when a configured provider is an instance of kind.

Testers pass the class of the provider they configured.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
241
242
243
244
245
246
247
248
def is_instrumented_by(kind: type) -> bool:
    """True when a configured provider is an instance of ``kind``.

    Testers pass the class of the provider they configured.
    """
    if not isinstance(kind, type):
        raise TypeError('is_instrumented_by expected a type, got ' + describe_value(kind))
    return any(isinstance(i, kind) for i in instrumentations)

reset_instrumentation()

Start telemetry over. Tests only.

Disposes and removes every configured provider, stops Dev UI log export, and forgets the open trace so the next span is a new root.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
def reset_instrumentation() -> None:
    """Start telemetry over. Tests only.

    Disposes and removes every configured provider, stops Dev UI log export,
    and forgets the open trace so the next span is a new root.
    """
    dispose_instrumentations()
    instrumentations.clear()
    reset_log_export()
    parent_path_context.set('')
    current_span.set(None)
    span_is_action.set(False)
    # The HTTP parent is a ContextVar on the poster. Reset must clear it
    # even when no poster is registered, so the next span is a new root.
    from ._http import reset_parent_span

    reset_parent_span()

run_in_new_span(name, fn, *, action_type=None, input=None, attributes=None, is_action=False) async

Run fn inside a new span via the configured provider chain.

No providers → fn runs with a no-op span (empty ids). Index 0 is outermost. The provider list is snapshotted so configure/reset during an await cannot break the chain.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
async def run_in_new_span(
    name: str,
    fn: Callable[[SpanContext], Awaitable[T]],
    *,
    action_type: str | None = None,
    input: object | None = None,
    attributes: Mapping[str, SpanAttributeValue] | None = None,
    is_action: bool = False,
) -> T:
    """Run ``fn`` inside a new span via the configured provider chain.

    No providers → ``fn`` runs with a no-op span (empty ids). Index 0 is
    outermost. The provider list is snapshotted so configure/reset during an
    await cannot break the chain.
    """
    if not inspect.iscoroutinefunction(fn):
        name = getattr(fn, '__qualname__', type(fn).__name__)
        raise TypeError(f'run_in_new_span expected an async callback, got {name}')
    attrs: dict[str, SpanAttributeValue] = dict(attributes) if attributes else {}
    meta = SpanMetadata(
        name=name,
        action_type=action_type,
        input=input,
        attributes=attrs,
    )
    providers = list(instrumentations)
    if not providers:
        return await _run_with_span(NoopSpanContext(), fn)

    spans: list[SpanContext] = []

    async def build(index: int) -> T:
        if index == len(providers):
            return await _run_with_span(CompositeSpanContext(spans), fn)

        async def nxt(span: SpanContext | None = None) -> T:
            if span is not None:
                spans.append(span)
            return await build(index + 1)

        return await providers[index].run_in_new_span(meta, nxt)

    token = span_is_action.set(is_action)
    try:
        return await build(0)
    finally:
        span_is_action.reset(token)

set_custom_metadata_attributes(attributes)

Write metadata on the active span. No-op outside a span.

Source code in packages/genkit/src/genkit/_core/_telemetry/_instrumentation.py
251
252
253
254
255
def set_custom_metadata_attributes(attributes: Mapping[str, object]) -> None:
    """Write metadata on the active span. No-op outside a span."""
    span = current_span.get()
    if span is not None:
        span.set_metadata(attributes)

genkit.middleware

Middleware for Genkit model calls.

Define a subclass of Middleware and register it on your app with @ai.middleware:

from genkit import Genkit
from genkit.middleware import Middleware, MiddlewareContext

ai = Genkit()

@ai.middleware(name='logging')
class LoggingMiddleware(Middleware):
    async def wrap_generate(self, params, ctx: MiddlewareContext, next_fn):
        print('before')
        result = await next_fn(params, ctx)
        print('after')
        return result

response = await ai.generate(
    model='your-model-here',
    prompt='Hello',
    use=[LoggingMiddleware()],
)

Once registered, the middleware is visible in the Dev UI. You can play with the Model Runner and mix-and-match your choice of middleware to see its impact on generating the next response.

Order of middleware in use=[...] determines the order in which they are called. The first middleware in the list is called first, and the last middleware in the list is called last.

For example, given this call:

use = [A(), B()]

The execution sequence is:

A_before()
    B_before()
        model_call()
    B_after()
A_after()

GenerateHookParams

Bases: pydantic.BaseModel

Params passed to the wrap_generate hook.

Covers one full iteration of the tool loop: a model call plus optional tool resolution. message_index tracks streaming position for this turn.

Source code in packages/genkit/src/genkit/_core/_middleware.py
204
205
206
207
208
209
210
211
212
213
214
215
class GenerateHookParams(BaseModel):
    """Params passed to the ``wrap_generate`` hook.

    Covers one full iteration of the tool loop: a model call plus optional tool
    resolution. ``message_index`` tracks streaming position for this turn.
    """

    model_config: ClassVar[ConfigDict] = ConfigDict(arbitrary_types_allowed=True)

    options: GenerateActionOptions
    iteration: int
    message_index: int = 0

Middleware

Bases: typing.Generic[genkit._core._middleware.TConfig]

Base class for generate middleware.

A middleware is defined by its custom configuration (backed by Pydantic), and a set of hooks to inject logic into the generate pipeline.

The base middleware has no custom configuration and noop hooks. The hooks that are not overridden are still called by the engine when the middleware is invoked.

To author a middleware, 1. Declare a config model, e.g. RetryConfig:

class RetryConfig(BaseModel):
    max_retries: int = 3

Any pydantic BaseModel works. Its keys (field names, or aliases if it declares them) are the config keys in .prompt files, the Dev UI form and traces. A key the class doesn't declare raises instead of being dropped (a ValidationError, as for a GenkitConfig), unless the class sets extra='allow' or 'ignore'.

  1. Extend Middleware with your config model and give it a registry name: ai = Genkit()

    @ai.middleware class Retry(Middleware[RetryConfig]): name = 'retry' description = 'Retries model calls with exponential backoff and jitter.'

    async def wrap_model(self, params, ctx, next_fn):
        for attempt in range(self.config.max_retries + 1):
            ...
    

@ai.middleware (or ai.define_middleware(Retry)) registers the class so the Dev UI lists it and a .prompt file can name it. @ai.middleware(name=..., description=...) overrides the class attributes. name and description are not inherited: a subclass of Retry sets its own name before it can be registered.

  1. Use the Retry middleware in your generate call: ai.generate( ..., use=[Retry(max_retries=5)] )

    Or alternatively, for full keyword auto-complete in your preferred IDE:

    ai.generate( ..., use=[Retry(config=RetryConfig(max_retries=5))] )

self.config is set once at construction. The attribute is read-only; treat the config object as read-only too (Pydantic models are not frozen).

Choose where to store state based on its lifetime:

* **Shared across all requests** (e.g., an audit client, rate limiter,
  or compiled regex): set on ``self`` in ``__init__``.
* **Scoped to one ``generate()`` call** (e.g., retry counters or loop
  budgets): use local variables inside ``wrap_generate``.
* **Scoped to one turn or tool call** (e.g., per-call timing or header
  injection): use local variables inside ``wrap_model`` or ``wrap_tool``.
* **Shared between hooks in one ``generate()`` call** (e.g., recording
  a tool call in ``wrap_tool`` and reading it in the next ``wrap_model``
  turn): pass it through ``ctx.context``, or store a fresh container on
  ``self`` in ``__copy__``.

Per-request containers via __copy__: Genkit calls copy.copy(mw) once at the start of each generate() call. Because a shallow copy shares any list or dict created in __init__ across concurrent requests, override __copy__ when you need a fresh per-request container without re-running __init__::

    def __copy__(self) -> Self:
        clone = type(self).__new__(type(self))
        clone.__dict__.update(self.__dict__)
        clone._seen_tools = []  # isolated per generate() call
        return clone
Source code in packages/genkit/src/genkit/_core/_middleware.py
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
class Middleware(Generic[TConfig]):
    """Base class for generate middleware.

    A middleware is defined by its custom configuration (backed by Pydantic),
    and a set of hooks to inject logic into the generate pipeline.

    The base middleware has no custom configuration and noop hooks. The hooks
    that are not overridden are still called by the engine when the middleware
    is invoked.

    To author a middleware,
    1. Declare a config model, e.g. RetryConfig:

        class RetryConfig(BaseModel):
            max_retries: int = 3

       Any pydantic BaseModel works. Its keys (field names, or aliases if it
       declares them) are the config keys in .prompt files, the Dev UI form
       and traces. A key the class doesn't declare raises instead of being
       dropped (a ValidationError, as for a GenkitConfig), unless the class sets
       ``extra='allow'`` or ``'ignore'``.

    2. Extend Middleware with your config model and give it a registry name:
        ai = Genkit()

        @ai.middleware
        class Retry(Middleware[RetryConfig]):
            name = 'retry'
            description = 'Retries model calls with exponential backoff and jitter.'

            async def wrap_model(self, params, ctx, next_fn):
                for attempt in range(self.config.max_retries + 1):
                    ...

    ``@ai.middleware`` (or ``ai.define_middleware(Retry)``) registers the class
    so the Dev UI lists it and a ``.prompt`` file can name it.
    ``@ai.middleware(name=..., description=...)`` overrides the class attributes.
    ``name`` and ``description`` are not inherited: a subclass of ``Retry``
    sets its own ``name`` before it can be registered.

    3. Use the Retry middleware in your `generate` call:
        ai.generate(
            ...,
            use=[Retry(max_retries=5)]
        )

        # Or alternatively, for full keyword auto-complete in your preferred IDE:
        ai.generate(
            ...,
            use=[Retry(config=RetryConfig(max_retries=5))]
        )

    ``self.config`` is set once at construction. The attribute is read-only;
    treat the config object as read-only too (Pydantic models are not frozen).

    Choose where to store state based on its lifetime:

        * **Shared across all requests** (e.g., an audit client, rate limiter,
          or compiled regex): set on ``self`` in ``__init__``.
        * **Scoped to one ``generate()`` call** (e.g., retry counters or loop
          budgets): use local variables inside ``wrap_generate``.
        * **Scoped to one turn or tool call** (e.g., per-call timing or header
          injection): use local variables inside ``wrap_model`` or ``wrap_tool``.
        * **Shared between hooks in one ``generate()`` call** (e.g., recording
          a tool call in ``wrap_tool`` and reading it in the next ``wrap_model``
          turn): pass it through ``ctx.context``, or store a fresh container on
          ``self`` in ``__copy__``.

    Per-request containers via ``__copy__``:
        Genkit calls ``copy.copy(mw)`` once at the start of each ``generate()``
        call. Because a shallow copy shares any ``list`` or ``dict`` created in
        ``__init__`` across concurrent requests, override ``__copy__`` when you
        need a fresh per-request container without re-running ``__init__``::

            def __copy__(self) -> Self:
                clone = type(self).__new__(type(self))
                clone.__dict__.update(self.__dict__)
                clone._seen_tools = []  # isolated per generate() call
                return clone
    """

    name: ClassVar[str] = ''
    description: ClassVar[str | None] = None
    Config: ClassVar[type[BaseModel]] = _EmptyMiddlewareConfig
    _config: TConfig

    def __init_subclass__(cls, **kwargs: Any) -> None:  # noqa: ANN401
        super().__init_subclass__(**kwargs)
        # The registry name and Dev UI description belong to the class that
        # declares them; a subclass inheriting them would collide with its parent.
        if 'name' not in cls.__dict__:
            cls.name = ''
        if 'description' not in cls.__dict__:
            cls.description = None
        # Python keeps RetryConfig in Middleware[RetryConfig] for type checkers only.
        # We copy it onto cls.Config so Retry(max_retries=5) and the Dev UI form work.
        if 'Config' in cls.__dict__:
            raise TypeError(f'{cls.__name__} must not define Config; declare config as Middleware[YourConfig] instead.')
        config_cls: type[BaseModel] | None = None
        # Pull config type out of the brackets of the class declaration.
        # i.e. CustomMiddlewareConfig from CustomMiddleware(Middleware[CustomMiddlewareConfig]).
        for base in getattr(cls, '__orig_bases__', ()):
            if get_origin(base) is Middleware:
                args = get_args(base)
                if len(args) == 1:
                    arg = args[0]
                    if isinstance(arg, type) and issubclass(arg, BaseModel):
                        config_cls = arg
                break
        # Look for a config in parent classes, e.g. if a parent is Middleware[SomeConfig]
        if config_cls is None:
            for base in cls.__mro__[1:]:
                if base is Middleware:
                    break
                if issubclass(base, Middleware) and base.Config is not _EmptyMiddlewareConfig:
                    config_cls = base.Config
                    break
        # Handle the case where no config type is specified, e.g. class Logging(Middleware):
        # This means there is no user-facing configuration for the middleware.
        cls.Config = config_cls or _EmptyMiddlewareConfig
        _reject_legacy_hooks(cls)

    def __init__(self, *, config: TConfig | None = None, **kwargs: Any) -> None:  # noqa: ANN401
        if config is not None:
            if kwargs:
                raise TypeError('pass either config= or keyword config fields, not both')
            if not isinstance(config, self.Config):
                raise TypeError(f'expected config type {self.Config.__name__}, got {type(config).__name__}')
            self._config = config
        else:
            unknown, _ = _unknown_config_keys(self.Config, kwargs)
            if unknown:
                # The same error a GenkitConfig raises, so the base class doesn't change what callers catch.
                raise ValidationError.from_exception_data(
                    self.Config.__name__,
                    [{'type': 'extra_forbidden', 'loc': (key,), 'input': kwargs[key]} for key in unknown],
                )
            self._config = cast(Any, self.Config(**kwargs))

    @property
    def config(self) -> TConfig:
        """The validated config this instance was constructed with (read-only)."""
        return self._config

    @classmethod
    def _middleware_metadata(
        cls,
        name: str | None = None,
        *,
        description: str | None = None,
    ) -> _MiddlewareMetadata:
        """Build the internal Dev UI catalog descriptor for this middleware class."""
        return _MiddlewareMetadata(cls=cls, name=name, description=description)

    def tools(self, ctx: MiddlewareContext) -> list[Tool]:
        """Return additional tools to expose to the model for this generate call."""
        return []

    async def wrap_generate(
        self,
        params: GenerateHookParams,
        ctx: MiddlewareContext,
        next_fn: Callable[[GenerateHookParams, MiddlewareContext], Awaitable[ModelResponse]],
    ) -> ModelResponse:
        """Wrap each iteration of the tool loop (model call + optional tool resolution)."""
        return await next_fn(params, ctx)

    async def wrap_model(
        self,
        params: ModelHookParams,
        ctx: MiddlewareContext,
        next_fn: Callable[[ModelHookParams, MiddlewareContext], Awaitable[ModelResponse]],
    ) -> ModelResponse:
        """Wrap each model API call."""
        return await next_fn(params, ctx)

    async def wrap_tool(
        self,
        params: ToolHookParams,
        ctx: MiddlewareContext,
        next_fn: Callable[[ToolHookParams, MiddlewareContext], Awaitable[MultipartToolResponse]],
    ) -> MultipartToolResponse:
        """Wrap each tool execution.

        Return a `MultipartToolResponse` to forward (or substitute) the
        tool's result.  Raise `Interrupt(metadata)` to halt this tool call
        and surface an interrupt to the caller.
        """
        return await next_fn(params, ctx)

config property

The validated config this instance was constructed with (read-only).

tools(ctx)

Return additional tools to expose to the model for this generate call.

Source code in packages/genkit/src/genkit/_core/_middleware.py
552
553
554
def tools(self, ctx: MiddlewareContext) -> list[Tool]:
    """Return additional tools to expose to the model for this generate call."""
    return []

wrap_generate(params, ctx, next_fn) async

Wrap each iteration of the tool loop (model call + optional tool resolution).

Source code in packages/genkit/src/genkit/_core/_middleware.py
556
557
558
559
560
561
562
563
async def wrap_generate(
    self,
    params: GenerateHookParams,
    ctx: MiddlewareContext,
    next_fn: Callable[[GenerateHookParams, MiddlewareContext], Awaitable[ModelResponse]],
) -> ModelResponse:
    """Wrap each iteration of the tool loop (model call + optional tool resolution)."""
    return await next_fn(params, ctx)

wrap_model(params, ctx, next_fn) async

Wrap each model API call.

Source code in packages/genkit/src/genkit/_core/_middleware.py
565
566
567
568
569
570
571
572
async def wrap_model(
    self,
    params: ModelHookParams,
    ctx: MiddlewareContext,
    next_fn: Callable[[ModelHookParams, MiddlewareContext], Awaitable[ModelResponse]],
) -> ModelResponse:
    """Wrap each model API call."""
    return await next_fn(params, ctx)

wrap_tool(params, ctx, next_fn) async

Wrap each tool execution.

Return a MultipartToolResponse to forward (or substitute) the tool's result. Raise Interrupt(metadata) to halt this tool call and surface an interrupt to the caller.

Source code in packages/genkit/src/genkit/_core/_middleware.py
574
575
576
577
578
579
580
581
582
583
584
585
586
async def wrap_tool(
    self,
    params: ToolHookParams,
    ctx: MiddlewareContext,
    next_fn: Callable[[ToolHookParams, MiddlewareContext], Awaitable[MultipartToolResponse]],
) -> MultipartToolResponse:
    """Wrap each tool execution.

    Return a `MultipartToolResponse` to forward (or substitute) the
    tool's result.  Raise `Interrupt(metadata)` to halt this tool call
    and surface an interrupt to the caller.
    """
    return await next_fn(params, ctx)

MiddlewareContext

Per-generate() runtime services shared by every middleware in use=[...].

ai is the app's Genkit instance, so await ctx.ai.lookup_model(name), await ctx.ai.lookup_tool(name) and ctx.ai.lookup_value(kind=..., name=...) find what the app defined. Inside an agent, read the session with genkit.exp.current_session(). Also carries a copy of the call's context= (auth, secrets; the same dict flows and tools read as ctx.context) and streaming hooks.

A callback stored on on_chunk that raises fails the turn; see replace_on_chunk.

Source code in packages/genkit/src/genkit/_core/_middleware.py
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
class MiddlewareContext:
    """Per-``generate()`` runtime services shared by every middleware in ``use=[...]``.

    ``ai`` is the app's ``Genkit`` instance, so ``await ctx.ai.lookup_model(name)``,
    ``await ctx.ai.lookup_tool(name)`` and ``ctx.ai.lookup_value(kind=..., name=...)``
    find what the app defined. Inside an agent, read the session with
    ``genkit.exp.current_session()``. Also carries a copy of the call's
    ``context=`` (auth, secrets; the same dict flows and tools read as
    ``ctx.context``) and streaming hooks.

    A callback stored on ``on_chunk`` that raises fails the turn; see
    ``replace_on_chunk``.
    """

    ai: GenkitLike
    context: dict[str, object]
    _on_chunk: Callable[[ModelResponseChunk], None] | None
    telemetry_labels: dict[str, str] | None

    def __init__(
        self,
        ai: GenkitLike,
        *,
        context: dict[str, object] | None = None,
        on_chunk: Callable[[ModelResponseChunk], None] | None = None,
        telemetry_labels: dict[str, str] | None = None,
    ) -> None:
        self.ai = ai
        self.context = context if context is not None else {}
        self._on_chunk = _guard_on_chunk(on_chunk)
        self.telemetry_labels = telemetry_labels

    @property
    def on_chunk(self) -> Callable[[ModelResponseChunk], None] | None:
        """Streaming callback for this generate call, guarded against callback raises."""
        return self._on_chunk

    @on_chunk.setter
    def on_chunk(self, value: Callable[[ModelResponseChunk], None] | None) -> None:
        self._on_chunk = _guard_on_chunk(value)

    @property
    def is_streaming(self) -> bool:
        """True when the caller registered a streaming callback for this generate."""
        return self._on_chunk is not None

    def send_chunk(self, chunk: ModelResponseChunk) -> None:
        """Stream a chunk to the client when ``on_chunk`` is set."""
        if self._on_chunk is not None:
            self._on_chunk(chunk)

    def replace_on_chunk(
        self,
        on_chunk: Callable[[ModelResponseChunk], None] | None,
    ) -> Callable[[ModelResponseChunk], None] | None:
        """Swap the streaming callback; returns the previous callback.

        Pass the returned callback back in to restore it. Assigning
        ``ctx.on_chunk`` directly behaves the same.

        If the callback you install raises, generate treats it like a raising
        caller callback, not a model failure:

        * the turn ends with ``finish_reason == FAILED`` and
          ``error.reason == ErrorReason.STREAM_CALLBACK_FAILED``;
        * the model is not called again: Retry and Fallback don't see it;
        * the caller's ``async for`` over ``stream.stream`` ends without
          raising, after the chunks sent before the failure.

        Example:
            ```python
            # 1. A middleware that redacts card numbers in streamed text
            class Redact(Middleware):
                async def wrap_model(self, params, ctx, next_fn):
                    previous = ctx.on_chunk

                    def redact(chunk):
                        previous(scrub_card_numbers(chunk))  # raises on a bug

                    ctx.replace_on_chunk(redact)
                    try:
                        return await next_fn(params, ctx)
                    finally:
                        ctx.replace_on_chunk(previous)


            # 2. Stream through it; Retry outside doesn't re-call the model
            stream = ai.generate_stream(
                prompt='Read back my order.',
                use=[Retry(max_retries=2), Redact()],
            )
            async for chunk in stream.stream:
                print(chunk.text)
            # => Your order:

            # 3. The turn failed on the callback, not the provider
            response = await stream.response
            print(response.finish_reason, response.error.reason)
            # => failed STREAM_CALLBACK_FAILED
            ```
        """
        previous = self._on_chunk
        self._on_chunk = _guard_on_chunk(on_chunk)
        return previous

is_streaming property

True when the caller registered a streaming callback for this generate.

on_chunk property writable

Streaming callback for this generate call, guarded against callback raises.

replace_on_chunk(on_chunk)

Swap the streaming callback; returns the previous callback.

Pass the returned callback back in to restore it. Assigning ctx.on_chunk directly behaves the same.

If the callback you install raises, generate treats it like a raising caller callback, not a model failure:

  • the turn ends with finish_reason == FAILED and error.reason == ErrorReason.STREAM_CALLBACK_FAILED;
  • the model is not called again: Retry and Fallback don't see it;
  • the caller's async for over stream.stream ends without raising, after the chunks sent before the failure.
Example
# 1. A middleware that redacts card numbers in streamed text
class Redact(Middleware):
    async def wrap_model(self, params, ctx, next_fn):
        previous = ctx.on_chunk

        def redact(chunk):
            previous(scrub_card_numbers(chunk))  # raises on a bug

        ctx.replace_on_chunk(redact)
        try:
            return await next_fn(params, ctx)
        finally:
            ctx.replace_on_chunk(previous)


# 2. Stream through it; Retry outside doesn't re-call the model
stream = ai.generate_stream(
    prompt='Read back my order.',
    use=[Retry(max_retries=2), Redact()],
)
async for chunk in stream.stream:
    print(chunk.text)
# => Your order:

# 3. The turn failed on the callback, not the provider
response = await stream.response
print(response.finish_reason, response.error.reason)
# => failed STREAM_CALLBACK_FAILED
Source code in packages/genkit/src/genkit/_core/_middleware.py
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
def replace_on_chunk(
    self,
    on_chunk: Callable[[ModelResponseChunk], None] | None,
) -> Callable[[ModelResponseChunk], None] | None:
    """Swap the streaming callback; returns the previous callback.

    Pass the returned callback back in to restore it. Assigning
    ``ctx.on_chunk`` directly behaves the same.

    If the callback you install raises, generate treats it like a raising
    caller callback, not a model failure:

    * the turn ends with ``finish_reason == FAILED`` and
      ``error.reason == ErrorReason.STREAM_CALLBACK_FAILED``;
    * the model is not called again: Retry and Fallback don't see it;
    * the caller's ``async for`` over ``stream.stream`` ends without
      raising, after the chunks sent before the failure.

    Example:
        ```python
        # 1. A middleware that redacts card numbers in streamed text
        class Redact(Middleware):
            async def wrap_model(self, params, ctx, next_fn):
                previous = ctx.on_chunk

                def redact(chunk):
                    previous(scrub_card_numbers(chunk))  # raises on a bug

                ctx.replace_on_chunk(redact)
                try:
                    return await next_fn(params, ctx)
                finally:
                    ctx.replace_on_chunk(previous)


        # 2. Stream through it; Retry outside doesn't re-call the model
        stream = ai.generate_stream(
            prompt='Read back my order.',
            use=[Retry(max_retries=2), Redact()],
        )
        async for chunk in stream.stream:
            print(chunk.text)
        # => Your order:

        # 3. The turn failed on the callback, not the provider
        response = await stream.response
        print(response.finish_reason, response.error.reason)
        # => failed STREAM_CALLBACK_FAILED
        ```
    """
    previous = self._on_chunk
    self._on_chunk = _guard_on_chunk(on_chunk)
    return previous

send_chunk(chunk)

Stream a chunk to the client when on_chunk is set.

Source code in packages/genkit/src/genkit/_core/_middleware.py
338
339
340
341
def send_chunk(self, chunk: ModelResponseChunk) -> None:
    """Stream a chunk to the client when ``on_chunk`` is set."""
    if self._on_chunk is not None:
        self._on_chunk(chunk)

ModelHookParams

Bases: pydantic.BaseModel

Params passed to the wrap_model hook (each raw model API call).

Source code in packages/genkit/src/genkit/_core/_middleware.py
218
219
220
221
222
223
class ModelHookParams(BaseModel):
    """Params passed to the ``wrap_model`` hook (each raw model API call)."""

    model_config: ClassVar[ConfigDict] = ConfigDict(arbitrary_types_allowed=True)

    request: ModelRequest

ToolHookParams

Bases: pydantic.BaseModel

Params passed to the wrap_tool hook (each individual tool execution).

Source code in packages/genkit/src/genkit/_core/_middleware.py
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
class ToolHookParams(BaseModel):
    """Params passed to the ``wrap_tool`` hook (each individual tool execution)."""

    model_config: ClassVar[ConfigDict] = ConfigDict(arbitrary_types_allowed=True)

    tool_request_part: Part
    tool: Action

    @field_validator('tool_request_part', mode='before')
    @classmethod
    def _wrap_tool_request_part(cls, v: object) -> object:
        if v is None:
            return v
        part = as_part(v)
        if part.tool_request is None:
            raise ValueError('wrap_tool needs a tool request part')
        return part

genkit.web

For serving flows over HTTP or writing a web framework adapter.

read_body turns the parsed JSON body into the flow input: callers send {"data": ...}, or {} for no input. wants_stream says whether to answer with server-sent events, and result_json encodes a one-shot return value as compact {"result": ...} JSON (camelCase aliases, None model fields omitted, nested models and datetimes serialized). When a flow fails, send error_json (or the error_body dict) with error_status as the HTTP status, or yield error_sse if a stream fails before to_sse starts. A PublicError's text reaches the caller, and bad input names the failing fields; anything else is a generic Internal Error so server details stay in your logs. result_json and to_sse apply the same rule to a failed agent turn's error (an AgentOutput or SessionSnapshot), which goes out in a 200: it keeps its status, and a non-public message becomes generic. Under GENKIT_ENV=dev both keep the error's own text, like Go, so a local curl against a served flow or agent shows the real cause. A ContextProvider reads the RequestData for one request and returns what goes into the flow's context.

to_sse frames a streaming handle (flow.stream(), ai.generate_stream(), prompt.stream(), chat.send_stream()) as the SSE lines every adapter sends: a message frame per chunk, then result, or an error frame instead. It's also how a hand-written route, say a FastAPI one with typed params and Depends(...), streams without writing frames itself. to_sse sends the handle's result as returned, so ai.generate_stream(), prompt.stream(), and flows returning a ModelResponse put request (system prompt, tools, docs, history) on the wire; stream a flow returning response.text or response.output from a served route.

Example
from starlette.requests import Request
from starlette.responses import Response, StreamingResponse

from genkit.web import (
    RequestData,
    error_json,
    error_status,
    read_body,
    result_json,
    to_sse,
    wants_stream,
)


# 1. Read auth off the request; the result becomes ctx.context in the flow
async def auth(request_data: RequestData) -> dict[str, object]:
    return {'token': request_data.headers.get('authorization')}


# 2. One route: parse, build context, then stream or run once
async def serve(request: Request) -> Response:
    try:
        body = await request.json()
        flow_input = read_body(body)
        request_data = RequestData(
            request=request,
            method=request.method,
            headers=request.headers.items(),
            input=body.get('data'),
        )
        ctx = await auth(request_data)
        if wants_stream(accept=request.headers.get('accept'), stream=request.query_params.get('stream')):
            stream = order_flow.stream(input=flow_input, context=ctx)
            return StreamingResponse(to_sse(stream), media_type='text/event-stream')
        response = await order_flow.run(input=flow_input, context=ctx)
        return Response(result_json(response.response), media_type='application/json')
    except Exception as e:
        return Response(error_json(e), status_code=error_status(e), media_type='application/json')


# POST /order {"data": {"dish": "pad thai"}}
# => {"result":{"text":"1x pad thai"}}
# POST /order?stream=true {"data": {"dish": "pad thai"}}
# => data: {"message":"Plating pad thai"}
#    data: {"result":{"text":"1x pad thai"}}
# POST /order {"input": "pad thai"}
# => 400 {"message":"Flow request must be wrapped in {\"data\": ...}","status":"INVALID_ARGUMENT"}

ContextProvider = Callable[[RequestData], dict[str, Any] | Awaitable[dict[str, Any]]] module-attribute

Middleware can read request data and add information to the context that will be passed to the Action. If middleware throws an error, that error will fail the request and the Action will not be called.

Expected cases should raise a PublicError, which allows the request handler to know what data is safe to return to end users. Middleware can provide validation in addition to parsing. For example, an auth middleware can have policies for validating auth in addition to passing auth context to the Action.

RequestData dataclass

What a context_provider sees for one HTTP request.

method, headers and input (the parsed {"data": ...}) are the same on every adapter, so a provider that reads only those works in Flask, Django and FastAPI. headers keys are lowercase so Authorization and authorization look the same on every served flow. Repeated names become one comma-joined string, so headers.get('authorization') sees every value that arrived. Pass headers as a mapping or as the raw (name, value) pairs off the wire.

request is the framework's own request object (Django HttpRequest, Flask Request, Starlette Request) for what the shared fields don't carry: cookies, sessions, the logged-in user. A provider that reads it works on that framework only.

Example
from genkit import FlowContext, PublicError
from genkit.web import RequestData
from genkit_django import genkit_django_handler


# 1. Django session auth; auser() because the view is async (Django 5.0+,
#    on 4.2 use sync_to_async(lambda: request.request.user)())
async def django_user(request: RequestData) -> dict[str, object]:
    user = await request.request.auser()
    if not user.is_authenticated:
        raise PublicError('UNAUTHENTICATED', 'Sign in first')
    return {'user_id': user.pk}


# 2. The flow reads it from ctx.context
@genkit_django_handler(ai, context_provider=django_user)
@ai.flow
async def reorder(order_id: str, ctx: FlowContext) -> str:
    return f'reordered {order_id} for {ctx.context["user_id"]}'
    # => reordered ORD-9921 for 42
Source code in packages/genkit/src/genkit/_core/_context.py
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
@dataclass(init=False)
class RequestData:
    """What a context_provider sees for one HTTP request.

    ``method``, ``headers`` and ``input`` (the parsed ``{"data": ...}``) are the
    same on every adapter, so a provider that reads only those works in Flask,
    Django and FastAPI. ``headers`` keys are lowercase so ``Authorization`` and
    ``authorization`` look the same on every served flow. Repeated names become
    one comma-joined string, so ``headers.get('authorization')`` sees every
    value that arrived. Pass ``headers`` as a mapping or as the raw
    ``(name, value)`` pairs off the wire.

    ``request`` is the framework's own request object (Django ``HttpRequest``,
    Flask ``Request``, Starlette ``Request``) for what the shared fields don't
    carry: cookies, sessions, the logged-in user. A provider that reads it works
    on that framework only.

    Example:
        ```python
        from genkit import FlowContext, PublicError
        from genkit.web import RequestData
        from genkit_django import genkit_django_handler


        # 1. Django session auth; auser() because the view is async (Django 5.0+,
        #    on 4.2 use sync_to_async(lambda: request.request.user)())
        async def django_user(request: RequestData) -> dict[str, object]:
            user = await request.request.auser()
            if not user.is_authenticated:
                raise PublicError('UNAUTHENTICATED', 'Sign in first')
            return {'user_id': user.pk}


        # 2. The flow reads it from ctx.context
        @genkit_django_handler(ai, context_provider=django_user)
        @ai.flow
        async def reorder(order_id: str, ctx: FlowContext) -> str:
            return f'reordered {order_id} for {ctx.context["user_id"]}'
            # => reordered ORD-9921 for 42
        ```
    """

    request: Any = None
    method: str = ''
    headers: dict[str, str] = field(default_factory=dict)
    input: Any = None

    def __init__(
        self,
        request: Any = None,  # noqa: ANN401
        method: str = '',
        headers: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
        input: Any = None,  # noqa: ANN401
    ) -> None:
        """Build request data; header names are lowercased and repeats comma-joined."""
        self.request = request
        self.method = method
        self.input = input
        pairs: Iterable[tuple[str, str]] = (
            cast(Mapping[str, str], headers).items() if isinstance(headers, Mapping) else headers or ()
        )
        # The same header can arrive twice (two Authorization lines, each hop
        # in an X-Forwarded-For chain). A context_provider looks the name up
        # once, so keep every part instead of dropping all but the last.
        self.headers = {}
        for name, value in pairs:
            key = name.lower()
            existing = self.headers.get(key)
            self.headers[key] = value if existing is None else f'{existing}, {value}'

__init__(request=None, method='', headers=None, input=None)

Build request data; header names are lowercased and repeats comma-joined.

Source code in packages/genkit/src/genkit/_core/_context.py
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
def __init__(
    self,
    request: Any = None,  # noqa: ANN401
    method: str = '',
    headers: Mapping[str, str] | Iterable[tuple[str, str]] | None = None,
    input: Any = None,  # noqa: ANN401
) -> None:
    """Build request data; header names are lowercased and repeats comma-joined."""
    self.request = request
    self.method = method
    self.input = input
    pairs: Iterable[tuple[str, str]] = (
        cast(Mapping[str, str], headers).items() if isinstance(headers, Mapping) else headers or ()
    )
    # The same header can arrive twice (two Authorization lines, each hop
    # in an X-Forwarded-For chain). A context_provider looks the name up
    # once, so keep every part instead of dropping all but the last.
    self.headers = {}
    for name, value in pairs:
        key = name.lower()
        existing = self.headers.get(key)
        self.headers[key] = value if existing is None else f'{existing}, {value}'

StreamHandle

Bases: typing.Protocol

Anything with chunks on .stream and a result on .response.

flow.stream(), ai.generate_stream(), prompt.stream() and chat.send_stream() all return one.

Source code in packages/genkit/src/genkit/web/_sse.py
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class StreamHandle(Protocol):
    """Anything with chunks on ``.stream`` and a result on ``.response``.

    ``flow.stream()``, ``ai.generate_stream()``, ``prompt.stream()`` and
    ``chat.send_stream()`` all return one.
    """

    @property
    def stream(self) -> AsyncIterator[object]:
        """Chunks, in order."""
        ...

    @property
    def response(self) -> Awaitable[object]:
        """The final result, once the stream ends."""
        ...

response property

The final result, once the stream ends.

stream property

Chunks, in order.

error_body(error)

JSON body to send back when a served flow fails.

Only a PublicError's message, details, and status go on the wire; it's the one error whose author said the text is safe for callers. A bad request to the flow itself keeps its 4xx status and names the failing fields without their values, such as "Invalid input for flow 'save': qty: Input should be a valid integer". Any other GenkitError, a provider error, and anything else become {"message": "Internal Error", "status": "INTERNAL"}. Under GENKIT_ENV=dev that body carries the error's own text instead, so a local curl shows the real cause; the status stays INTERNAL. Mirrors Go's wire.ClientMessage.

Example
from genkit.web import error_body, error_status

try:
    response = await my_flow.run(input=data)
except Exception as e:
    return JSONResponse(error_body(e), status_code=error_status(e))
Source code in packages/genkit/src/genkit/_core/_error.py
 991
 992
 993
 994
 995
 996
 997
 998
 999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
def error_body(error: Exception) -> dict[str, Any]:
    """JSON body to send back when a served flow fails.

    Only a PublicError's message, details, and status go on the wire; it's
    the one error whose author said the text is safe for callers. A bad
    request to the flow itself keeps its 4xx status and names the failing
    fields without their values, such as ``"Invalid input for flow 'save':
    qty: Input should be a valid integer"``. Any other GenkitError, a provider
    error, and anything else become ``{"message": "Internal Error", "status": "INTERNAL"}``.
    Under ``GENKIT_ENV=dev`` that body carries the error's own text instead,
    so a local curl shows the real cause; the status stays ``INTERNAL``.
    Mirrors Go's ``wire.ClientMessage``.

    Example:
        ```python
        from genkit.web import error_body, error_status

        try:
            response = await my_flow.run(input=data)
        except Exception as e:
            return JSONResponse(error_body(e), status_code=error_status(e))
        ```
    """
    facing = _client_facing_error(error)
    if facing is None:
        if is_dev_environment():
            return {'message': _dev_client_message(error), 'status': 'INTERNAL'}
        return dict(_INTERNAL_CLIENT_BODY)
    message = facing.message if isinstance(facing, PublicError) else _request_client_message(facing)
    body: dict[str, Any] = {
        'message': message,
        'status': facing.status,
    }
    if isinstance(facing, PublicError):
        details = _client_details(facing.details)
        if details is not None:
            body['details'] = details
    return body

error_json(error)

Encode error_body(error) as compact JSON; pair with error_status(error).

Source code in packages/genkit/src/genkit/web/_sse.py
 98
 99
100
def error_json(error: Exception) -> str:
    """Encode ``error_body(error)`` as compact JSON; pair with ``error_status(error)``."""
    return _dumps(error_body(error))

error_sse(error)

Encode error_body(error) as one data: {"error": ...}\n\n SSE frame.

Source code in packages/genkit/src/genkit/web/_sse.py
103
104
105
106
def error_sse(error: Exception) -> str:
    r"""Encode ``error_body(error)`` as one ``data: {"error": ...}\n\n`` SSE frame."""
    # For failures before to_sse runs, e.g. action.stream(...) raising.
    return _frame('error', error_body(error))

error_status(error)

HTTP status to send back when a served flow fails; pairs with error_body.

A PublicError keeps its own status (NOT_FOUND is a 404), and a bad request to the flow itself keeps its 4xx. Any other GenkitError, a provider error, a plain exception, or anything else is a 500.

Source code in packages/genkit/src/genkit/_core/_error.py
940
941
942
943
944
945
946
947
948
949
950
def error_status(error: Exception) -> int:
    """HTTP status to send back when a served flow fails; pairs with ``error_body``.

    A PublicError keeps its own status (NOT_FOUND is a 404), and a bad
    request to the flow itself keeps its 4xx. Any other GenkitError, a
    provider error, a plain exception, or anything else is a 500.
    """
    facing = _client_facing_error(error)
    if facing is not None:
        return http_status_code(facing.status)
    return 500

read_body(body)

Return the flow input from a parsed JSON request body.

{"data": x} gives x. {} and {"data": null} mean the caller sent no input, so a flow with a default uses it. Any other body is a 400 so the caller learns to wrap their input instead of the flow seeing a half-understood value.

Raises:

Type Description
genkit._core._error.PublicError

INVALID_ARGUMENT when the body isn't {"data": ...} or {}.

Source code in packages/genkit/src/genkit/_core/_web.py
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
def read_body(body: object) -> object:
    """Return the flow input from a parsed JSON request body.

    ``{"data": x}`` gives ``x``. ``{}`` and ``{"data": null}`` mean the caller
    sent no input, so a flow with a default uses it. Any other body is a 400
    so the caller learns to wrap their input instead of the flow seeing a
    half-understood value.

    Raises:
        PublicError: INVALID_ARGUMENT when the body isn't ``{"data": ...}`` or ``{}``.
    """
    if isinstance(body, dict):
        fields = cast(dict[str, object], body)
        if 'data' in fields:
            return input_from_json(fields['data'])
        if not fields:
            return input_from_json(None)
    raise PublicError('INVALID_ARGUMENT', 'Flow request must be wrapped in {"data": ...}')

result_json(result)

Encode a one-shot result as compact {"result": ...} JSON, the bytes every adapter sends.

A failed agent turn's error keeps its status but only a PublicError's message; anything else goes out as a generic message for that status.

Source code in packages/genkit/src/genkit/web/_sse.py
88
89
90
91
92
93
94
95
def result_json(result: object) -> str:
    """Encode a one-shot result as compact ``{"result": ...}`` JSON, the bytes every adapter sends.

    A failed agent turn's ``error`` keeps its status but only a PublicError's
    message; anything else goes out as a generic message for that status.
    """
    # Same encoding as to_sse frames: aliases, no null model fields.
    return _dumps({'result': _frame_value(result)})

to_sse(handle) async

Frame a streaming handle as Genkit SSE lines.

Yields data: {"message": ...} for each chunk, then data: {"result": ...}. If the run fails, it yields one data: {"error": ...} instead of the rest and logs the failure with Python's logging module (5xx with a traceback, 4xx as a warning). Only a PublicError's text reaches the client; anything else goes out as Internal Error. A failed agent turn's error in the result frame follows the same rule (see result_json). These are the frames serve_flow, handle_genkit_request and serve_agent send.

The result goes out as the run returned it. ai.generate_stream(), prompt.stream(), and flows returning a whole ModelResponse send its request too (system prompt, tools, docs, history), so stream a flow returning response.text or response.output from a served route.

.response is read only after the stream drains, so a handle that fails or is never iterated doesn't leave an un-awaited result behind.

Example
from fastapi import Depends
from fastapi.responses import StreamingResponse
from genkit.web import to_sse


@app.post('/deploy/stream')
async def deploy(service: str, user: User = Depends(current_user)):
    # 1. FastAPI owns the route: typed params, Depends, OpenAPI
    stream = deploy_service.stream(service, context={'user_id': user.id})

    # 2. Genkit owns the wire
    return StreamingResponse(to_sse(stream), media_type='text/event-stream')
    # => data: {"message":"[u_42] building payments"}
    #    data: {"result":"https://payments.run.app"}

Parameters:

Name Type Description Default
handle genkit.web._sse.StreamHandle

The streaming handle to frame.

required

Yields:

Type Description
collections.abc.AsyncGenerator[str, None]

One SSE data: line per frame, each ending in a blank line.

Source code in packages/genkit/src/genkit/web/_sse.py
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
async def to_sse(handle: StreamHandle) -> AsyncGenerator[str, None]:
    r"""Frame a streaming handle as Genkit SSE lines.

    Yields ``data: {"message": ...}`` for each chunk, then ``data: {"result": ...}``.
    If the run fails, it yields one ``data: {"error": ...}`` instead of the rest
    and logs the failure with Python's logging module (5xx with a traceback,
    4xx as a warning). Only a ``PublicError``'s text reaches the client; anything else goes out as
    ``Internal Error``. A failed agent turn's ``error`` in the result frame
    follows the same rule (see ``result_json``). These are the frames ``serve_flow``,
    ``handle_genkit_request`` and ``serve_agent`` send.

    The result goes out as the run returned it. ``ai.generate_stream()``,
    ``prompt.stream()``, and flows returning a whole ``ModelResponse`` send its
    ``request`` too (system prompt, tools, docs, history), so stream a flow
    returning ``response.text`` or ``response.output`` from a served route.

    ``.response`` is read only after the stream drains, so a handle that fails
    or is never iterated doesn't leave an un-awaited result behind.

    Example:
        ```python
        from fastapi import Depends
        from fastapi.responses import StreamingResponse
        from genkit.web import to_sse


        @app.post('/deploy/stream')
        async def deploy(service: str, user: User = Depends(current_user)):
            # 1. FastAPI owns the route: typed params, Depends, OpenAPI
            stream = deploy_service.stream(service, context={'user_id': user.id})

            # 2. Genkit owns the wire
            return StreamingResponse(to_sse(stream), media_type='text/event-stream')
            # => data: {"message":"[u_42] building payments"}
            #    data: {"result":"https://payments.run.app"}
        ```

    Args:
        handle: The streaming handle to frame.

    Yields:
        One SSE ``data:`` line per frame, each ending in a blank line.
    """
    chunks = handle.stream.__aiter__()
    try:
        try:
            async for chunk in chunks:
                yield _frame('message', _frame_value(chunk))
        finally:
            # Closing `to_sse` early (e.g. a client disconnect) closes the
            # chunk iterator right away so the run cancels immediately.
            aclose = getattr(chunks, 'aclose', None)
            if aclose is not None:
                await aclose()
        result = await handle.response
        # ModelStreamResponse boxes turn failures onto .response instead of raising
        # from .stream; re-raise here so SSE callers get the error frame and log.
        if (
            isinstance(handle, ModelStreamResponse)
            and isinstance(result, ModelResponse)
            and result.finish_reason == FinishReason.FAILED
        ):
            raise (
                result._failure.to_exception()
                if result._failure is not None
                else GenkitError(
                    status='INTERNAL',
                    message=result.finish_message or 'Model generation failed',
                )
            )
        yield _frame('result', _frame_value(result))
    except (Exception, Interrupt, TaskGroupError) as exc:
        failure = interrupt_escape_error(exc)
        if failure is not None:
            e: Exception = failure
        elif isinstance(exc, Exception):
            e = exc
        else:
            raise
        action_name = getattr(handle, '_action_name', None)
        if isinstance(action_name, str) and action_name:
            extra = {'genkit_action': action_name}
            if error_status(e) >= 500:
                _logger.exception('served action %r stream failed', action_name, extra=extra)
            else:
                _logger.warning('served action %r stream failed: %s', action_name, e, extra=extra)
        elif error_status(e) >= 500:
            _logger.exception('served stream failed')
        else:
            _logger.warning('served stream failed: %s', e)
        yield error_sse(e)

wants_stream(*, accept, stream)

Whether the caller asked for server-sent events.

Pass the Accept header and the ?stream= query value. Substring match so text/event-stream, */* still streams.

Source code in packages/genkit/src/genkit/_core/_web.py
45
46
47
48
49
50
51
def wants_stream(*, accept: str | None, stream: str | None) -> bool:
    """Whether the caller asked for server-sent events.

    Pass the ``Accept`` header and the ``?stream=`` query value. Substring
    match so ``text/event-stream, */*`` still streams.
    """
    return 'text/event-stream' in (accept or '') or stream == 'true'

genkit.exp

Experimental APIs. Agents stay here even after Genkit Python is GA.

from genkit.exp import Genkit
from genkit.exp.agent import InMemorySessionStore
from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()])
agent = ai.define_agent(
    name='weatherAgent',
    model=GoogleAI.gemini('gemini-flash-latest'),
    system='Weather assistant.',
    store=InMemorySessionStore(),
)

Genkit

Bases: genkit._ai._aio.Genkit

Genkit plus the agent APIs, which are still experimental.

Importing this class is how you opt into agents. The stable from genkit import Genkit does not grow these methods.

Source code in packages/genkit/src/genkit/exp/_api.py
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
class Genkit(StableGenkit):
    """Genkit plus the agent APIs, which are still experimental.

    Importing this class is how you opt into agents. The stable
    ``from genkit import Genkit`` does not grow these methods.
    """

    async def agent(self, name: str) -> Agent:
        """Look up a registered agent by name."""
        resolved = await self._registry.resolve_action(ActionKind.AGENT, name)
        if resolved is None:
            raise GenkitError(
                status='NOT_FOUND',
                message=f"Agent '{name}' not found in registry.",
                reason=ErrorReason.ACTION_NOT_FOUND,
            )
        if not isinstance(resolved, Agent):
            raise GenkitError(
                status='INTERNAL',
                message=f"Registry entry '{name}' is not an Agent.",
            )
        return resolved

    def define_custom_agent(
        self,
        name: str,
        fn: AgentFn,
        *,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
    ) -> Agent[StateT]:
        """Define and register an agent with full control over the turn loop.

        fn receives (SessionRunner, AgentContext) and must call sess.run(handle_turn)
        to process inputs, then return an AgentResult.

        Pass ``state_schema`` (a Pydantic model) to type the custom state, so the
        chat's ``state``, ``response.state``, and streamed ``chunk.custom`` come
        back as that model instead of a dict.
        """
        return define_custom_agent(
            self,
            name=name,
            fn=fn,
            store=store,
            state_transform=state_transform,
            chunk_transform=chunk_transform,
            state_schema=state_schema,
            description=description,
            metadata=metadata,
        )

    # No config: any ref, including one picked between providers.
    @overload
    def define_agent(
        self,
        name: str,
        *,
        model: ModelRef[Any] | Action | str | None = None,
        system: str | list[Part] | None = None,
        tools: Sequence[str | Tool] | None = None,
        use: Sequence[Middleware] | None = None,
        config: None = None,
        max_turns: int | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
    ) -> Agent[StateT]: ...

    @overload
    def define_agent(
        self,
        name: str,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        system: str | list[Part] | None = None,
        tools: Sequence[str | Tool] | None = None,
        use: Sequence[Middleware] | None = None,
        config: ModelConfigDict,
        max_turns: int | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
    ) -> Agent[StateT]: ...

    @overload
    def define_agent(
        self,
        name: str,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        system: str | list[Part] | None = None,
        tools: Sequence[str | Tool] | None = None,
        use: Sequence[Middleware] | None = None,
        config: ModelRefConfigT | Mapping[str, Any] | None,
        max_turns: int | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
    ) -> Agent[StateT]: ...

    def define_agent(
        self,
        name: str,
        *,
        model: ModelRef[ModelRefConfigT] | Action | str | None = None,
        system: str | list[Part] | None = None,
        tools: Sequence[str | Tool] | None = None,
        use: Sequence[Middleware] | None = None,
        config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
        max_turns: int | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
    ) -> Agent[StateT]:
        """Define a prompt-backed agent.

        Each turn: attaches session history, calls generate with streaming,
        updates session. Pass resume in AgentInput to resume from an interrupt.

        Pass ``state_schema`` (a Pydantic model) to type the custom state tools
        read and write — the chat's ``state``, ``response.state``, and streamed
        ``chunk.custom`` come back as that model instead of a dict.

        Example:
            from genkit.exp import Genkit
            from genkit.exp.agent import InMemorySessionStore
            from genkit_google_genai import GoogleAI

            ai = Genkit(plugins=[GoogleAI()])
            agent = ai.define_agent(
                name='weatherAgent',
                model=GoogleAI.gemini('gemini-flash-latest'),
                system='Weather assistant.',
                tools=[current_weather],
                store=InMemorySessionStore(),
            )
            chat = agent.chat()
            res = await chat.send('Weather in Paris?')
        """
        return define_agent(
            self,
            name=name,
            model=model,
            system=system,
            tools=tools,
            use=use,
            config=config,
            max_turns=max_turns,
            description=description,
            metadata=metadata,
            store=store,
            state_transform=state_transform,
            chunk_transform=chunk_transform,
            state_schema=state_schema,
        )

    def define_prompt_agent(
        self,
        name: str,
        *,
        store: SessionStore[StateT] | None = None,
        state_transform: StateTransform | None = None,
        chunk_transform: ChunkTransform | None = None,
        state_schema: type[StateT] | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
    ) -> Agent[StateT]:
        """Wire an already-registered prompt as an agent.

        Looks up the prompt named `name` from the registry. Use when the prompt
        is defined via ai.define_prompt() or loaded from a .prompt file.
        """
        return define_prompt_agent(
            self,
            name=name,
            store=store,
            state_transform=state_transform,
            chunk_transform=chunk_transform,
            state_schema=state_schema,
            description=description,
            metadata=metadata,
        )

__init__(*args, plugins=None, model=None, prompt_dir=None)

Initialize a Genkit instance.

Parameters:

Name Type Description Default
plugins list[genkit._core._plugin.Plugin] | None

Plugins to register (e.g. [GoogleAI()]). Plugins resolve models lazily on demand when ai.generate() is called.

None
model genkit._ai._model.ModelArg | None

Default model for ai.generate(). Accepts a typed ModelRef (recommended, e.g. GoogleAI.gemini('gemini-flash-latest')) or a plugin-prefixed string ('googleai/gemini-flash-latest').

None
prompt_dir str | pathlib.Path | None

Optional directory for loading .prompt files.

None
Source code in packages/genkit/src/genkit/_ai/_aio.py
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
def __init__(  # noqa: D417
    self,
    *args: object,
    plugins: list[Plugin] | None = None,
    model: ModelArg | None = None,
    prompt_dir: str | Path | None = None,
) -> None:
    """Initialize a Genkit instance.

    Args:
        plugins: Plugins to register (e.g. ``[GoogleAI()]``). Plugins resolve
            models lazily on demand when ``ai.generate()`` is called.
        model: Default model for ``ai.generate()``. Accepts a typed ``ModelRef``
            (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``) or
            a plugin-prefixed string (``'googleai/gemini-flash-latest'``).
        prompt_dir: Optional directory for loading ``.prompt`` files.
    """
    if args:
        raise TypeError(
            f'Genkit() takes no positional arguments, got {len(args)}. '
            f'Pass keyword arguments instead, e.g. {init_keyword_example(args[0])}.'
        )
    # Before anything that logs, so plugin initialization is covered too.
    configure_logging()
    self._registry = Registry()
    self._reflection_server_spec = None
    # The reflection API runs under GENKIT_ENV=dev, or in any environment
    # with GENKIT_REFLECTION_ENABLED=true. Resolving here keeps an invalid
    # setting a constructor-time error.
    self._reflection_config = resolve_reflection_config()
    self._reflection_ready = threading.Event()
    # Set when the reflection thread exits for any reason (v2 auth
    # rejection, server crash), so run_main stops waiting on nothing.
    self._reflection_stopped = threading.Event()
    # host:port the v1 socket is bound to, set in the constructor so
    # run_main can log it without waiting on the server thread.
    self._reflection_bound_addr = None
    self._initialize_registry(model, plugins)
    # Ensure the default generate action is registered for async usage.
    define_generate_action(self)
    self._register_plugin_middleware(plugins)
    maybe_inject_dev_instrumentation()
    # When reflection is on, start the server immediately in a background
    # daemon thread so it's available regardless of which web framework (or
    # none) the user chooses.
    if self._reflection_config.enabled:
        # SIGINT (Ctrl+C) always hits handle_signal. SIGTERM inside the
        # run_main wait loop is stolen by anyio (clean exit → atexit);
        # elsewhere SIGTERM also goes through handle_signal. Both paths
        # remove the runtime discovery files.
        setup_signal_handlers()
        self._start_reflection_background()

    # Load prompts
    load_path = prompt_dir
    if load_path is None:
        default_prompts_path = Path('./prompts')
        if default_prompts_path.is_dir():
            load_path = default_prompts_path

    if load_path:
        load_prompt_folder(self, dir_path=load_path)

agent(name) async

Look up a registered agent by name.

Source code in packages/genkit/src/genkit/exp/_api.py
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
async def agent(self, name: str) -> Agent:
    """Look up a registered agent by name."""
    resolved = await self._registry.resolve_action(ActionKind.AGENT, name)
    if resolved is None:
        raise GenkitError(
            status='NOT_FOUND',
            message=f"Agent '{name}' not found in registry.",
            reason=ErrorReason.ACTION_NOT_FOUND,
        )
    if not isinstance(resolved, Agent):
        raise GenkitError(
            status='INTERNAL',
            message=f"Registry entry '{name}' is not an Agent.",
        )
    return resolved

cancel_operation(operation, *, context=None, config=None) async

cancel_operation(
    operation: Operation[T],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[T]
cancel_operation(
    operation: Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[Any]

Cancel a background job.

Same input and return types as check_operation: Operation[T] in, Operation[T] out; a stored dict in, Operation[Any] out. Same context / config pockets.

Example
# 1. Reload the stored handle and cancel it
op = await ai.cancel_operation(json.loads(saved))

# 2. The returned handle reflects the cancel attempt
print(op.id)
# => operations/risotto-123
Source code in packages/genkit/src/genkit/_ai/_aio.py
2721
2722
2723
2724
2725
2726
2727
2728
2729
2730
2731
2732
2733
2734
2735
2736
2737
2738
2739
2740
2741
2742
2743
2744
async def cancel_operation(
    self,
    operation: Operation[Any] | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None,
) -> Operation[Any]:
    """Cancel a background job.

    Same input and return types as ``check_operation``: ``Operation[T]``
    in, ``Operation[T]`` out; a stored dict in, ``Operation[Any]`` out.
    Same ``context`` / ``config`` pockets.

    Example:
        ```python
        # 1. Reload the stored handle and cancel it
        op = await ai.cancel_operation(json.loads(saved))

        # 2. The returned handle reflects the cancel attempt
        print(op.id)
        # => operations/risotto-123
        ```
    """
    return await cancel_operation(self._registry, operation, context=context, config=config)

check_operation(operation, *, context=None, config=None) async

check_operation(
    operation: Operation[T],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[T]
check_operation(
    operation: Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None
) -> Operation[Any]

Poll a background job.

Generic like JS checkOperation<T>: an Operation[T] comes back as Operation[T], a stored dict as Operation[Any]. The handle's action key finds the job. For a background model the handle is validated as Operation[ModelResponse] before anything runs: an unknown key, a missing id, or an output that isn't a ModelResponse is INVALID_ARGUMENT.

Pass context={'secrets': {'api_key': ...}} again when start used a per-request key. config is client knobs (base_url, location, api_version), not video settings.

Example
# 1. Start a job and store the handle as JSON
op = await ai.generate_operation(
    model='googleai/veo-3.1-generate-preview',
    prompt='A chef plating risotto.',
)
saved = op.model_dump_json()

# 2. Later, reload it typed and poll
op = await ai.check_operation(Operation[ModelResponse].model_validate_json(saved))
print(op.done)
# => False

# 3. Poll until done; output is a ModelResponse
while not op.done:
    op = await ai.check_operation(op)
if op.output and op.output.media:
    print(op.output.media.url)
# => https://storage.googleapis.com/.../risotto.mp4
Source code in packages/genkit/src/genkit/_ai/_aio.py
2659
2660
2661
2662
2663
2664
2665
2666
2667
2668
2669
2670
2671
2672
2673
2674
2675
2676
2677
2678
2679
2680
2681
2682
2683
2684
2685
2686
2687
2688
2689
2690
2691
2692
2693
2694
2695
2696
2697
2698
2699
2700
2701
async def check_operation(
    self,
    operation: Operation[Any] | Mapping[str, Any],
    *,
    context: dict[str, Any] | None = None,
    config: Mapping[str, Any] | None = None,
) -> Operation[Any]:
    """Poll a background job.

    Generic like JS ``checkOperation<T>``: an ``Operation[T]`` comes back
    as ``Operation[T]``, a stored dict as ``Operation[Any]``. The handle's
    ``action`` key finds the job. For a background model the handle is
    validated as ``Operation[ModelResponse]`` before anything runs: an
    unknown key, a missing ``id``, or an ``output`` that isn't a
    ModelResponse is INVALID_ARGUMENT.

    Pass ``context={'secrets': {'api_key': ...}}`` again when start used a
    per-request key. ``config`` is client knobs (``base_url``,
    ``location``, ``api_version``), not video settings.

    Example:
        ```python
        # 1. Start a job and store the handle as JSON
        op = await ai.generate_operation(
            model='googleai/veo-3.1-generate-preview',
            prompt='A chef plating risotto.',
        )
        saved = op.model_dump_json()

        # 2. Later, reload it typed and poll
        op = await ai.check_operation(Operation[ModelResponse].model_validate_json(saved))
        print(op.done)
        # => False

        # 3. Poll until done; output is a ModelResponse
        while not op.done:
            op = await ai.check_operation(op)
        if op.output and op.output.media:
            print(op.output.media.url)
        # => https://storage.googleapis.com/.../risotto.mp4
        ```
    """
    return await check_operation(self._registry, operation, context=context, config=config)

current_context() staticmethod

Get the current execution context, or None if not in an action.

Source code in packages/genkit/src/genkit/_ai/_aio.py
2596
2597
2598
2599
@staticmethod
def current_context() -> dict[str, Any] | None:
    """Get the current execution context, or None if not in an action."""
    return get_current_context()

define_agent(name, *, model=None, system=None, tools=None, use=None, config=None, max_turns=None, description=None, metadata=None, store=None, state_transform=None, chunk_transform=None, state_schema=None)

define_agent(
    name: str,
    *,
    model: ModelRef[Any] | Action | str | None = None,
    system: str | list[Part] | None = None,
    tools: Sequence[str | Tool] | None = None,
    use: Sequence[Middleware] | None = None,
    config: None = None,
    max_turns: int | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None
) -> Agent[StateT]
define_agent(
    name: str,
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    system: str | list[Part] | None = None,
    tools: Sequence[str | Tool] | None = None,
    use: Sequence[Middleware] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None
) -> Agent[StateT]
define_agent(
    name: str,
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    system: str | list[Part] | None = None,
    tools: Sequence[str | Tool] | None = None,
    use: Sequence[Middleware] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None
) -> Agent[StateT]

Define a prompt-backed agent.

Each turn: attaches session history, calls generate with streaming, updates session. Pass resume in AgentInput to resume from an interrupt.

Pass state_schema (a Pydantic model) to type the custom state tools read and write — the chat's state, response.state, and streamed chunk.custom come back as that model instead of a dict.

Example

from genkit.exp import Genkit from genkit.exp.agent import InMemorySessionStore from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()]) agent = ai.define_agent( name='weatherAgent', model=GoogleAI.gemini('gemini-flash-latest'), system='Weather assistant.', tools=[current_weather], store=InMemorySessionStore(), ) chat = agent.chat() res = await chat.send('Weather in Paris?')

Source code in packages/genkit/src/genkit/exp/_api.py
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
def define_agent(
    self,
    name: str,
    *,
    model: ModelRef[ModelRefConfigT] | Action | str | None = None,
    system: str | list[Part] | None = None,
    tools: Sequence[str | Tool] | None = None,
    use: Sequence[Middleware] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    max_turns: int | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None,
) -> Agent[StateT]:
    """Define a prompt-backed agent.

    Each turn: attaches session history, calls generate with streaming,
    updates session. Pass resume in AgentInput to resume from an interrupt.

    Pass ``state_schema`` (a Pydantic model) to type the custom state tools
    read and write — the chat's ``state``, ``response.state``, and streamed
    ``chunk.custom`` come back as that model instead of a dict.

    Example:
        from genkit.exp import Genkit
        from genkit.exp.agent import InMemorySessionStore
        from genkit_google_genai import GoogleAI

        ai = Genkit(plugins=[GoogleAI()])
        agent = ai.define_agent(
            name='weatherAgent',
            model=GoogleAI.gemini('gemini-flash-latest'),
            system='Weather assistant.',
            tools=[current_weather],
            store=InMemorySessionStore(),
        )
        chat = agent.chat()
        res = await chat.send('Weather in Paris?')
    """
    return define_agent(
        self,
        name=name,
        model=model,
        system=system,
        tools=tools,
        use=use,
        config=config,
        max_turns=max_turns,
        description=description,
        metadata=metadata,
        store=store,
        state_transform=state_transform,
        chunk_transform=chunk_transform,
        state_schema=state_schema,
    )

define_background_model(name, *, start, check, cancel=None, info=None, config_schema=None, metadata=None, description=None)

Register a background model for long-running AI operations.

Source code in packages/genkit/src/genkit/_ai/_aio.py
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
def define_background_model(
    self,
    name: str,
    *,
    start: StartModelOpFn,
    check: CheckModelOpFn,
    cancel: CancelModelOpFn | None = None,
    info: ModelInfo | None = None,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> BackgroundModel:
    """Register a background model for long-running AI operations."""
    return define_background_model(
        registry=self._registry,
        name=name,
        start=start,
        check=check,
        cancel=cancel,
        info=info,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_batch_evaluator(name, fn, *, display_name, definition, is_billed=False, config_schema=None, metadata=None, description=None)

Register a batch evaluator.

The function takes one EvaluatorRequest and returns list[EvaluatorResponse]. Read options from req.options. A second parameter raises TypeError when defined.

Source code in packages/genkit/src/genkit/_ai/_aio.py
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
def define_batch_evaluator(
    self,
    name: str,
    fn: BatchEvaluatorFn,
    *,
    display_name: str,
    definition: str,
    is_billed: bool = False,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> BatchEvaluator:
    """Register a batch evaluator.

    The function takes one ``EvaluatorRequest`` and returns ``list[EvaluatorResponse]``.
    Read options from ``req.options``. A second parameter raises ``TypeError`` when defined.
    """
    return define_batch_evaluator(
        self._registry,
        name=name,
        display_name=display_name,
        definition=definition,
        fn=fn,
        is_billed=is_billed,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_custom_agent(name, fn, *, store=None, state_transform=None, chunk_transform=None, state_schema=None, description=None, metadata=None)

Define and register an agent with full control over the turn loop.

fn receives (SessionRunner, AgentContext) and must call sess.run(handle_turn) to process inputs, then return an AgentResult.

Pass state_schema (a Pydantic model) to type the custom state, so the chat's state, response.state, and streamed chunk.custom come back as that model instead of a dict.

Source code in packages/genkit/src/genkit/exp/_api.py
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def define_custom_agent(
    self,
    name: str,
    fn: AgentFn,
    *,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
) -> Agent[StateT]:
    """Define and register an agent with full control over the turn loop.

    fn receives (SessionRunner, AgentContext) and must call sess.run(handle_turn)
    to process inputs, then return an AgentResult.

    Pass ``state_schema`` (a Pydantic model) to type the custom state, so the
    chat's ``state``, ``response.state``, and streamed ``chunk.custom`` come
    back as that model instead of a dict.
    """
    return define_custom_agent(
        self,
        name=name,
        fn=fn,
        store=store,
        state_transform=state_transform,
        chunk_transform=chunk_transform,
        state_schema=state_schema,
        description=description,
        metadata=metadata,
    )

define_dynamic_action_provider(name, fn, *, description=None, cache_ttl_millis=None, metadata=None)

Register a Dynamic Action Provider (DAP).

Source code in packages/genkit/src/genkit/_ai/_aio.py
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
def define_dynamic_action_provider(
    self,
    name: str,
    fn: DapFn,
    *,
    description: str | None = None,
    cache_ttl_millis: int | None = None,
    metadata: dict[str, Any] | None = None,
) -> DynamicActionProvider:
    """Register a Dynamic Action Provider (DAP)."""
    return define_dap_block(
        self._registry,
        name,
        fn,
        description=description,
        cache_ttl_millis=cache_ttl_millis,
        metadata=metadata,
    )

define_embedder(name, fn, *, info=None, metadata=None, description=None, config_schema=None)

define_embedder(
    name: str,
    fn: EmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> Embedder
define_embedder(
    name: str,
    fn: CtxFirstEmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> Embedder

Register a custom embedder action.

The options class comes from config_schema or the fn's EmbedRequest[Cfg] annotation; given both, they must be the same class.

Source code in packages/genkit/src/genkit/_ai/_aio.py
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
def define_embedder(
    self,
    name: str,
    fn: EmbedderFn | CtxFirstEmbedderFn,
    *,
    info: EmbedderInfo | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
) -> Embedder:
    """Register a custom embedder action.

    The options class comes from ``config_schema`` or the fn's
    ``EmbedRequest[Cfg]`` annotation; given both, they must be the same class.
    """
    return define_embedder(self._registry, name, fn, info, metadata, description, config_schema=config_schema)

define_evaluator(name, fn, *, display_name, definition, is_billed=False, config_schema=None, metadata=None, description=None)

Register an evaluator that scores one dataset row at a time.

Example
# 1. Score whether the answer mentions the expected dish
async def mentions_dish(row: BaseDataPoint, options: object | None) -> EvaluatorResponse:
    hit = row.reference.lower() in str(row.output).lower()
    return EvaluatorResponse(test_case_id=row.test_case_id or '', evaluation=[Score(score=hit)])


# 2. Register it under a name
ai.define_evaluator(
    'mentions_dish',
    mentions_dish,
    display_name='Mentions dish',
    definition='Whether the answer names the expected dish.',
)

# 3. Run it over a dataset
rows = await ai.evaluate(evaluator='mentions_dish', dataset=dataset)
# => [EvaluatorResponse(test_case_id='...', evaluation=[Score(score=True)]), ...]
Source code in packages/genkit/src/genkit/_ai/_aio.py
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
def define_evaluator(
    self,
    name: str,
    fn: EvaluatorFn[Any],
    *,
    display_name: str,
    definition: str,
    is_billed: bool = False,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    description: str | None = None,
) -> Evaluator:
    """Register an evaluator that scores one dataset row at a time.

    Example:
        ```python
        # 1. Score whether the answer mentions the expected dish
        async def mentions_dish(row: BaseDataPoint, options: object | None) -> EvaluatorResponse:
            hit = row.reference.lower() in str(row.output).lower()
            return EvaluatorResponse(test_case_id=row.test_case_id or '', evaluation=[Score(score=hit)])


        # 2. Register it under a name
        ai.define_evaluator(
            'mentions_dish',
            mentions_dish,
            display_name='Mentions dish',
            definition='Whether the answer names the expected dish.',
        )

        # 3. Run it over a dataset
        rows = await ai.evaluate(evaluator='mentions_dish', dataset=dataset)
        # => [EvaluatorResponse(test_case_id='...', evaluation=[Score(score=True)]), ...]
        ```
    """
    return define_evaluator(
        self._registry,
        name=name,
        display_name=display_name,
        definition=definition,
        fn=fn,
        is_billed=is_billed,
        config_schema=config_schema,
        metadata=metadata,
        description=description,
    )

define_format(formatter)

Register a custom output format. See genkit.formats.Formatter.

Source code in packages/genkit/src/genkit/_ai/_aio.py
900
901
902
def define_format(self, formatter: Formatter) -> None:
    """Register a custom output format. See `genkit.formats.Formatter`."""
    self._registry.register_value('format', formatter.name, formatter)

define_helper(name, fn)

Register a Handlebars helper for prompt templates.

Dotprompt calls the helper as fn(params, options): params is a list of the positional arguments from the template, and options carries the named arguments in options.hash. A one-argument function such as lambda s: s.upper() raises TypeError at render time. Return a str.

Example
# 1. Register a helper that takes one positional and one named argument
def menu_item(params: list[Any], options: Any) -> str:
    dish = str(params[0])
    return dish.upper() if options.hash.get('loud') else dish


ai.define_helper('menu_item', menu_item)

# 2. Use it in a prompt template
special = ai.define_prompt(
    name='special',
    model='googleai/gemini-flash-latest',
    prompt="Describe today's special, {{menu_item dish loud=true}}, in one line.",
)

# 3. Render to check the expanded text
request = await special.render(input={'dish': 'smoked salmon tartine'})
print(request.messages[0].content[0].text)
# => Describe today's special, SMOKED SALMON TARTINE, in one line.
Source code in packages/genkit/src/genkit/_ai/_aio.py
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
def define_helper(self, name: str, fn: Callable[..., Any]) -> None:
    """Register a Handlebars helper for prompt templates.

    Dotprompt calls the helper as ``fn(params, options)``: ``params`` is a
    list of the positional arguments from the template, and ``options``
    carries the named arguments in ``options.hash``. A one-argument
    function such as ``lambda s: s.upper()`` raises ``TypeError`` at
    render time. Return a ``str``.

    Example:
        ```python
        # 1. Register a helper that takes one positional and one named argument
        def menu_item(params: list[Any], options: Any) -> str:
            dish = str(params[0])
            return dish.upper() if options.hash.get('loud') else dish


        ai.define_helper('menu_item', menu_item)

        # 2. Use it in a prompt template
        special = ai.define_prompt(
            name='special',
            model='googleai/gemini-flash-latest',
            prompt="Describe today's special, {{menu_item dish loud=true}}, in one line.",
        )

        # 3. Render to check the expanded text
        request = await special.render(input={'dish': 'smoked salmon tartine'})
        print(request.messages[0].content[0].text)
        # => Describe today's special, SMOKED SALMON TARTINE, in one line.
        ```
    """
    define_helper(self._registry, name, fn)

define_interrupt(name, *, input_schema=None, description=None)

Register an interrupt tool that always pauses for user input.

Parameters:

Name Type Description Default
name str

Tool name

required
input_schema type[pydantic.BaseModel] | dict[str, object] | None

Optional input schema (Pydantic model or JSON schema dict)

None
description str | None

Tool description

None

Returns:

Type Description
genkit._core._tool.Tool[typing.Any, typing.NoReturn]

The registered interrupt tool. Awaiting it directly raises Interrupt.

Example

ask_user = ai.define_interrupt( name='ask_user', input_schema=Question, description='Ask the user a question', )

Source code in packages/genkit/src/genkit/_ai/_aio.py
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
def define_interrupt(
    self,
    name: str,
    *,
    input_schema: type[BaseModel] | dict[str, object] | None = None,
    description: str | None = None,
) -> Tool[Any, NoReturn]:
    """Register an interrupt tool that always pauses for user input.

    Args:
        name: Tool name
        input_schema: Optional input schema (Pydantic model or JSON schema dict)
        description: Tool description

    Returns:
        The registered interrupt tool. Awaiting it directly raises ``Interrupt``.

    Example:
        ask_user = ai.define_interrupt(
            name='ask_user',
            input_schema=Question,
            description='Ask the user a question',
        )
    """
    return define_interrupt(
        self._registry,
        name,
        description=description,
        input_schema=input_schema,
    )

define_json_schema(name, json_schema)

Register a JSON schema for use in prompts.

Source code in packages/genkit/src/genkit/_ai/_aio.py
499
500
501
502
def define_json_schema(self, name: str, json_schema: dict[str, object]) -> dict[str, object]:
    """Register a JSON schema for use in prompts."""
    self._registry.register_schema(name, json_schema)
    return json_schema

define_middleware(cls, *, name=None, description=None)

Register a middleware class on this app's registry.

Source code in packages/genkit/src/genkit/_ai/_aio.py
645
646
647
648
649
650
651
652
653
654
655
def define_middleware(
    self,
    cls: type[MiddlewareT],
    *,
    name: str | None = None,
    description: str | None = None,
) -> type[MiddlewareT]:
    """Register a middleware class on this app's registry."""
    desc = cls._middleware_metadata(name, description=description)
    self._registry.register_value('middleware', desc.name, desc)
    return cls

define_model(name, fn, *, config_schema=None, metadata=None, info=None, description=None)

define_model(
    name: str,
    fn: ModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> Model
define_model(
    name: str,
    fn: CtxFirstModelFn,
    *,
    config_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None
) -> Model

Register a custom model action.

Source code in packages/genkit/src/genkit/_ai/_aio.py
821
822
823
824
825
826
827
828
829
830
831
832
def define_model(
    self,
    name: str,
    fn: ModelFn | CtxFirstModelFn,
    *,
    config_schema: type[BaseModel] | dict[str, object] | None = None,
    metadata: dict[str, object] | None = None,
    info: ModelInfo | None = None,
    description: str | None = None,
) -> Model:
    """Register a custom model action."""
    return define_model(self._registry, name, fn, config_schema, metadata, info, description)

define_partial(name, source)

Register a Handlebars partial template.

Source code in packages/genkit/src/genkit/_ai/_aio.py
490
491
492
def define_partial(self, name: str, source: str) -> None:
    """Register a Handlebars partial template."""
    define_partial(self._registry, name, source)

define_prompt(name=None, *, variant=None, model=None, config=None, description=None, system=None, prompt=None, messages=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, max_turns=None, return_tool_requests=None, metadata=None, tools=None, tool_choice=None, use=None, docs=None, input_schema=None, output_schema=None)

define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type[InputT],
    output_schema: dict[str, object] | str | None = None
) -> Prompt[InputT, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: dict[str, object] | str | None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: ModelRef[Any] | Action | str | None = None,
    config: None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelConfigDict,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]
define_prompt(
    name: str | None = None,
    *,
    variant: str | None = None,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: (
        type | dict[str, object] | str | None
    ) = None,
    output_schema: (
        type | dict[str, object] | str | None
    ) = None
) -> Prompt[Any, Any]

Register a prompt template.

Example

joke = ai.define_prompt(name='joke', prompt='Tell a joke about {{topic}}.') res = await joke(input={'topic': 'cats'}) print(res.text)

=> Why did the cat sit on the keyboard? To keep an eye on the mouse.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
def define_prompt(
    self,
    name: str | None = None,
    *,
    variant: str | None = None,
    model: str | ModelRef[Any] | Action | None = None,
    config: Mapping[str, Any] | BaseModel | ModelConfigDict | None = None,
    description: str | None = None,
    system: str | list[Part] | None = None,
    prompt: str | list[Part] | None = None,
    messages: str | list[Message] | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    max_turns: int | None = None,
    return_tool_requests: bool | None = None,
    metadata: dict[str, object] | None = None,
    tools: Sequence[str | Tool] | None = None,
    tool_choice: ToolChoice | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
    input_schema: type | dict[str, object] | str | None = None,
    output_schema: type | dict[str, object] | str | None = None,
) -> Prompt[Any, Any]:
    """Register a prompt template.

    Example:
        joke = ai.define_prompt(name='joke', prompt='Tell a joke about {{topic}}.')
        res = await joke(input={'topic': 'cats'})
        print(res.text)
        # => Why did the cat sit on the keyboard? To keep an eye on the mouse.
    """
    executable_prompt = Prompt(
        self,
        variant=variant,
        model=model,
        config=config,
        description=description,
        input_schema=input_schema,
        system=system,
        prompt=prompt,
        messages=messages,
        output_format=output_format,
        output_content_type=output_content_type,
        output_instructions=output_instructions,
        output_schema=output_schema,
        output_constrained=output_constrained,
        max_turns=max_turns,
        return_tool_requests=return_tool_requests,
        metadata=metadata,
        tools=tools,
        tool_choice=tool_choice,
        use=use,
        docs=docs,
        name=name,
    )
    if name:
        register_prompt_actions(self._registry, executable_prompt, name, variant)
    return executable_prompt

define_prompt_agent(name, *, store=None, state_transform=None, chunk_transform=None, state_schema=None, description=None, metadata=None)

Wire an already-registered prompt as an agent.

Looks up the prompt named name from the registry. Use when the prompt is defined via ai.define_prompt() or loaded from a .prompt file.

Source code in packages/genkit/src/genkit/exp/_api.py
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
def define_prompt_agent(
    self,
    name: str,
    *,
    store: SessionStore[StateT] | None = None,
    state_transform: StateTransform | None = None,
    chunk_transform: ChunkTransform | None = None,
    state_schema: type[StateT] | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
) -> Agent[StateT]:
    """Wire an already-registered prompt as an agent.

    Looks up the prompt named `name` from the registry. Use when the prompt
    is defined via ai.define_prompt() or loaded from a .prompt file.
    """
    return define_prompt_agent(
        self,
        name=name,
        store=store,
        state_transform=state_transform,
        chunk_transform=chunk_transform,
        state_schema=state_schema,
        description=description,
        metadata=metadata,
    )

define_schema(name, schema)

Register a Pydantic schema for use in prompts.

Source code in packages/genkit/src/genkit/_ai/_aio.py
494
495
496
497
def define_schema(self, name: str, schema: type[BaseModel]) -> type[BaseModel]:
    """Register a Pydantic schema for use in prompts."""
    define_schema(self._registry, name, schema)
    return schema

define_value(*, kind, name, value)

Store value under kind and name for later lookup_value.

Defining the same kind and name again replaces the value, so a re-run notebook cell does not fail.

Raises:

Type Description
ValueError

kind is one Genkit owns (use define_middleware, define_format, or Genkit(model=...)), or value is None.

Source code in packages/genkit/src/genkit/_ai/_aio.py
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
def define_value(self, *, kind: str, name: str, value: object) -> None:
    """Store ``value`` under ``kind`` and ``name`` for later ``lookup_value``.

    Defining the same kind and name again replaces the value, so a
    re-run notebook cell does not fail.

    Raises:
        ValueError: ``kind`` is one Genkit owns (use ``define_middleware``,
            ``define_format``, or ``Genkit(model=...)``), or ``value`` is None.
    """
    if kind in _CORE_VALUE_KINDS:
        raise ValueError(f'define_value kind {kind!r} is reserved; use {_CORE_VALUE_KINDS[kind]} instead.')
    if value is None:
        raise ValueError('define_value value must not be None; lookup_value returns None for "not defined".')
    self._registry.register_value(kind, name, value, allow_overwrite=True)

embed(*, embedder, content, metadata=None, config=None, context=None) async

embed(
    *,
    embedder: str | EmbedderRef[Any],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: None = None,
    context: dict[str, Any] | None = None
) -> list[Embedding]
embed(
    *,
    embedder: str | EmbedderRef[EmbedderRefConfigT],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: EmbedderRefConfigT | Mapping[str, Any] | None,
    context: dict[str, Any] | None = None
) -> list[Embedding]

Generate vector embeddings for a single document or string.

config is layered over the EmbedderRef's version and config (the call wins per key) and reaches the embedder as request.options. A config object must be the embedder's options class. An embedder name that isn't registered raises GenkitError with NOT_FOUND.

metadata is attached to a string content. A Document already carries its own metadata, so passing both raises TypeError.

context reaches the embedder as ctx.context, as on generate. Omitted, the embedder sees the enclosing action's context. The GoogleAI, VertexAI and OpenAI embedders read a per-request key from context={'secrets': {'api_key': ...}}, so the tenant, not the plugin key, is billed. Ollama and Bedrock embedders always use the plugin's client.

Example

from genkit_google_genai import GoogleAI

embeddings = await ai.embed( embedder=GoogleAI.embedder('gemini-embedding-001'), content='Hello world', ) vector = embeddings[0].embedding

Source code in packages/genkit/src/genkit/_ai/_aio.py
2419
2420
2421
2422
2423
2424
2425
2426
2427
2428
2429
2430
2431
2432
2433
2434
2435
2436
2437
2438
2439
2440
2441
2442
2443
2444
2445
2446
2447
2448
2449
2450
2451
2452
2453
2454
2455
2456
2457
2458
2459
2460
2461
2462
2463
2464
2465
2466
2467
2468
2469
2470
2471
async def embed(
    self,
    *,
    embedder: str | EmbedderRef[Any],
    content: str | Document,
    metadata: dict[str, object] | None = None,
    config: BaseModel | Mapping[str, Any] | None = None,
    context: dict[str, Any] | None = None,
) -> list[Embedding]:
    """Generate vector embeddings for a single document or string.

    ``config`` is layered over the ``EmbedderRef``'s version and config
    (the call wins per key) and reaches the embedder as
    ``request.options``. A config object must be the embedder's options
    class. An embedder name that isn't registered raises ``GenkitError``
    with ``NOT_FOUND``.

    ``metadata`` is attached to a string ``content``. A ``Document``
    already carries its own metadata, so passing both raises ``TypeError``.

    ``context`` reaches the embedder as ``ctx.context``, as on
    ``generate``. Omitted, the embedder sees the enclosing action's
    context. The GoogleAI, VertexAI and OpenAI embedders read a
    per-request key from ``context={'secrets': {'api_key': ...}}``, so
    the tenant, not the plugin key, is billed. Ollama and Bedrock
    embedders always use the plugin's client.

    Example:
        from genkit_google_genai import GoogleAI

        embeddings = await ai.embed(
            embedder=GoogleAI.embedder('gemini-embedding-001'),
            content='Hello world',
        )
        vector = embeddings[0].embedding
    """
    if metadata is not None and isinstance(content, Document):
        raise TypeError(_DOCUMENT_METADATA_CONFLICT)

    embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

    documents = [Document.from_text(content, metadata)] if isinstance(content, str) else [content]

    response = (
        await embed_action.run(
            EmbedRequest(
                input=documents,
                options=final_options,
            ),
            context=context,
        )
    ).response
    return response.embeddings

embed_many(*, embedder, content, metadata=None, config=None, context=None) async

embed_many(
    *,
    embedder: str | EmbedderRef[Any],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: None = None,
    context: dict[str, Any] | None = None
) -> list[Embedding]
embed_many(
    *,
    embedder: str | EmbedderRef[EmbedderRefConfigT],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: EmbedderRefConfigT | Mapping[str, Any] | None,
    context: dict[str, Any] | None = None
) -> list[Embedding]

Generate vector embeddings for multiple documents in a single batch call.

content is any sequence (list, tuple, ...) of strings or Documents; one embedding comes back per item, in order. A bare str raises TypeError; use embed for one item. config, metadata and context work the same as on embed.

Source code in packages/genkit/src/genkit/_ai/_aio.py
2497
2498
2499
2500
2501
2502
2503
2504
2505
2506
2507
2508
2509
2510
2511
2512
2513
2514
2515
2516
2517
2518
2519
2520
2521
2522
2523
2524
2525
2526
2527
2528
async def embed_many(
    self,
    *,
    embedder: str | EmbedderRef[Any],
    content: Sequence[str | Document],
    metadata: dict[str, object] | None = None,
    config: BaseModel | Mapping[str, Any] | None = None,
    context: dict[str, Any] | None = None,
) -> list[Embedding]:
    """Generate vector embeddings for multiple documents in a single batch call.

    ``content`` is any sequence (list, tuple, ...) of strings or
    ``Document``s; one embedding comes back per item, in order. A bare
    ``str`` raises ``TypeError``; use ``embed`` for one item.
    ``config``, ``metadata`` and ``context`` work the same as on ``embed``.
    """
    if isinstance(content, str):
        raise TypeError('embed_many() takes a sequence of strings or Documents, not a str; use embed() for one.')
    if metadata is not None and any(isinstance(item, Document) for item in content):
        raise TypeError(_DOCUMENT_METADATA_CONFLICT)

    # Convert strings to Documents if needed
    documents: list[Document] = [
        Document.from_text(item, metadata) if isinstance(item, str) else item for item in content
    ]

    embed_action, final_options = await self._embedder_and_options(embedder=embedder, config=config)

    response = (
        await embed_action.run(EmbedRequest(input=documents, options=final_options), context=context)  # type: ignore[arg-type]
    ).response
    return response.embeddings

evaluate(*, evaluator, dataset, config=None, eval_run_id=None) async

Evaluate a dataset using the specified evaluator.

Returns a list of rows. A per-row evaluator gives one row per datapoint, in dataset order. A batch evaluator gives the rows its function returned, as returned. Each row's evaluation is a list of scores.

config is merged over the EvaluatorRef's config (the call wins per key) and handed to the evaluator as its second argument. When neither sets anything, the evaluator gets None. An evaluator name that isn't registered raises GenkitError with NOT_FOUND.

Example

from genkit.evaluator import BaseDataPoint

results = await ai.evaluate( evaluator='my_eval', dataset=[BaseDataPoint(input='What is 2+2?', output='4')], ) for row in results: for score in row.evaluation: print(row.test_case_id, score.score)

Source code in packages/genkit/src/genkit/_ai/_aio.py
2530
2531
2532
2533
2534
2535
2536
2537
2538
2539
2540
2541
2542
2543
2544
2545
2546
2547
2548
2549
2550
2551
2552
2553
2554
2555
2556
2557
2558
2559
2560
2561
2562
2563
2564
2565
2566
2567
2568
2569
2570
2571
2572
2573
2574
2575
2576
2577
2578
2579
2580
2581
2582
2583
2584
2585
2586
2587
2588
2589
2590
2591
2592
2593
2594
async def evaluate(
    self,
    *,
    evaluator: str | EvaluatorRef,
    dataset: list[BaseDataPoint],
    config: dict[str, object] | None = None,
    eval_run_id: str | None = None,
) -> list[EvaluatorResponse]:
    """Evaluate a dataset using the specified evaluator.

    Returns a list of rows. A per-row evaluator gives one row per
    datapoint, in dataset order. A batch evaluator gives the rows its
    function returned, as returned. Each row's ``evaluation`` is a list of
    scores.

    ``config`` is merged over the ``EvaluatorRef``'s config (the call
    wins per key) and handed to the evaluator as its second argument. When
    neither sets anything, the evaluator gets ``None``. An evaluator name
    that isn't registered raises ``GenkitError`` with ``NOT_FOUND``.

    Example:
        from genkit.evaluator import BaseDataPoint

        results = await ai.evaluate(
            evaluator='my_eval',
            dataset=[BaseDataPoint(input='What is 2+2?', output='4')],
        )
        for row in results:
            for score in row.evaluation:
                print(row.test_case_id, score.score)
    """
    warn_evaluators_deprecated()
    if isinstance(evaluator, EvaluatorRef):
        evaluator_name = evaluator.name
        ref_config = evaluator.config
    else:
        evaluator_name = evaluator
        ref_config = None

    # same rule as _embedder_options: None when nothing was set, matching
    # what the CLI / Dev UI send, so `options is None` is the one check.
    final_options: dict[str, object] | None = None
    if ref_config is not None or config is not None:
        final_options = {**(ref_config or {}), **(config or {})}

    eval_action = await self._registry.resolve_evaluator(evaluator_name)
    if eval_action is None:
        raise GenkitError(
            status='NOT_FOUND',
            message=f"Evaluator '{evaluator_name}' not found.",
            reason=ErrorReason.ACTION_NOT_FOUND,
        )

    if not eval_run_id:
        eval_run_id = str(uuid.uuid4())

    with suppress_evaluator_warning():
        response = await eval_action.run(
            EvaluatorRequest(
                dataset=dataset,
                options=final_options,
                eval_run_id=eval_run_id,
            ),
        )
    return response.response.root

flow(name=None, *, description=None)

flow(
    name: str | None = None,
    *,
    description: str | None = None
) -> _FlowDecorator
flow(
    func: Callable[
        [FlowContext[ChunkT], object], Awaitable[OutputT]
    ],
) -> Flow[Any, OutputT, ChunkT]
flow(
    func: DefaultInputCtxFn[
        FlowContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedFlow[InputT, OutputT, ChunkT]
flow(
    func: Callable[
        [InputT, FlowContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Flow[InputT, OutputT, ChunkT]
flow(
    func: CtxDefaultInputFn[
        FlowContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedFlow[InputT, OutputT, ChunkT]
flow(
    func: Callable[
        [FlowContext[ChunkT], InputT], Awaitable[OutputT]
    ],
) -> Flow[InputT, OutputT, ChunkT]
flow(
    func: Callable[[object], Awaitable[OutputT]],
) -> Flow[Any, OutputT]
flow(
    func: Callable[
        [FlowContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Flow[None, OutputT, ChunkT]
flow(
    func: DefaultInputFn[InputT, OutputT],
) -> DefaultedFlow[InputT, OutputT]
flow(
    func: Callable[[InputT], Awaitable[OutputT]],
) -> Flow[InputT, OutputT]
flow(
    func: Callable[[], Awaitable[OutputT]],
) -> Flow[None, OutputT]

Decorator to register an async function as a flow.

Can be used bare (@ai.flow) or with arguments (@ai.flow(), @ai.flow('custom_name', description='...')).

A flow takes at most one input. To read the request context or stream chunks, add a parameter annotated FlowContext, in any position. Any other second parameter raises TypeError when the flow is defined.

Parameters:

Name Type Description Default
name str | collections.abc.Callable[..., collections.abc.Awaitable[typing.Any]] | None

Optional name for the flow (or the function itself when used as @ai.flow). Defaults to the function name.

None
description str | None

Optional description for the flow.

None
Example

from genkit import FlowContext, Genkit from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

@ai.flow async def my_flow(prompt: str) -> str: res = await ai.generate(prompt=prompt) return res.text

@ai.flow async def streaming_flow(x: int, ctx: FlowContext[str]) -> str: ctx.send_chunk('progress') return 'done'

Source code in packages/genkit/src/genkit/_ai/_aio.py
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
def flow(
    self,
    name: str | Callable[..., Awaitable[Any]] | None = None,
    *,
    description: str | None = None,
) -> _FlowDecorator | Flow[Any, Any, Any]:
    """Decorator to register an async function as a flow.

    Can be used bare (``@ai.flow``) or with arguments (``@ai.flow()``,
    ``@ai.flow('custom_name', description='...')``).

    A flow takes at most one input. To read the request context or stream
    chunks, add a parameter annotated ``FlowContext``, in any position.
    Any other second parameter raises ``TypeError`` when the flow is defined.

    Args:
        name: Optional name for the flow (or the function itself when used
            as ``@ai.flow``). Defaults to the function name.
        description: Optional description for the flow.

    Example:
        from genkit import FlowContext, Genkit
        from genkit_google_genai import GoogleAI

        ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))

        @ai.flow
        async def my_flow(prompt: str) -> str:
            res = await ai.generate(prompt=prompt)
            return res.text

        @ai.flow
        async def streaming_flow(x: int, ctx: FlowContext[str]) -> str:
            ctx.send_chunk('progress')
            return 'done'
    """
    if not isinstance(name, str) and name is not None:
        return _FlowDecorator(self._registry, None, description)(name)
    return _FlowDecorator(self._registry, name, description)

generate(*, model=None, prompt=None, system=None, messages=None, tools=None, return_tool_requests=None, tool_choice=None, resume_respond=None, resume_restart=None, resume_metadata=None, config=None, max_turns=None, context=None, output_schema=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, use=None, docs=None) async

generate(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[OutputT]
generate(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]
generate(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelResponse[Any]

Generate text or structured data using a language model.

model accepts a typed ModelRef from a plugin constructor (recommended, e.g. GoogleAI.gemini('gemini-flash-latest'), which takes the bare model ID, stamps the 'googleai/' namespace prefix, and type-checks config), a plugin-prefixed string ('googleai/gemini-flash-latest'), a registered model Action, or None to use the default model= passed to Genkit(...). When passing a plain str for a plugin model, the <plugin>/ prefix (such as 'googleai/' or 'vertexai/') is required; passing an unprefixed string raises GenkitError with NOT_FOUND. Any model ID served by the provider (including newly released models) is resolved lazily on demand at call time without needing pre-registration or SDK updates.

tools is typed as Sequence rather than list because Sequence is covariant: list[Tool] or list[str] are both assignable to Sequence[str | Tool], but not to list[str | Tool].

Example

from pydantic import BaseModel

class Weather(BaseModel): city: str forecast: str

res = await ai.generate( prompt='Weather in Paris?', tools=[current_weather], output_schema=Weather, ) if res.output: print(res.output)

=> city='Paris' forecast='Sunny'

max_turns caps tool rounds (default 50, matching Go): the model may call tools that many times and then reply, so a run uses at most max_turns + 1 model calls. Past the cap the response is ABORTED with reason MAX_TURNS_EXCEEDED.

prompt and system strings are sent exactly as written. Braces are content (JSON, code, or another template), not Handlebars. Partials ({{> persona}}), define_helper helpers and {{media url=...}} only render in define_prompt or a .prompt file; otherwise build the text or Part.from_media(...) yourself.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
async def generate(
    self,
    *,
    model: str | ModelRef[Any] | Action | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[Any] | dict[str, Any] | str | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> ModelResponse[Any]:
    """Generate text or structured data using a language model.

    ``model`` accepts a typed ``ModelRef`` from a plugin constructor
    (recommended, e.g. ``GoogleAI.gemini('gemini-flash-latest')``,
    which takes the bare model ID, stamps the ``'googleai/'`` namespace
    prefix, and type-checks ``config``), a plugin-prefixed string
    (``'googleai/gemini-flash-latest'``), a registered model ``Action``, or
    ``None`` to use the default ``model=`` passed to ``Genkit(...)``. When
    passing a plain ``str`` for a plugin model, the ``<plugin>/`` prefix
    (such as ``'googleai/'`` or ``'vertexai/'``) is required; passing an
    unprefixed string raises ``GenkitError`` with ``NOT_FOUND``. Any model
    ID served by the provider (including newly released models) is resolved
    lazily on demand at call time without needing pre-registration or SDK
    updates.

    ``tools`` is typed as ``Sequence`` rather than ``list`` because ``Sequence``
    is covariant: ``list[Tool]`` or ``list[str]`` are both assignable to
    ``Sequence[str | Tool]``, but not to ``list[str | Tool]``.

    Example:
        from pydantic import BaseModel

        class Weather(BaseModel):
            city: str
            forecast: str

        res = await ai.generate(
            prompt='Weather in Paris?',
            tools=[current_weather],
            output_schema=Weather,
        )
        if res.output:
            print(res.output)
        # => city='Paris' forecast='Sunny'

    ``max_turns`` caps tool rounds (default 50, matching Go): the model may
    call tools that many times and then reply, so a run uses at most
    ``max_turns + 1`` model calls. Past the cap the response is ``ABORTED``
    with reason ``MAX_TURNS_EXCEEDED``.

    ``prompt`` and ``system`` strings are sent exactly as written. Braces
    are content (JSON, code, or another template), not Handlebars.
    Partials (``{{> persona}}``), ``define_helper`` helpers and
    ``{{media url=...}}`` only render in ``define_prompt`` or a ``.prompt``
    file; otherwise build the text or ``Part.from_media(...)`` yourself.
    """
    return await self._generate(
        model=model,
        prompt=prompt,
        system=system,
        messages=messages,
        tools=tools,
        return_tool_requests=return_tool_requests,
        tool_choice=tool_choice,
        resume_respond=resume_respond,
        resume_restart=resume_restart,
        resume_metadata=resume_metadata,
        config=config,
        max_turns=max_turns,
        context=context,
        output_schema=output_schema,
        output_format=output_format,
        output_content_type=output_content_type,
        output_instructions=output_instructions,
        output_constrained=output_constrained,
        use=use,
        docs=docs,
    )

generate_operation(*, model=None, prompt=None, system=None, messages=None, config=None, context=None, use=None, docs=None) async

generate_operation(
    *,
    model: (
        ModelRef[Any] | BackgroundModel | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: None = None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]
generate_operation(
    *,
    model: (
        ModelRef[ModelRefConfigT]
        | BackgroundModel
        | str
        | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: ModelConfigDict,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]
generate_operation(
    *,
    model: (
        ModelRef[ModelRefConfigT]
        | BackgroundModel
        | str
        | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> Operation[ModelResponse]

Generate content using a long-running model, returning an Operation to poll.

A background start is one request that returns a job handle. There is no tool loop and no output parsing on check_operation, so tools, max_turns, and the output_* options are not accepted here.

Example

op = await ai.generate_operation( model='googleai/veo-3.1-generate-preview', prompt='A timelapse of a flower blooming.', ) while not op.done: op = await ai.check_operation(op)

Source code in packages/genkit/src/genkit/_ai/_aio.py
2789
2790
2791
2792
2793
2794
2795
2796
2797
2798
2799
2800
2801
2802
2803
2804
2805
2806
2807
2808
2809
2810
2811
2812
2813
2814
2815
2816
2817
2818
2819
2820
2821
2822
2823
2824
2825
2826
2827
2828
2829
2830
2831
2832
2833
2834
2835
2836
2837
2838
2839
2840
2841
2842
2843
2844
2845
2846
2847
2848
2849
2850
2851
2852
2853
2854
2855
2856
2857
2858
2859
2860
2861
2862
2863
2864
2865
2866
2867
async def generate_operation(
    self,
    *,
    model: ModelRef[ModelRefConfigT] | BackgroundModel | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    context: dict[str, object] | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> Operation[ModelResponse]:
    """Generate content using a long-running model, returning an Operation to poll.

    A background start is one request that returns a job handle. There is
    no tool loop and no output parsing on ``check_operation``, so tools,
    ``max_turns``, and the ``output_*`` options are not accepted here.

    Example:
        op = await ai.generate_operation(
            model='googleai/veo-3.1-generate-preview',
            prompt='A timelapse of a flower blooming.',
        )
        while not op.done:
            op = await ai.check_operation(op)
    """
    if isinstance(model, BackgroundModel):
        # Same as its name, once we know this registry holds that object.
        model = background_model_name(model=model, registry=self._registry)
    resolved = await resolve_for_generate(
        model=model,
        config=config,
        registry=self._registry,
        message='No model specified for generate_operation.',
    )
    check_call_config(config=config, schema=resolved.config_schema, model=resolved.name)

    model_action = await self._registry.resolve_model(resolved.name)
    if not model_action:
        raise GenkitError(
            status='NOT_FOUND',
            message=f"Model '{resolved.name}' not found.",
            reason=ErrorReason.MODEL_NOT_FOUND,
        )

    if model_action.kind != ActionKind.BACKGROUND_MODEL:
        raise GenkitError(
            status='INVALID_ARGUMENT',
            message=f"Model '{model_action.name}' does not support long running operations.",
            reason=ErrorReason.UNSUPPORTED_BY_MODEL,
        )

    # Call generate with already-resolved wire name + config.
    response = await self.generate(
        model=resolved.name,
        prompt=prompt,
        system=system,
        messages=messages,
        config=resolved.config,
        context=context,
        use=use,
        docs=docs,
    )

    if response.error is not None:
        # This call is "give me the ticket." A start that already
        # failed is not that ticket — while-not-done would poll it
        # as a live job.
        err = GenkitError(
            status=response.error.status or 'INTERNAL',
            message=response.error.message,
            details=response.error.details,
            reason=response.error.reason,
        )
        mark_already_sourced(err)
        raise err
    if not response.operation:
        raise missing_operation_error(name=model_action.name)
    return as_model_operation(response.operation, name=model_action.name, status='INTERNAL')

generate_stream(*, model=None, prompt=None, system=None, messages=None, tools=None, return_tool_requests=None, tool_choice=None, resume_respond=None, resume_restart=None, resume_metadata=None, config=None, max_turns=None, context=None, output_schema=None, output_format=None, output_content_type=None, output_instructions=None, output_constrained=None, use=None, docs=None)

generate_stream(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[OutputT],
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[OutputT]
generate_stream(
    *,
    model: ModelRef[Any] | Action | str | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelConfigDict,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]
generate_stream(
    *,
    model: (
        ModelRef[ModelRefConfigT] | Action | str | None
    ) = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: ModelRefConfigT | Mapping[str, Any] | None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: (
        type[Any] | dict[str, Any] | str | None
    ) = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None
) -> ModelStreamResponse[Any]

Stream generated text, returning a ModelStreamResponse with .stream and .response.

With output_schema=Recipe, each chunk.output is a partial of that type: same attributes, any field may still be None or a prefix. Guard the field you are about to use. The finished Recipe is only (await result.response).output, and it's None when the reply isn't a Recipe.

If the model fails partway through, the async for still ends normally. The final response has finish_reason == FAILED, error set, text == '', message is None, and messages ending at the last complete turn, so it's safe to send back. The chunks you already received are the record of what was shown.

Use async with result.stream as stream: so that leaving the loop early (break, an exception, a disconnected client) closes the stream and stops the model call.

Example
# 1. Start streaming
result = ai.generate_stream(prompt='Write a haiku about rain.')

# 2. Print chunks as they arrive; the context manager closes the stream
async with result.stream as stream:
    async for chunk in stream:
        print(chunk.text, end='')
print()
# => Soft rain on the roof...

# 3. Await the final response
final = await result.response
print(final.finish_reason)
# => stop
Source code in packages/genkit/src/genkit/_ai/_aio.py
2207
2208
2209
2210
2211
2212
2213
2214
2215
2216
2217
2218
2219
2220
2221
2222
2223
2224
2225
2226
2227
2228
2229
2230
2231
2232
2233
2234
2235
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
2253
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
2283
2284
2285
2286
2287
2288
2289
2290
2291
2292
2293
2294
2295
2296
2297
2298
2299
2300
2301
2302
def generate_stream(
    self,
    *,
    model: str | ModelRef[Any] | Action | None = None,
    prompt: str | list[Part] | None = None,
    system: str | list[Part] | None = None,
    messages: list[Message] | None = None,
    tools: Sequence[str | Tool] | None = None,
    return_tool_requests: bool | None = None,
    tool_choice: ToolChoice | None = None,
    resume_respond: Part | list[Part] | None = None,
    resume_restart: Part | list[Part] | None = None,
    resume_metadata: dict[str, Any] | None = None,
    config: BaseModel | ModelConfigDict | Mapping[str, Any] | None = None,
    max_turns: int | None = None,
    context: dict[str, object] | None = None,
    output_schema: type[Any] | dict[str, Any] | str | None = None,
    output_format: str | None = None,
    output_content_type: str | None = None,
    output_instructions: bool | str | None = None,
    output_constrained: bool | None = None,
    use: Sequence[Middleware] | None = None,
    docs: list[Document] | None = None,
) -> ModelStreamResponse[Any]:
    """Stream generated text, returning a ModelStreamResponse with .stream and .response.

    With ``output_schema=Recipe``, each ``chunk.output`` is a partial of
    that type: same attributes, any field may still be ``None`` or a
    prefix. Guard the field you are about to use. The finished
    ``Recipe`` is only ``(await result.response).output``, and it's ``None``
    when the reply isn't a ``Recipe``.

    If the model fails partway through, the ``async for`` still ends
    normally. The final response has ``finish_reason == FAILED``,
    ``error`` set, ``text == ''``, ``message is None``, and ``messages``
    ending at the last complete turn, so it's safe to send back. The
    chunks you already received are the record of what was shown.

    Use ``async with result.stream as stream:`` so that leaving the loop
    early (``break``, an exception, a disconnected client) closes the
    stream and stops the model call.

    Example:
        ```python
        # 1. Start streaming
        result = ai.generate_stream(prompt='Write a haiku about rain.')

        # 2. Print chunks as they arrive; the context manager closes the stream
        async with result.stream as stream:
            async for chunk in stream:
                print(chunk.text, end='')
        print()
        # => Soft rain on the roof...

        # 3. Await the final response
        final = await result.response
        print(final.finish_reason)
        # => stop
        ```
    """
    check_max_turns(max_turns)
    initial_msgs: list[Message] = []
    if not isinstance(messages, str):
        initial_msgs = call_messages(system=system, messages=messages, prompt=prompt)

    async def _run_generate(
        send_chunk: Callable[[ModelResponseChunk], None],
        caller_stopped: asyncio.Event,
    ) -> ModelResponse[Any]:
        return await self._generate(
            model=model,
            prompt=prompt,
            system=system,
            messages=messages,
            tools=tools,
            return_tool_requests=return_tool_requests,
            tool_choice=tool_choice,
            resume_respond=resume_respond,
            resume_restart=resume_restart,
            resume_metadata=resume_metadata,
            config=config,
            max_turns=max_turns,
            context=context,
            output_schema=output_schema,
            output_format=output_format,
            output_content_type=output_content_type,
            output_instructions=output_instructions,
            output_constrained=output_constrained,
            use=use,
            docs=docs,
            on_chunk=send_chunk,
            caller_stopped=caller_stopped,
        )

    stream, task = start_generate_stream(initial_messages=initial_msgs, run=_run_generate)
    return ModelStreamResponse[Any](stream=stream, response=task)

lookup_model(name) async

Return the model action registered under name, or None.

Plugin models that haven't been used yet are resolved through the plugin, so 'googleai/gemini-flash-latest' works before any generate call. Background models aren't included; they run through generate_operation.

Source code in packages/genkit/src/genkit/_ai/_aio.py
904
905
906
907
908
909
910
911
912
913
async def lookup_model(self, name: str) -> Action[ModelRequest, ModelResponse, ModelResponseChunk] | None:
    """Return the model action registered under ``name``, or None.

    Plugin models that haven't been used yet are resolved through the
    plugin, so ``'googleai/gemini-flash-latest'`` works before any
    generate call. Background models aren't included; they run through
    ``generate_operation``.
    """
    action = await self._registry.resolve_action(ActionKind.MODEL, name)
    return cast(Action[ModelRequest, ModelResponse, ModelResponseChunk], action) if action is not None else None

lookup_tool(name) async

Return the tool registered under name, or None.

The same handle @ai.tool returns, so a tool defined in one module can be called or passed in tools=[...] from another without importing it.

Example
# 1. Define a tool in one module
@ai.tool
async def menu_price(dish: str) -> float:
    return 14.5


# 2. Find it by name somewhere else
price_tool = await ai.lookup_tool('menu_price')
response = await ai.generate(prompt='How much is the ramen?', tools=[price_tool])
print(response.text)
# => The ramen is $14.50.
Source code in packages/genkit/src/genkit/_ai/_aio.py
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
async def lookup_tool(self, name: str) -> Tool | None:
    """Return the tool registered under ``name``, or None.

    The same handle ``@ai.tool`` returns, so a tool defined in one module
    can be called or passed in ``tools=[...]`` from another without
    importing it.

    Example:
        ```python
        # 1. Define a tool in one module
        @ai.tool
        async def menu_price(dish: str) -> float:
            return 14.5


        # 2. Find it by name somewhere else
        price_tool = await ai.lookup_tool('menu_price')
        response = await ai.generate(prompt='How much is the ramen?', tools=[price_tool])
        print(response.text)
        # => The ramen is $14.50.
        ```
    """
    action = await self._registry.resolve_action(ActionKind.TOOL, name)
    if action is None:
        return None
    return Tool.from_action(action)

lookup_value(*, kind, name)

Return the value defined under kind and name, or None.

Source code in packages/genkit/src/genkit/_ai/_aio.py
942
943
944
def lookup_value(self, *, kind: str, name: str) -> object | None:
    """Return the value defined under ``kind`` and ``name``, or None."""
    return self._registry.lookup_value(kind, name)

middleware(cls=None, *, name=None, description=None)

middleware(cls: type[MiddlewareT]) -> type[MiddlewareT]
middleware(
    *,
    name: str | None = None,
    description: str | None = None
) -> Callable[[type[MiddlewareT]], type[MiddlewareT]]

Decorator that registers a custom middleware on this app's registry.

Source code in packages/genkit/src/genkit/_ai/_aio.py
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
def middleware(
    self,
    cls: type[MiddlewareT] | None = None,
    *,
    name: str | None = None,
    description: str | None = None,
) -> type[MiddlewareT] | Callable[[type[MiddlewareT]], type[MiddlewareT]]:
    """Decorator that registers a custom middleware on this app's registry."""

    def decorator(target: type[MiddlewareT]) -> type[MiddlewareT]:
        return self.define_middleware(target, name=name, description=description)

    if cls is not None:
        return decorator(cls)
    return decorator

prompt(name, *, variant=None, input_schema=None, output_schema=None)

prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: None = None,
    output_schema: None = None
) -> Prompt[Any, Any]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT],
    output_schema: None = None
) -> Prompt[InputT, Any]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: None = None,
    output_schema: type[OutputT]
) -> Prompt[Any, OutputT]
prompt(
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT],
    output_schema: type[OutputT]
) -> Prompt[InputT, OutputT]

Look up a prompt by name and optional variant.

Source code in packages/genkit/src/genkit/_ai/_aio.py
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
def prompt(
    self,
    name: str,
    *,
    variant: str | None = None,
    input_schema: type[InputT] | None = None,
    output_schema: type[OutputT] | None = None,
) -> Prompt[InputT, OutputT] | Prompt[Any, Any]:
    """Look up a prompt by name and optional variant."""
    return Prompt(
        self,
        name=name,
        variant=variant,
        input_schema=input_schema,
        output_schema=output_schema,
    )

run(name, fn, *, metadata=None) async

Run a function as a discrete traced step within a flow.

fn takes no arguments and returns an awaitable, so async def functions, lambda: fetch(i), and callables with an async def __call__ all work. Same shape as JS ai.run('step', fn).

Example
# 1. Each fan-out step gets its own span in the trace
menus = await asyncio.gather(*[ai.run(f'fetch-{i}', lambda i=i: fetch_menu(i)) for i in range(3)])

# 2. Keyword form still works
total = await ai.run(name='sum', fn=lambda: sum_prices(menus))
Source code in packages/genkit/src/genkit/_ai/_aio.py
2601
2602
2603
2604
2605
2606
2607
2608
2609
2610
2611
2612
2613
2614
2615
2616
2617
2618
2619
2620
2621
2622
2623
2624
2625
2626
2627
2628
2629
2630
2631
2632
2633
2634
2635
2636
2637
2638
2639
async def run(
    self,
    name: str,
    fn: Callable[[], Awaitable[T]],
    *,
    metadata: dict[str, Any] | None = None,
) -> T:
    """Run a function as a discrete traced step within a flow.

    ``fn`` takes no arguments and returns an awaitable, so ``async def``
    functions, ``lambda: fetch(i)``, and callables with an ``async def
    __call__`` all work. Same shape as JS ``ai.run('step', fn)``.

    Example:
        ```python
        # 1. Each fan-out step gets its own span in the trace
        menus = await asyncio.gather(*[ai.run(f'fetch-{i}', lambda i=i: fetch_menu(i)) for i in range(3)])

        # 2. Keyword form still works
        total = await ai.run(name='sum', fn=lambda: sum_prices(menus))
        ```
    """
    if not callable(fn):
        raise TypeError(f'fn must be callable, got {type(fn).__name__}')
    not_awaitable = (
        'fn must return an awaitable: pass an async def, a lambda returning a coroutine, '
        'or wrap blocking work in asyncio.to_thread'
    )

    async def body(_span: object) -> T:
        result = fn()
        if not inspect.isawaitable(result):
            # Steps stay async like tools and flows; blocking work goes
            # through asyncio.to_thread.
            raise TypeError(not_awaitable)
        return await result

    attributes = {metadata_key(k): str(v) for k, v in (metadata or {}).items()}
    return await run_in_new_span(name, body, action_type='flowStep', attributes=attributes)

run_main(coro)

Run your main coroutine and return its result, like asyncio.run.

With reflection on (GENKIT_ENV=dev, which genkit start sets, or GENKIT_REFLECTION_ENABLED=true), it keeps the process alive after main returns, so the Dev UI can keep running your flows, until Ctrl+C, SIGTERM, or the reflection server stops on its own. With reflection off, it returns as soon as main does.

If main raises while reflection is on, the error is logged and the Dev UI stays up. The error is raised once the process stops. Ctrl+C after a successful main raises KeyboardInterrupt, and SIGTERM returns main's result.

Example
from genkit import Genkit
from genkit_google_genai import GoogleAI

# 1. Initialize Genkit and define a flow
ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))


@ai.flow
async def suggest_dish(cuisine: str) -> str:
    response = await ai.generate(prompt=f'Suggest one {cuisine} dish.')
    return response.text


# 2. Run a quick check from your script's entry point
async def main() -> None:
    print(await suggest_dish('Thai'))


# 3. Start it
ai.run_main(main())
# => Green curry with chicken
#    `python main.py` exits here. Under `genkit start`, the process
#    stays up for the Dev UI until you press Ctrl+C.
Source code in packages/genkit/src/genkit/_ai/_aio.py
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
def run_main(self, coro: Coroutine[Any, Any, T]) -> T:
    """Run your ``main`` coroutine and return its result, like ``asyncio.run``.

    With reflection on (``GENKIT_ENV=dev``, which ``genkit start`` sets, or
    ``GENKIT_REFLECTION_ENABLED=true``), it keeps the process alive after
    ``main`` returns, so the Dev UI can keep running your flows, until
    Ctrl+C, SIGTERM, or the reflection server stops on its own. With
    reflection off, it returns as soon as ``main`` does.

    If ``main`` raises while reflection is on, the error is logged and the
    Dev UI stays up. The error is raised once the process stops. Ctrl+C
    after a successful ``main`` raises ``KeyboardInterrupt``, and SIGTERM
    returns ``main``'s result.

    Example:
        ```python
        from genkit import Genkit
        from genkit_google_genai import GoogleAI

        # 1. Initialize Genkit and define a flow
        ai = Genkit(plugins=[GoogleAI()], model=GoogleAI.gemini('gemini-flash-latest'))


        @ai.flow
        async def suggest_dish(cuisine: str) -> str:
            response = await ai.generate(prompt=f'Suggest one {cuisine} dish.')
            return response.text


        # 2. Run a quick check from your script's entry point
        async def main() -> None:
            print(await suggest_dish('Thai'))


        # 3. Start it
        ai.run_main(main())
        # => Green curry with chicken
        #    `python main.py` exits here. Under `genkit start`, the process
        #    stays up for the Dev UI until you press Ctrl+C.
        ```
    """
    try:
        asyncio.get_running_loop()
    except RuntimeError:
        pass
    else:
        # Jupyter, IPython, and async frameworks already run a loop, and
        # asyncio.run would fail with a raw RuntimeError plus an
        # unawaited-coroutine warning.
        coro.close()
        raise RuntimeError(
            'ai.run_main() cannot be called from a running event loop (Jupyter, IPython, or an async '
            'framework). Use `await main()` instead.'
        )
    if not self._reflection_config.enabled:
        return run_loop(coro)

    user_error: Exception | None = None
    stop_signal: signal.Signals | None = None

    async def reflection_runner() -> T | None:
        nonlocal user_error, stop_signal
        user_result: T | None = None
        try:
            user_result = await coro
            logger.debug('User coroutine completed successfully.')
        except Exception as e:
            # Script entrypoint failed — there's no Dev UI panel for this run,
            # so keep a headline + a debug traceback.
            logger.error('Startup failed: %s: %s', type(e).__name__, e)
            logger.debug('Startup failure details', exc_info=True)
            user_error = e

        # Block until Ctrl+C, SIGTERM, or the reflection server stops,
        # keeping the daemon reflection thread alive. The receiver is open
        # before the ready line, so a signal sent once it prints is ours,
        # not asyncio's default SIGINT handling.
        try:
            with anyio.open_signal_receiver(signal.SIGINT, signal.SIGTERM) as sigs:
                logger.info(self._reflection_ready_message())
                async with anyio.create_task_group() as tg:

                    async def _handle_signal(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                        nonlocal stop_signal
                        async for sig in sigs:
                            stop_signal = sig
                            tg_.cancel_scope.cancel()
                            return

                    async def _handle_reflection_stopped(tg_: anyio.abc.TaskGroup) -> None:  # type: ignore[name-defined]
                        # Poll rather than park a worker thread in Event.wait:
                        # anyio worker threads are non-daemon, so a parked one
                        # keeps the process alive after run_main returns.
                        while not self._reflection_stopped.is_set():  # noqa: ASYNC110 - threading.Event, set off-loop
                            await anyio.sleep(0.25)
                        logger.warning('Reflection server stopped; returning from run_main.')
                        tg_.cancel_scope.cancel()

                    tg.start_soon(_handle_signal, tg)
                    tg.start_soon(_handle_reflection_stopped, tg)
                    await anyio.sleep_forever()
        except anyio.get_cancelled_exc_class():
            pass

        logger.debug('Reflection server stopped.')
        return user_result

    # Decide out here, after the loop has shut down cleanly, so neither the
    # coroutine's error nor KeyboardInterrupt is raised during asyncio shutdown.
    try:
        result = anyio.run(reflection_runner)
    except KeyboardInterrupt:
        # Ctrl+C before the receiver opened (main still running).
        if user_error is None:
            raise
        raise user_error from None
    if user_error is not None:
        raise user_error
    if stop_signal == signal.SIGINT:
        raise KeyboardInterrupt
    # main returned normally (user_error is None), so result holds its value.
    return cast(T, result)

tool(name=None, *, description=None, input_schema=None)

tool(
    name: str | None = None,
    *,
    description: str | None = None,
    input_schema: (
        type[BaseModel] | dict[str, object] | None
    ) = None
) -> _ToolDecorator
tool(
    func: Callable[
        [ToolContext[ChunkT], object], Awaitable[OutputT]
    ],
) -> Tool[Any, OutputT, ChunkT]
tool(
    func: DefaultInputCtxFn[
        ToolContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedTool[InputT, OutputT, ChunkT]
tool(
    func: Callable[
        [InputT, ToolContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Tool[InputT, OutputT, ChunkT]
tool(
    func: CtxDefaultInputFn[
        ToolContext[ChunkT], InputT, OutputT
    ],
) -> DefaultedTool[InputT, OutputT, ChunkT]
tool(
    func: Callable[
        [ToolContext[ChunkT], InputT], Awaitable[OutputT]
    ],
) -> Tool[InputT, OutputT, ChunkT]
tool(
    func: Callable[[object], Awaitable[OutputT]],
) -> Tool[Any, OutputT]
tool(
    func: Callable[
        [ToolContext[ChunkT]], Awaitable[OutputT]
    ],
) -> Tool[None, OutputT, ChunkT]
tool(
    func: DefaultInputFn[InputT, OutputT],
) -> DefaultedTool[InputT, OutputT]
tool(
    func: Callable[[InputT], Awaitable[OutputT]],
) -> Tool[InputT, OutputT]
tool(
    func: Callable[[], Awaitable[OutputT]],
) -> Tool[None, OutputT]

Decorator to register a function as a tool.

Can be used bare (@ai.tool) or with arguments (@ai.tool(), @ai.tool('custom_name', description='...')).

The return annotation is what the model binds as outputSchema. Awaiting the tool directly returns what the function returned.

A tool takes at most one input, and that input's type is the schema the model fills in. For several fields, use one Pydantic model. To read the request context or interrupt, add a parameter annotated ToolContext, in any position. Any other second parameter raises TypeError when the tool is defined.

Example

@ai.tool async def current_weather(city: str) -> str: return f'Sunny in {city}'

class Forecast(BaseModel): city: str days: int = 3

@ai.tool async def forecast(input: Forecast, ctx: ToolContext) -> str: user = ctx.context.get('user_id') return f'{input.days}-day forecast for {input.city} ({user})'

res = await ai.generate(prompt='Weather in Paris?', tools=['current_weather', 'forecast'])

Source code in packages/genkit/src/genkit/_ai/_aio.py
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
def tool(
    self,
    name: str | Callable[..., Awaitable[Any]] | None = None,
    *,
    description: str | None = None,
    input_schema: type[BaseModel] | dict[str, object] | None = None,
) -> _ToolDecorator | Tool[Any, Any, Any]:
    """Decorator to register a function as a tool.

    Can be used bare (``@ai.tool``) or with arguments (``@ai.tool()``,
    ``@ai.tool('custom_name', description='...')``).

    The return annotation is what the model binds as ``outputSchema``.
    Awaiting the tool directly returns what the function returned.

    A tool takes at most one input, and that input's type is the schema the
    model fills in. For several fields, use one Pydantic model. To read the
    request context or interrupt, add a parameter annotated
    ``ToolContext``, in any position. Any other second parameter raises
    ``TypeError`` when the tool is defined.

    Example:
        @ai.tool
        async def current_weather(city: str) -> str:
            return f'Sunny in {city}'

        class Forecast(BaseModel):
            city: str
            days: int = 3

        @ai.tool
        async def forecast(input: Forecast, ctx: ToolContext) -> str:
            user = ctx.context.get('user_id')
            return f'{input.days}-day forecast for {input.city} ({user})'

        res = await ai.generate(prompt='Weather in Paris?', tools=['current_weather', 'forecast'])
    """
    if not isinstance(name, str) and name is not None:
        return _ToolDecorator(self._registry, None, description, input_schema)(name)
    return _ToolDecorator(self._registry, name, description, input_schema)

current_session()

Return the active agent session, or None if not inside a session.

Source code in packages/genkit/src/genkit/exp/_api.py
44
45
46
def current_session() -> SessionLike | None:
    """Return the active agent session, or None if not inside a session."""
    return get_current_session()

genkit.exp.agent

Agent types. Experimental — import the instance from genkit.exp.

from genkit.exp import Genkit
from genkit.exp.agent import InMemorySessionStore
from genkit_google_genai import GoogleAI

ai = Genkit(plugins=[GoogleAI()])
agent = ai.define_agent(
    name='weatherAgent',
    model=GoogleAI.gemini('gemini-flash-latest'),
    system='Weather assistant.',
    store=InMemorySessionStore(),
)

AgentFn = Callable[[SessionRunner, AgentContext], Awaitable[AgentResult]] module-attribute

Custom agent entrypoint: takes a SessionRunner and the run context, returns an AgentResult.

ChunkTransform = Callable[[AgentStreamChunk], AgentStreamChunk | None] module-attribute

Reshapes a stream chunk before a client sees it; returning None drops the chunk.

SaveFn = Callable[[SessionSnapshot | None], SessionSnapshot | None] module-attribute

Synchronous save mutator: gets a copy of the stored snapshot (or None), returns the new one or None to skip.

StateT = TypeVarExt('StateT', bound=BaseModel, default=Any) module-attribute

Type of a session's custom state: a Pydantic model, or Any for schemaless sessions.

StateTransform = Callable[[SessionState], SessionState] module-attribute

Redacts session state before a client sees it; must return a state, never None.

TERMINAL_STATUSES = frozenset({SnapshotStatus.COMPLETED, SnapshotStatus.FAILED, SnapshotStatus.ABORTED}) module-attribute

Final snapshot statuses: a store rejects any later status change, and status streams end after one.

Agent

Bases: genkit._core._action.BidiAction[genkit._core._model.AgentInput, genkit._core._model.AgentOutput, genkit._core._model.AgentStreamChunk, genkit._core._model.AgentInit], genkit._ai._agents._client.AgentClient[genkit._ai._agents._session.StateT], typing.Generic[genkit._ai._agents._session.StateT]

The low-level agent primitive: a BidiAction that lives in the registry.

Created by define_agent / define_custom_agent. As a BidiAction it's the thing that gets registered and served over HTTP. It's also an AgentClient, so the ergonomic chat surface (chat/load_chat/ get_snapshot/abort) is inherited rather than reimplemented — it's the same client used for remote agents, just pointed at an in-process transport. So talking to a local agent and a remote one go through one client, not two.

The action generics are pinned to the agent turn shape: each turn's input is an AgentInput, streamed chunks are AgentStreamChunk, the turn result is an AgentOutput, and init (session identity) is an AgentInit.

Source code in packages/genkit/src/genkit/_ai/_agents/_base.py
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
class Agent(
    BidiAction[AgentInput, AgentOutput, AgentStreamChunk, AgentInit],
    AgentClient[StateT],
    Generic[StateT],
):
    """The low-level agent primitive: a BidiAction that lives in the registry.

    Created by ``define_agent`` / ``define_custom_agent``. As a BidiAction it's
    the thing that gets registered and served over HTTP. It's *also* an
    ``AgentClient``, so the ergonomic chat surface (``chat``/``load_chat``/
    ``get_snapshot``/``abort``) is inherited rather than reimplemented — it's the
    same client used for remote agents, just pointed at an in-process transport.
    So talking to a local agent and a remote one go through one client, not two.

    The action generics are pinned to the agent turn shape: each turn's input is
    an ``AgentInput``, streamed chunks are ``AgentStreamChunk``, the turn result
    is an ``AgentOutput``, and ``init`` (session identity) is an ``AgentInit``.
    """

    def __init__(
        self,
        *,
        name: str,
        bidi_fn: BidiFn[AgentInit, AgentInput, AgentStreamChunk, AgentOutput],
        store: SessionStore | None = None,
        state_transform: StateTransform | None = None,
        state_schema: type[StateT] | None = None,
        description: str | None = None,
        metadata: dict[str, object] | None = None,
    ) -> None:
        """Initialise Agent; transport is inferred from the action + store."""
        agent_meta: dict[str, object] = {'stateManagement': 'server' if store is not None else 'client'}
        # Publish the state shape so tooling (e.g. the Dev UI) can inspect and
        # validate custom state the same way it does tool/prompt schemas. StateT is
        # bound to BaseModel, so a non-Pydantic schema is a type error at the call
        # site — nothing to shape-check at runtime here.
        if state_schema is not None:
            agent_meta['stateSchema'] = state_schema.model_json_schema()
        # BidiAction is inited via super() (not an explicit BidiAction.__init__)
        # so the type checker keeps Agent's bound generics; calling it explicitly
        # makes it re-infer them and the invariant ChunkT collapses to Never. The
        # AgentClient half is inited explicitly just below.
        super().__init__(
            kind=ActionKind.AGENT,
            name=name,
            bidi_fn=bidi_fn,
            description=description,
            # 'agent' is framework-owned metadata (state management + schema), so
            # it always wins over anything the caller put under that key.
            metadata={**(metadata or {}), 'agent': agent_meta},
            # An agent turn always resumes (or starts) a session, so its init is
            # always an AgentInit. Declaring it here validates the session
            # identity up front and lets a bare run() default to a fresh session.
            init_schema=AgentInit,
            # Each turn's input is an AgentInput. Declaring it means a raw payload
            # (e.g. an HTTP JSON body) is coerced into an AgentInput before the
            # turn runs, instead of reaching the runtime as a bare dict.
            input_schema=AgentInput,
        )
        self.store = store
        self._state_transform = state_transform
        # The AgentClient half (chat/load_chat/get_snapshot/abort rides along)
        # runs against an in-process transport that drives this very action — the
        # way remote_agent runs against an HTTP one.
        AgentClient.__init__(self, self._in_process_transport(), state_schema=state_schema)

    def _in_process_transport(self) -> InProcessTransport:
        # Agent satisfies AgentAction (stream_bidi + get/abort_snapshot_data), so
        # the transport drives it directly. With no store the snapshot methods
        # just return None, so there's nothing to special-case here.
        state_management: StateManagement = 'server' if self.store is not None else 'client'
        return InProcessTransport(action=self, state_management=state_management)

    async def get_snapshot_data(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> SessionSnapshot | None:
        """Read a stored snapshot without starting a session.

        Pass exactly one of ``snapshot_id`` or ``session_id``. A session
        lookup returns the newest row even when that turn failed or was
        aborted. ``chat(session_id=)`` is how you continue from the last
        good turn.
        """
        if self.store is None:
            return None
        return await resolve_snapshot(
            store=self.store,
            snapshot_id=snapshot_id,
            session_id=session_id,
            state_transform=self._state_transform,
            context=get_current_context(),
        )

    async def abort_snapshot_data(self, snapshot_id: str) -> SnapshotStatus | None:
        """Abort a running snapshot.

        The return is the snapshot's status from *before* this call, not after.
        ``pending`` means the turn was still running and this call cancelled it
        (the row is now ``aborted``). A terminal status means the turn had
        already finished — this call did not rewrite it. ``None`` means
        nothing was observed (no store, no row, or the store never ran the
        abort write). This Python server always returns the previous status.
        """
        if self.store is None:
            return None
        return await abort_snapshot_in_store(
            store=self.store,
            snapshot_id=snapshot_id,
            context=get_current_context(),
        )

config_schema property

The config class set at definition time, from config_schema= or the fn annotation.

input_class property

The action's input annotation as a concrete class, when it is one.

params property

The function's input and context parameters, as Genkit passes them.

__call__(input=NO_INPUT, *, context=None) async

__call__(
    input: None = None,
    *,
    context: dict[str, Any] | None = None
) -> OutputT
__call__(
    input: InputT, *, context: dict[str, Any] | None = None
) -> OutputT

Call the action directly, returning just the response value.

Source code in packages/genkit/src/genkit/_core/_action.py
1350
1351
1352
1353
1354
1355
1356
1357
async def __call__(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
) -> OutputT:
    """Call the action directly, returning just the response value."""
    return (await self._run(input, context=context)).response

__init__(*, name, bidi_fn, store=None, state_transform=None, state_schema=None, description=None, metadata=None)

Initialise Agent; transport is inferred from the action + store.

Source code in packages/genkit/src/genkit/_ai/_agents/_base.py
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
def __init__(
    self,
    *,
    name: str,
    bidi_fn: BidiFn[AgentInit, AgentInput, AgentStreamChunk, AgentOutput],
    store: SessionStore | None = None,
    state_transform: StateTransform | None = None,
    state_schema: type[StateT] | None = None,
    description: str | None = None,
    metadata: dict[str, object] | None = None,
) -> None:
    """Initialise Agent; transport is inferred from the action + store."""
    agent_meta: dict[str, object] = {'stateManagement': 'server' if store is not None else 'client'}
    # Publish the state shape so tooling (e.g. the Dev UI) can inspect and
    # validate custom state the same way it does tool/prompt schemas. StateT is
    # bound to BaseModel, so a non-Pydantic schema is a type error at the call
    # site — nothing to shape-check at runtime here.
    if state_schema is not None:
        agent_meta['stateSchema'] = state_schema.model_json_schema()
    # BidiAction is inited via super() (not an explicit BidiAction.__init__)
    # so the type checker keeps Agent's bound generics; calling it explicitly
    # makes it re-infer them and the invariant ChunkT collapses to Never. The
    # AgentClient half is inited explicitly just below.
    super().__init__(
        kind=ActionKind.AGENT,
        name=name,
        bidi_fn=bidi_fn,
        description=description,
        # 'agent' is framework-owned metadata (state management + schema), so
        # it always wins over anything the caller put under that key.
        metadata={**(metadata or {}), 'agent': agent_meta},
        # An agent turn always resumes (or starts) a session, so its init is
        # always an AgentInit. Declaring it here validates the session
        # identity up front and lets a bare run() default to a fresh session.
        init_schema=AgentInit,
        # Each turn's input is an AgentInput. Declaring it means a raw payload
        # (e.g. an HTTP JSON body) is coerced into an AgentInput before the
        # turn runs, instead of reaching the runtime as a bare dict.
        input_schema=AgentInput,
    )
    self.store = store
    self._state_transform = state_transform
    # The AgentClient half (chat/load_chat/get_snapshot/abort rides along)
    # runs against an in-process transport that drives this very action — the
    # way remote_agent runs against an HTTP one.
    AgentClient.__init__(self, self._in_process_transport(), state_schema=state_schema)

abort(snapshot_id) async

Aborts a running snapshot on the server.

The return is the snapshot's status from before this call, not after. pending means the turn was still running and this call cancelled it (the row is now aborted). A terminal status (completed, failed, aborted) means the turn had already finished — this call did not rewrite it. None means nothing was observed (no row, or the store never ran the abort write).

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
691
692
693
694
695
696
697
698
699
700
701
async def abort(self, snapshot_id: str) -> SnapshotStatus | None:
    """Aborts a running snapshot on the server.

    The return is the snapshot's status from *before* this call, not after.
    ``pending`` means the turn was still running and this call cancelled it
    (the row is now ``aborted``). A terminal status (``completed``,
    ``failed``, ``aborted``) means the turn had already finished — this
    call did not rewrite it. ``None`` means nothing was observed (no row,
    or the store never ran the abort write).
    """
    return await self._transport.abort_snapshot(snapshot_id)

abort_snapshot_data(snapshot_id) async

Abort a running snapshot.

The return is the snapshot's status from before this call, not after. pending means the turn was still running and this call cancelled it (the row is now aborted). A terminal status means the turn had already finished — this call did not rewrite it. None means nothing was observed (no store, no row, or the store never ran the abort write). This Python server always returns the previous status.

Source code in packages/genkit/src/genkit/_ai/_agents/_base.py
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
async def abort_snapshot_data(self, snapshot_id: str) -> SnapshotStatus | None:
    """Abort a running snapshot.

    The return is the snapshot's status from *before* this call, not after.
    ``pending`` means the turn was still running and this call cancelled it
    (the row is now ``aborted``). A terminal status means the turn had
    already finished — this call did not rewrite it. ``None`` means
    nothing was observed (no store, no row, or the store never ran the
    abort write). This Python server always returns the previous status.
    """
    if self.store is None:
        return None
    return await abort_snapshot_in_store(
        store=self.store,
        snapshot_id=snapshot_id,
        context=get_current_context(),
    )

action_fn(input, ctx) async

Adapt the bidi fn to the plain Action fn shape.

The bidi fn reads its per-turn inputs from an async stream and emits chunks through a callback — the same pair a plain action fn gets on its ctx. A live chat supplies ctx._input_stream; a one-shot run has just the single input, which we hand over as a one-item stream. init (session identity) rides the run's init channel, separate from inputs.

Source code in packages/genkit/src/genkit/_core/_action.py
2236
2237
2238
2239
2240
2241
2242
2243
2244
2245
2246
2247
2248
2249
2250
2251
2252
async def action_fn(self, input: InputT, ctx: ActionContext) -> OutputT:  # noqa: A002
    """Adapt the bidi fn to the plain Action fn shape.

    The bidi fn reads its per-turn inputs from an async stream and emits
    chunks through a callback — the same pair a plain action fn gets on its
    ctx. A live chat supplies ``ctx._input_stream``; a one-shot run has just
    the single ``input``, which we hand over as a one-item stream. init
    (session identity) rides the run's init channel, separate from inputs.
    """
    if ctx._input_stream is not None:
        # ctx carries the stream as AsyncIterator[object]; here we know it's
        # this action's InputT. (ty collapses InputT to object and sees this
        # as redundant; pyright needs it.)
        input_stream = cast('AsyncIterator[InputT]', ctx._input_stream)  # ty: ignore[redundant-cast]
    else:
        input_stream = single_item_stream(input)
    return await self.bidi_fn(cast(InitT, ctx._init), input_stream, ctx.send_chunk)

chat(*, snapshot_id=None, session_id=None, messages=None, artifacts=None, state=None)

Starts a new session, or resumes one.

Store-backed agents take snapshot_id and/or session_id. snapshot_id resumes that exact row (it must be completed). session_id continues the conversation: skip a failed / aborted / pending leaf, or start fresh if there isn't a completed turn yet. Passing both is fine: the snapshot picks the row, the session id checks it belongs to that session.

messages / artifacts / state are only for client-managed agents (no store). Mixing those with a resume id, or sending a state blob to a store-backed agent, raises :class:AgentInitError.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
def chat(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
    messages: list[Message] | None = None,
    artifacts: list[Artifact] | None = None,
    state: StateT | None = None,
) -> AgentChat[StateT]:
    """Starts a new session, or resumes one.

    Store-backed agents take ``snapshot_id`` and/or ``session_id``.
    ``snapshot_id`` resumes that exact row (it must be completed).
    ``session_id`` continues the conversation: skip a failed / aborted /
    pending leaf, or start fresh if there isn't a completed turn yet.
    Passing both is fine: the snapshot picks the row, the session id
    checks it belongs to that session.

    ``messages`` / ``artifacts`` / ``state`` are only for client-managed
    agents (no store). Mixing those with a resume id, or sending a state
    blob to a store-backed agent, raises :class:`AgentInitError`.
    """
    session_transport = copy.copy(self._transport)
    return AgentChat(
        session_transport,
        init_from(
            snapshot_id=snapshot_id,
            session_id=session_id,
            messages=messages,
            artifacts=artifacts,
            state=state,
        ),
        state_schema=self._state_schema,
    )

get_snapshot(*, snapshot_id=None, session_id=None) async

Reads a stored snapshot without starting a session.

Pass exactly one of snapshot_id or session_id. A session lookup returns the newest row even when that turn failed or was aborted. chat(session_id=) is how you continue from the last good turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
676
677
678
679
680
681
682
683
684
685
686
687
688
689
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> SessionSnapshotVeneer | None:
    """Reads a stored snapshot without starting a session.

    Pass exactly one of ``snapshot_id`` or ``session_id``. A session
    lookup returns the newest row even when that turn failed or was
    aborted. ``chat(session_id=)`` is how you continue from the last
    good turn.
    """
    return await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)

get_snapshot_data(*, snapshot_id=None, session_id=None) async

Read a stored snapshot without starting a session.

Pass exactly one of snapshot_id or session_id. A session lookup returns the newest row even when that turn failed or was aborted. chat(session_id=) is how you continue from the last good turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_base.py
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
async def get_snapshot_data(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> SessionSnapshot | None:
    """Read a stored snapshot without starting a session.

    Pass exactly one of ``snapshot_id`` or ``session_id``. A session
    lookup returns the newest row even when that turn failed or was
    aborted. ``chat(session_id=)`` is how you continue from the last
    good turn.
    """
    if self.store is None:
        return None
    return await resolve_snapshot(
        store=self.store,
        snapshot_id=snapshot_id,
        session_id=session_id,
        state_transform=self._state_transform,
        context=get_current_context(),
    )

load_chat(*, snapshot_id=None, session_id=None) async

Loads a stored snapshot onto a new chat.

Pass exactly one of snapshot_id or session_id. The chat is pointed at that row as stored — including a failed, aborted, or still-pending turn. send() resumes that row, so a non-completed leaf is rejected. To continue the conversation, use chat(session_id=).

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
async def load_chat(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> AgentChat[StateT]:
    """Loads a stored snapshot onto a new chat.

    Pass exactly one of ``snapshot_id`` or ``session_id``. The chat is
    pointed at that row as stored — including a failed, aborted, or
    still-pending turn. ``send()`` resumes that row, so a non-completed
    leaf is rejected. To continue the conversation, use ``chat(session_id=)``.
    """
    snapshot = await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)
    if snapshot is None:
        raise GenkitError(
            status='NOT_FOUND',
            message=f'Snapshot {lookup_label(snapshot_id=snapshot_id, session_id=session_id)!r} not found.',
            reason=ErrorReason.SNAPSHOT_NOT_FOUND,
        )
    session_transport = copy.copy(self._transport)
    session_transport.state_management = 'server'
    chat = AgentChat(session_transport, state_schema=self._state_schema)
    chat._load_from_snapshot(snapshot)
    return chat

run(input=NO_INPUT, *, on_chunk=None, context=None, telemetry_labels=None, init=None) async

run(
    input: None = None,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]
run(
    input: InputT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> ActionResponse[OutputT]

Run the action and return its result with trace ids.

Parameters:

Name Type Description Default
input genkit._core._action.InputT | None

The input, validated against the input schema. Required unless the action takes no input or its function gives the input a default; omit it to use that default. On a flow or tool, an explicit None is a value and is validated like any other.

genkit._core._action.NO_INPUT
on_chunk collections.abc.Callable[[genkit._core._action.ChunkT], None] | None

Called with each chunk the action streams.

None
context dict[str, typing.Any] | None

Request context (auth, headers, ...), read as ctx.context.

None
telemetry_labels dict[str, object] | None

Custom labels set as span attributes.

None
init genkit._core._action.InitT | None

Session init value for a bidi action (e.g. a served agent's session identity). Validated against the init schema; plain actions ignore it.

None

Returns:

Type Description
genkit._core._action.ActionResponse[genkit._core._action.OutputT]

ActionResponse with the result, trace id and span id.

Raises:

Type Description
genkit._core._error.GenkitError

If input validation fails (INVALID_ARGUMENT status).

Source code in packages/genkit/src/genkit/_core/_action.py
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
async def run(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    on_chunk: Callable[[ChunkT], None] | None = None,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> ActionResponse[OutputT]:
    """Run the action and return its result with trace ids.

    Args:
        input: The input, validated against the input schema. Required
            unless the action takes no input or its function gives the
            input a default; omit it to use that default. On a flow or
            tool, an explicit None is a value and is validated like any
            other.
        on_chunk: Called with each chunk the action streams.
        context: Request context (auth, headers, ...), read as ``ctx.context``.
        telemetry_labels: Custom labels set as span attributes.
        init: Session init value for a bidi action (e.g. a served agent's
            session identity). Validated against the init schema; plain
            actions ignore it.

    Returns:
        ActionResponse with the result, trace id and span id.

    Raises:
        GenkitError: If input validation fails (INVALID_ARGUMENT status).
    """
    return await self._run(
        input,
        on_chunk=on_chunk,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream(input=NO_INPUT, *, context=None, telemetry_labels=None, init=None)

stream(
    input: None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]
stream(
    input: InputT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None
) -> StreamResponse[ChunkT, OutputT]

Return a StreamResponse: iterate .stream for chunks, await .response for the result.

Takes the same keyword arguments as run, minus on_chunk. If the action raises, both the loop and .response raise.

Source code in packages/genkit/src/genkit/_core/_action.py
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
def stream(
    self: Action[Any, OutputT, ChunkT, InitT],
    input: InputT | None = NO_INPUT,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
    init: InitT | None = None,
) -> StreamResponse[ChunkT, OutputT]:
    """Return a ``StreamResponse``: iterate ``.stream`` for chunks, await ``.response`` for the result.

    Takes the same keyword arguments as ``run``, minus ``on_chunk``. If the
    action raises, both the loop and ``.response`` raise.
    """
    return self._stream(
        input,
        context=context,
        telemetry_labels=telemetry_labels,
        init=init,
    )

stream_bidi(init=None, *, context=None, telemetry_labels=None) async

Start a bidirectional streaming session over the single stream() primitive.

Opens an input channel, kicks off _stream(input_stream=channel), and returns a BidiConnection whose send/close push per-turn inputs into that channel while receive/output read the run's chunks and final result. init is the session identity for the whole connection; per-turn inputs arrive later via BidiConnection.send. It's sugar — all execution goes through the same run()/stream() path as any other action.

Source code in packages/genkit/src/genkit/_core/_action.py
2254
2255
2256
2257
2258
2259
2260
2261
2262
2263
2264
2265
2266
2267
2268
2269
2270
2271
2272
2273
2274
2275
2276
2277
2278
2279
2280
2281
2282
async def stream_bidi(
    self,
    init: InitT | None = None,
    *,
    context: dict[str, Any] | None = None,
    telemetry_labels: dict[str, object] | None = None,
) -> BidiConnection[InputT, ChunkT, OutputT]:
    """Start a bidirectional streaming session over the single stream() primitive.

    Opens an input channel, kicks off ``_stream(input_stream=channel)``, and
    returns a BidiConnection whose send/close push per-turn inputs into that
    channel while receive/output read the run's chunks and final result.
    ``init`` is the session identity for the whole connection; per-turn
    inputs arrive later via ``BidiConnection.send``. It's sugar — all
    execution goes through the same run()/stream() path as any other action.
    """
    # Unbounded: turn-level backpressure is managed at the agent runtime intake.
    in_queue: CloseableQueue[InputT] = CloseableQueue()
    # A connection outlives any one read of its chunks, so a reader that
    # stops early leaves the session running.
    stream_response = self._start_stream(
        input=NO_INPUT,
        init=init,
        context=context,
        telemetry_labels=telemetry_labels,
        input_stream=in_queue,
        stop_on_early_exit=False,
    )
    return BidiConnection(in_queue, stream_response)

AgentChat

Bases: typing.Generic[genkit._ai._agents._client.StateT]

A stateful conversation session with an agent.

Public surface: read snapshot_id, session_id, state, messages, and artifacts; call send / send_stream, resume / resume_stream, detach, and abort. Everything prefixed with _ is internal wiring.

state is the agent's custom session state; messages and artifacts are the running conversation and files. The chat tracks all three directly, so a client-managed resume just hands them back (chat(messages=chat.messages, state=chat.state, artifacts=chat.artifacts)). snapshot_id and session_id are the server store's resume handles.

The chat keeps these fields in sync with each turn's output and rebuilds the per-turn resume payload from them via _wire_init.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
class AgentChat(Generic[StateT]):
    """A stateful conversation session with an agent.

    Public surface: read ``snapshot_id``, ``session_id``, ``state``, ``messages``,
    and ``artifacts``; call ``send`` / ``send_stream``, ``resume`` /
    ``resume_stream``, ``detach``, and ``abort``. Everything prefixed with ``_``
    is internal wiring.

    ``state`` is the agent's custom session state; ``messages`` and ``artifacts``
    are the running conversation and files. The chat tracks all three directly,
    so a client-managed resume just hands them back (``chat(messages=chat.messages,
    state=chat.state, artifacts=chat.artifacts)``). ``snapshot_id`` and
    ``session_id`` are the server store's resume handles.

    The chat keeps these fields in sync with each turn's output and rebuilds the
    per-turn resume payload from them via ``_wire_init``.
    """

    def __init__(
        self,
        transport: AgentTransport[StateT],
        init: AgentInit | None = None,
        *,
        state_schema: type[StateT] | None = None,
    ) -> None:
        self._transport = transport
        self._state_schema = state_schema
        self._snapshot_id: str | None = None
        # Snapshot the next turn resumes from. Kept in lockstep with
        # ``_snapshot_id`` whenever a turn output carries one (including a
        # pending detached snapshot — a follow-up ``send`` then fails until that
        # snapshot completes or the chat is reloaded onto a completed ancestor).
        self._resume_snapshot_id: str | None = None
        self._session_id: str | None = None
        self._messages: list[Message] = []
        self._artifacts: list[Artifact] = []
        # Held as the wire-shaped blob (plain JSON); reads validate it into the
        # declared state model on the way out via _coerce_custom.
        self._custom: Any | None = None
        # Rebuilds a server-managed turn's full message history (including
        # intermediate tool steps) from its chunk stream; created fresh per turn.
        self._turn_accumulator: StreamedMessageAccumulator | None = None

        if init is not None:
            validate_init(init)
            # Store-backed chats resume by snapshot/session id only. Accepting a
            # seed state blob here would look live on the client while the server
            # session stayed empty — so refuse up front instead of dropping it.
            if init.state is not None and self._transport.state_management == 'server':
                fields = seeded_init_fields(init.state)
                raise AgentInitError(
                    status='FAILED_PRECONDITION',
                    message=(
                        f'Cannot send {fields} to a server-managed agent (one with a '
                        "store). Send 'snapshot_id' or 'session_id' instead."
                    ),
                )
            if init.state is not None:
                self._set_state(init.state)
            if init.snapshot_id:
                self._snapshot_id = init.snapshot_id
                self._resume_snapshot_id = init.snapshot_id
            if init.session_id:
                self._session_id = init.session_id

    @property
    def snapshot_id(self) -> str | None:
        """Store resume handle, kept in sync with the latest turn (store-backed only)."""
        return self._snapshot_id

    @property
    def state(self) -> StateT | None:
        """The agent's custom session state, kept live as the turn streams."""
        return self._coerce_custom(self._custom)

    def _coerce_custom(self, value: Any) -> StateT | None:  # noqa: ANN401
        """Validate the wire-shaped custom blob into the declared state model.

        Custom state rides the wire as plain JSON, so without a ``state_schema``
        the caller just gets that mapping back. With one, they get a real model
        instance — so reading ``state`` gives typed attribute access instead of a
        bare dict.
        """
        schema = self._state_schema
        if value is None or schema is None or isinstance(value, schema):
            return cast('StateT | None', value)
        return cast('StateT | None', schema.model_validate(value))

    @property
    def session_id(self) -> str | None:
        return self._session_id

    @property
    def messages(self) -> list[Message]:
        """Running view of the conversation, built the same way in both modes.

        A turn's messages are stitched from its chunk stream — the only channel
        that carries the in-between tool-request/tool-response steps — with the
        final reply taken from the turn's output when it's there (it carries the
        metadata a resume needs). The chunks are identical whether state is server-
        or client-managed, so there's one path here. For server-managed sessions
        the durable snapshot in the store stays the source of truth — use
        ``get_snapshot()`` / ``load_chat`` to read it (e.g. after a detached
        turn, whose chunks this session never saw).
        """
        return self._messages

    @property
    def artifacts(self) -> list[Artifact]:
        return self._artifacts

    # ------------------------------------------------------------------
    # Public API
    # ------------------------------------------------------------------

    async def send(
        self,
        input: str | AgentInput,
    ) -> AgentResponse[StateT]:
        """Runs a turn and returns the completed response.

        A turn that finishes failed still returns: ``finish_reason`` is
        ``failed`` and ``.error`` says why. It raises ``GenkitError`` only
        when the call never got a turn result (dropped connection, init
        misuse), and puts the chat back where it was before the send. A
        dropped connection may still have run the turn server-side, so
        reload with ``chat(session_id=...)`` before resending a turn whose
        tools have side effects. Cancelling or timing out the call is a
        client-side detach instead: it raises ``CancelledError`` /
        ``TimeoutError`` and keeps the prompt. Pumps the transport so custom-state
        patches and message stitching still apply; does not expose a chunk
        stream. For incremental chunks use :meth:`send_stream`.
        """
        return await self._start_turn(input).run()

    def send_stream(
        self,
        input: str | AgentInput,
    ) -> AgentTurn[StateT]:
        """Runs a turn and returns a handle with ``.stream`` / ``.response``.

        Streaming form of :meth:`send` (like ``Action.stream`` / ``ai.generate_stream``):
        same underlying turn, with chunks delivered to the caller. To stop a turn,
        call ``turn.abort()`` for a client-side detach (the server finishes in the
        background), or wrap the stream/response in ``asyncio.timeout(...)`` /
        cancel the surrounding task — both detach the same way and then surface the
        deadline. Use ``chat.abort()`` to halt server-side work on a store-backed
        agent.
        """
        return self._start_turn(input, chunks=CloseableQueue()).start()

    def _start_turn(
        self,
        input: str | AgentInput,
        *,
        chunks: CloseableQueue[AgentChunk[StateT] | Exception] | None = None,
    ) -> TurnDriver[StateT]:
        """Shared setup for :meth:`send` and :meth:`send_stream`."""
        inp = to_agent_input(input)

        # Capture the resume payload from history *before* this turn's message.
        # The transport carries the new message as the turn input and the agent
        # records it there, so a client-managed payload that also bundled it would
        # land the same message in history twice.
        init = self._wire_init()
        # If the turn raises, put back everything below (see _restore).
        checkpoint = self._checkpoint()
        # Optimistically append the user message so it shows immediately; remember
        # the prior length so a turn that lands no reply (server-side failed/aborted)
        # can roll it back. This length-based rollback assumes turns are single-flight
        # — overlapping sends on one session would race on this list and corrupt it.
        message_count_before = len(self.messages)
        # Streamed custom patches land on _custom as they arrive. Keep the
        # pre-turn value so a turn that lands no reply can undo them.
        custom_before = checkpoint.custom
        if inp.message:
            self.messages.append(inp.message)

        self._turn_accumulator = StreamedMessageAccumulator()
        return TurnDriver(
            inp=inp,
            init=init,
            run_turn=self._transport.run_turn,
            commit_output=lambda raw: self._commit_output(
                raw=raw, message_count_before=message_count_before, custom_before=custom_before
            ),
            commit_custom_patch=self._commit_custom_patch,
            accumulate_chunk=self._turn_accumulator.add,
            rollback=lambda: self._restore(checkpoint),
            chunks=chunks,
        )

    async def resume(
        self,
        *,
        respond: list[Part] | None = None,
        restart: list[Part] | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> AgentResponse[StateT]:
        """Continues a conversation from an interrupt and returns the response.

        Sugar for :meth:`send` with a resume payload. For streaming, use
        :meth:`resume_stream`.
        """
        wire = resume_options_to_resume(resume_respond=respond, resume_restart=restart, resume_metadata=metadata)
        return await self.send(AgentInput(resume=wire or Resume(metadata=metadata)))

    def resume_stream(
        self,
        *,
        respond: list[Part] | None = None,
        restart: list[Part] | None = None,
        metadata: dict[str, Any] | None = None,
    ) -> AgentTurn[StateT]:
        """Continues a conversation from an interrupt and returns an in-flight turn.

        ``respond`` answers paused tool requests; ``restart`` re-runs them with
        new metadata. Build each part with the interrupt's ``respond`` / ``restart``
        helpers. ``metadata`` rides along on the resumed tool message (the same
        ``resume_metadata`` a plain ``generate`` call takes). Sugar for
        :meth:`send_stream` with a resume payload.
        """
        wire = resume_options_to_resume(resume_respond=respond, resume_restart=restart, resume_metadata=metadata)
        return self.send_stream(AgentInput(resume=wire or Resume(metadata=metadata)))

    async def get_snapshot(self) -> SessionSnapshotVeneer | None:
        """Reads the current snapshot from the server store, if store-backed."""
        if not self._snapshot_id:
            return None
        return await self._transport.get_snapshot(snapshot_id=self._snapshot_id)

    async def detach(self, input: str | AgentInput) -> DetachedTask[StateT]:  # noqa: A002
        """Runs a turn in the background on the server and returns a poll handle."""
        inp = to_agent_input(input)
        inp.detach = True

        init = self._wire_init()
        # Optimistically append the user message so the local history reflects the
        # detached turn; the reply is retrieved later by polling the snapshot.
        message_count_before = len(self.messages)
        custom_before = copy.deepcopy(self._custom)
        if inp.message:
            self.messages.append(inp.message)

        # This session never sees a detached turn's chunks, so start from an empty
        # accumulator — otherwise a prior turn's messages would be folded
        # in when the output settles.
        self._turn_accumulator = StreamedMessageAccumulator()

        # The transport drives the turn to completion on its own (see
        # AgentTransport.run_turn), so the output resolves whether or not anyone
        # reads the stream. For detach we only care about the resulting handle.
        _stream, output_awaitable = await self._transport.run_turn(agent_input=inp, init=init)
        raw_output = await output_awaitable
        # Point the chat at the pending detached snapshot. A send() while it is
        # still pending is rejected; after it completes, send continues from
        # that snapshot. Abort stops the server turn but keeps the prompt —
        # it was still asked. Use chat(session_id=...) to resume from the last
        # completed turn.
        self._update_from_output(raw=raw_output, message_count_before=message_count_before, custom_before=custom_before)

        if not raw_output.snapshot_id:
            raise ValueError('detach did not return a snapshot_id.')
        return DetachedTask(
            snapshot_id=raw_output.snapshot_id,
            transport=self._transport,
            state_schema=self._state_schema,
        )

    async def abort(self) -> SnapshotStatus | None:
        """Stops the session's server-side work by aborting its current snapshot.

        The return is the snapshot's status from *before* this call, not after.
        ``pending`` means the turn was still running and this call cancelled it
        (the row is now ``aborted``). A terminal status means the turn had
        already finished. ``None`` means nothing was observed.

        Against this SDK the return is always the previous status. After abort
        the chat still points at the aborted leaf — ``chat(session_id=…)``
        before the next ``send()``. The local transcript keeps the prompt;
        it was still asked.

        Raises:
            ValueError: if there's no snapshot to abort — the agent is
                client-managed (no store) or no turn has produced a snapshot yet.
                For a client-side stop that just detaches the caller, use
                ``turn.abort()`` instead.
        """
        if not self._snapshot_id:
            raise ValueError(
                'No active snapshot to abort. session.abort() stops server-side work and '
                'needs a store-backed agent with a snapshot (e.g. after detach() or a '
                'completed turn). For a client-side stop, use turn.abort().'
            )
        return await self._transport.abort_snapshot(self._snapshot_id)

    # ------------------------------------------------------------------
    # Internal (transport / runtime wiring)
    # ------------------------------------------------------------------

    def _load_from_snapshot(self, snapshot: SessionSnapshotVeneer) -> None:
        self._snapshot_id = snapshot.snapshot_id
        self._resume_snapshot_id = snapshot.snapshot_id
        if snapshot.state is not None:
            self._set_state(snapshot.state)

    def _set_state(self, state: SessionStateVeneer) -> None:
        snapshot = state.model_copy(deep=True)
        self._session_id = snapshot.session_id
        self._messages = list(snapshot.messages or [])
        self._artifacts = list(snapshot.artifacts or [])
        self._custom = snapshot.custom

    def _session_state(self) -> SessionState:
        """Assembles the wire-shaped state blob from the chat's tracked fields."""
        return SessionState(
            session_id=self._session_id,
            messages=self._messages,
            custom=self._custom,
            artifacts=self._artifacts,
        ).model_copy(deep=True)

    def _wire_init(self) -> AgentInit:
        """Builds the resume payload for this turn from the live session state.

        The session doesn't hold onto the original init; it just keeps the
        tracked fields (and ``_snapshot_id``) synced with each turn's output and
        reconstructs the resume handle every request.
        """
        if self._transport.state_management == 'client':
            # snapshot_id on an agent with no store is misuse. Send the id
            # so the server rejects the init; a state blob would look like
            # a brand-new session and the caller would never see why.
            if self._resume_snapshot_id:
                return AgentInit(snapshot_id=self._resume_snapshot_id)
            # No server store, so the client is the source of truth: ship the
            # full live state every turn.
            return AgentInit(state=self._session_state())

        # A snapshot id already names the row. Sending session_id too would
        # re-check ownership every turn, and a mismatched id on the snapshot
        # vs its state would reject a row the caller already chose. Session
        # id is only the resume handle when there isn't a snapshot yet.
        if self._resume_snapshot_id:
            return AgentInit(snapshot_id=self._resume_snapshot_id)
        if self._session_id:
            return AgentInit(session_id=self._session_id)
        return AgentInit()

    def _apply_custom_patch(self, patch: Any) -> None:  # noqa: ANN401
        patch_list = patch.root if hasattr(patch, 'root') else patch
        self._custom = apply_json_patch(doc=self._custom, patch=patch_list)

    def _commit_output(
        self,
        *,
        raw: AgentOutput,
        message_count_before: int,
        custom_before: Any,  # noqa: ANN401
    ) -> AgentResponse[StateT]:
        """Folds a turn's final output into the session and builds the turn result.

        A failed turn returns with the last good snapshot or state. The
        caller reads why on ``.error`` and sends again from there.
        """
        self._update_from_output(raw=raw, message_count_before=message_count_before, custom_before=custom_before)
        raw = self._with_resume_snapshot(raw)
        return AgentResponse(raw=raw, messages=list(self.messages), state=self._response_state(raw))

    def _with_resume_snapshot(self, raw: AgentOutput) -> AgentOutput:
        """Put the last completed snapshot id on a failed or aborted turn that omitted one.

        A new connection whose first turn fails has no snapshot of its own.
        The chat is still on the previous completed one, and that is the
        id the caller resumes from.
        """
        if raw.finish_reason in _NO_REPLY and raw.snapshot_id is None and self._resume_snapshot_id is not None:
            return raw.model_copy(update={'snapshot_id': self._resume_snapshot_id})
        return raw

    def _response_state(self, raw: AgentOutput) -> StateT | None:
        """Typed custom state for the response, or None when it can't be read.

        Invalid custom state is itself the failed turn. Validating that
        blob again would raise and hide the error the turn returned.
        """
        try:
            return self.state
        except ValidationError:
            if raw.finish_reason not in _NO_REPLY:
                raise
            return None

    def _checkpoint(self) -> _TurnCheckpoint:
        """Everything a turn can change on the chat, taken before ``send`` touches it."""
        return _TurnCheckpoint(
            messages=list(self._messages),
            custom=copy.deepcopy(self._custom),
            artifacts=list(self._artifacts),
            session_id=self._session_id,
            snapshot_id=self._snapshot_id,
            resume_snapshot_id=self._resume_snapshot_id,
        )

    def _restore(self, checkpoint: _TurnCheckpoint) -> None:
        """Put the chat back where it was before a turn that raised.

        Usually the raise comes before any output, so only the optimistic
        prompt and streamed patches need undoing. But ``commit_output`` can
        also raise after the output was folded in (e.g. the final custom
        state fails ``state_schema``), so every field goes back, or the next
        send would resume from a snapshot the local history doesn't have.
        """
        # In place: callers may hold a reference to chat.messages.
        self._messages[:] = checkpoint.messages
        self._custom = checkpoint.custom
        self._artifacts = checkpoint.artifacts
        self._session_id = checkpoint.session_id
        self._snapshot_id = checkpoint.snapshot_id
        self._resume_snapshot_id = checkpoint.resume_snapshot_id

    def _commit_custom_patch(self, patch: Any) -> StateT | None:  # noqa: ANN401
        """Applies a streamed custom-state patch and returns the new custom state."""
        self._apply_custom_patch(patch)
        return self.state

    def _rollback_optimistic(self, message_count_before: int) -> None:
        """Drops the user message ``send`` optimistically pushed for an aborted turn.

        Inverse of the eager append in ``send``: trims the running view back to its
        pre-send length so an aborted turn doesn't strand an unanswered message and
        the next turn resumes from before it. Assumes single-flight turns, same as
        the failed-turn rollback in ``_update_from_output``.
        """
        del self.messages[message_count_before:]

    def _merge_artifacts(self, artifacts: list[Artifact]) -> None:
        """Merge a turn's artifacts into the running view, replacing by name."""
        for art in artifacts:
            name = art.name
            idx = next((i for i, x in enumerate(self.artifacts) if x.name == name), -1) if name else -1
            if idx >= 0:
                self.artifacts[idx] = art
            else:
                self.artifacts.append(art)

    def _update_from_output(
        self,
        *,
        raw: AgentOutput,
        message_count_before: int,
        custom_before: Any,  # noqa: ANN401
    ) -> None:
        # message_count_before and custom_before are the history length and
        # custom state from before this turn, so a turn that lands no reply
        # can roll back the optimistic user message and any streamed custom
        # patches (see send()).
        if raw.snapshot_id is not None:
            self._snapshot_id = raw.snapshot_id
            # A failed/aborted row is inspectable, not a place the next
            # send() can resume from. Keep the last completed id.
            # Everything else was asked — including a blocked refusal —
            # so the prompt stays and send continues from that snapshot.
            if raw.finish_reason not in _NO_REPLY:
                self._resume_snapshot_id = raw.snapshot_id

        if raw.finish_reason in _NO_REPLY:
            # No reply landed this turn, so drop the optimistic user message
            # rather than strand it unanswered; the next turn resumes from before
            # it. The durable snapshot still holds the truth. Its custom state
            # is the pre-turn one too; a client-managed output that carries
            # state overwrites this below.
            self._rollback_optimistic(message_count_before)
            self._custom = custom_before
        else:
            self._append_turn_messages(raw)

        self._sync_nonmessage_state(raw)

    def _append_turn_messages(self, raw: AgentOutput) -> None:
        """Extend the running view with this turn's messages.

        Intermediate tool-request/tool-response steps only exist on the chunk
        stream, so they're always taken from the accumulator. The final reply is
        taken from the turn's output when present — it's the copy that carries the
        interrupt and output-format metadata a resume depends on, which the model
        chunks don't.
        """
        streamed = self._turn_accumulator.messages() if self._turn_accumulator is not None else []

        # No output reply this turn (e.g. a long-lived socket that only resolves
        # at close): the streamed model group is the reply, so keep it whole.
        if raw.message is None:
            self.messages.extend(streamed)
            return

        # Prefer the output's reply over the streamed copy of it, so drop that
        # trailing streamed model group before appending the authoritative one.
        if streamed and streamed[-1].role == Role.MODEL:
            streamed = streamed[:-1]
        self.messages.extend(streamed)
        self.messages.append(raw.message)

    def _sync_nonmessage_state(self, raw: AgentOutput) -> None:
        """Refresh the non-message state a turn carries back.

        This is the one place the two modes diverge, and they have to: a
        client-managed session round-trips the whole blob, so the output is
        authoritative for the session id, custom state, and artifacts (the
        last-good values on a failed turn). A server-managed session never puts
        full state on the wire — custom stays live from streamed patches, and we
        only fold in whatever session id / artifacts the output reports.
        """
        if raw.state is not None:
            # Client-managed: the whole session round-trips, so the output is
            # authoritative for session id, custom state, and artifacts. Keep the
            # id so the next turn's state blob stays self-describing.
            self._session_id = raw.state.session_id
            self._custom = copy.deepcopy(raw.state.custom)
            self._artifacts = [a.model_copy(deep=True) for a in raw.state.artifacts] if raw.state.artifacts else []
            return

        # Server-managed: the store assigns and owns the session id, so adopt it
        # (and any artifacts) from the output.
        if raw.session_id is not None:
            self._session_id = raw.session_id
        if raw.artifacts:
            self._merge_artifacts(raw.artifacts)

messages property

Running view of the conversation, built the same way in both modes.

A turn's messages are stitched from its chunk stream — the only channel that carries the in-between tool-request/tool-response steps — with the final reply taken from the turn's output when it's there (it carries the metadata a resume needs). The chunks are identical whether state is server- or client-managed, so there's one path here. For server-managed sessions the durable snapshot in the store stays the source of truth — use get_snapshot() / load_chat to read it (e.g. after a detached turn, whose chunks this session never saw).

snapshot_id property

Store resume handle, kept in sync with the latest turn (store-backed only).

state property

The agent's custom session state, kept live as the turn streams.

abort() async

Stops the session's server-side work by aborting its current snapshot.

The return is the snapshot's status from before this call, not after. pending means the turn was still running and this call cancelled it (the row is now aborted). A terminal status means the turn had already finished. None means nothing was observed.

Against this SDK the return is always the previous status. After abort the chat still points at the aborted leaf — chat(session_id=…) before the next send(). The local transcript keeps the prompt; it was still asked.

Raises:

Type Description
ValueError

if there's no snapshot to abort — the agent is client-managed (no store) or no turn has produced a snapshot yet. For a client-side stop that just detaches the caller, use turn.abort() instead.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
async def abort(self) -> SnapshotStatus | None:
    """Stops the session's server-side work by aborting its current snapshot.

    The return is the snapshot's status from *before* this call, not after.
    ``pending`` means the turn was still running and this call cancelled it
    (the row is now ``aborted``). A terminal status means the turn had
    already finished. ``None`` means nothing was observed.

    Against this SDK the return is always the previous status. After abort
    the chat still points at the aborted leaf — ``chat(session_id=…)``
    before the next ``send()``. The local transcript keeps the prompt;
    it was still asked.

    Raises:
        ValueError: if there's no snapshot to abort — the agent is
            client-managed (no store) or no turn has produced a snapshot yet.
            For a client-side stop that just detaches the caller, use
            ``turn.abort()`` instead.
    """
    if not self._snapshot_id:
        raise ValueError(
            'No active snapshot to abort. session.abort() stops server-side work and '
            'needs a store-backed agent with a snapshot (e.g. after detach() or a '
            'completed turn). For a client-side stop, use turn.abort().'
        )
    return await self._transport.abort_snapshot(self._snapshot_id)

detach(input) async

Runs a turn in the background on the server and returns a poll handle.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
async def detach(self, input: str | AgentInput) -> DetachedTask[StateT]:  # noqa: A002
    """Runs a turn in the background on the server and returns a poll handle."""
    inp = to_agent_input(input)
    inp.detach = True

    init = self._wire_init()
    # Optimistically append the user message so the local history reflects the
    # detached turn; the reply is retrieved later by polling the snapshot.
    message_count_before = len(self.messages)
    custom_before = copy.deepcopy(self._custom)
    if inp.message:
        self.messages.append(inp.message)

    # This session never sees a detached turn's chunks, so start from an empty
    # accumulator — otherwise a prior turn's messages would be folded
    # in when the output settles.
    self._turn_accumulator = StreamedMessageAccumulator()

    # The transport drives the turn to completion on its own (see
    # AgentTransport.run_turn), so the output resolves whether or not anyone
    # reads the stream. For detach we only care about the resulting handle.
    _stream, output_awaitable = await self._transport.run_turn(agent_input=inp, init=init)
    raw_output = await output_awaitable
    # Point the chat at the pending detached snapshot. A send() while it is
    # still pending is rejected; after it completes, send continues from
    # that snapshot. Abort stops the server turn but keeps the prompt —
    # it was still asked. Use chat(session_id=...) to resume from the last
    # completed turn.
    self._update_from_output(raw=raw_output, message_count_before=message_count_before, custom_before=custom_before)

    if not raw_output.snapshot_id:
        raise ValueError('detach did not return a snapshot_id.')
    return DetachedTask(
        snapshot_id=raw_output.snapshot_id,
        transport=self._transport,
        state_schema=self._state_schema,
    )

get_snapshot() async

Reads the current snapshot from the server store, if store-backed.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1243
1244
1245
1246
1247
async def get_snapshot(self) -> SessionSnapshotVeneer | None:
    """Reads the current snapshot from the server store, if store-backed."""
    if not self._snapshot_id:
        return None
    return await self._transport.get_snapshot(snapshot_id=self._snapshot_id)

resume(*, respond=None, restart=None, metadata=None) async

Continues a conversation from an interrupt and returns the response.

Sugar for :meth:send with a resume payload. For streaming, use :meth:resume_stream.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
async def resume(
    self,
    *,
    respond: list[Part] | None = None,
    restart: list[Part] | None = None,
    metadata: dict[str, Any] | None = None,
) -> AgentResponse[StateT]:
    """Continues a conversation from an interrupt and returns the response.

    Sugar for :meth:`send` with a resume payload. For streaming, use
    :meth:`resume_stream`.
    """
    wire = resume_options_to_resume(resume_respond=respond, resume_restart=restart, resume_metadata=metadata)
    return await self.send(AgentInput(resume=wire or Resume(metadata=metadata)))

resume_stream(*, respond=None, restart=None, metadata=None)

Continues a conversation from an interrupt and returns an in-flight turn.

respond answers paused tool requests; restart re-runs them with new metadata. Build each part with the interrupt's respond / restart helpers. metadata rides along on the resumed tool message (the same resume_metadata a plain generate call takes). Sugar for :meth:send_stream with a resume payload.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
def resume_stream(
    self,
    *,
    respond: list[Part] | None = None,
    restart: list[Part] | None = None,
    metadata: dict[str, Any] | None = None,
) -> AgentTurn[StateT]:
    """Continues a conversation from an interrupt and returns an in-flight turn.

    ``respond`` answers paused tool requests; ``restart`` re-runs them with
    new metadata. Build each part with the interrupt's ``respond`` / ``restart``
    helpers. ``metadata`` rides along on the resumed tool message (the same
    ``resume_metadata`` a plain ``generate`` call takes). Sugar for
    :meth:`send_stream` with a resume payload.
    """
    wire = resume_options_to_resume(resume_respond=respond, resume_restart=restart, resume_metadata=metadata)
    return self.send_stream(AgentInput(resume=wire or Resume(metadata=metadata)))

send(input) async

Runs a turn and returns the completed response.

A turn that finishes failed still returns: finish_reason is failed and .error says why. It raises GenkitError only when the call never got a turn result (dropped connection, init misuse), and puts the chat back where it was before the send. A dropped connection may still have run the turn server-side, so reload with chat(session_id=...) before resending a turn whose tools have side effects. Cancelling or timing out the call is a client-side detach instead: it raises CancelledError / TimeoutError and keeps the prompt. Pumps the transport so custom-state patches and message stitching still apply; does not expose a chunk stream. For incremental chunks use :meth:send_stream.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
async def send(
    self,
    input: str | AgentInput,
) -> AgentResponse[StateT]:
    """Runs a turn and returns the completed response.

    A turn that finishes failed still returns: ``finish_reason`` is
    ``failed`` and ``.error`` says why. It raises ``GenkitError`` only
    when the call never got a turn result (dropped connection, init
    misuse), and puts the chat back where it was before the send. A
    dropped connection may still have run the turn server-side, so
    reload with ``chat(session_id=...)`` before resending a turn whose
    tools have side effects. Cancelling or timing out the call is a
    client-side detach instead: it raises ``CancelledError`` /
    ``TimeoutError`` and keeps the prompt. Pumps the transport so custom-state
    patches and message stitching still apply; does not expose a chunk
    stream. For incremental chunks use :meth:`send_stream`.
    """
    return await self._start_turn(input).run()

send_stream(input)

Runs a turn and returns a handle with .stream / .response.

Streaming form of :meth:send (like Action.stream / ai.generate_stream): same underlying turn, with chunks delivered to the caller. To stop a turn, call turn.abort() for a client-side detach (the server finishes in the background), or wrap the stream/response in asyncio.timeout(...) / cancel the surrounding task — both detach the same way and then surface the deadline. Use chat.abort() to halt server-side work on a store-backed agent.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
def send_stream(
    self,
    input: str | AgentInput,
) -> AgentTurn[StateT]:
    """Runs a turn and returns a handle with ``.stream`` / ``.response``.

    Streaming form of :meth:`send` (like ``Action.stream`` / ``ai.generate_stream``):
    same underlying turn, with chunks delivered to the caller. To stop a turn,
    call ``turn.abort()`` for a client-side detach (the server finishes in the
    background), or wrap the stream/response in ``asyncio.timeout(...)`` /
    cancel the surrounding task — both detach the same way and then surface the
    deadline. Use ``chat.abort()`` to halt server-side work on a store-backed
    agent.
    """
    return self._start_turn(input, chunks=CloseableQueue()).start()

AgentChunk dataclass

Bases: typing.Generic[genkit._ai._agents._client.StateT]

Represents a structured stream chunk yielded during a turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
175
176
177
178
179
180
181
182
183
184
185
186
187
188
@dataclass
class AgentChunk(Generic[StateT]):
    """Represents a structured stream chunk yielded during a turn."""

    text: str | None = None
    reasoning: str | None = None
    accumulated_text: str = ''  # this turn's text so far, including this chunk
    tool_requests: list[Part] = field(default_factory=list)
    tool_responses: list[Part] = field(default_factory=list)
    data: Any | None = None  # structured output part, if the chunk carries one
    media: Media | None = None
    artifact: Artifact | None = None
    custom: StateT | None = None  # post-patch resolved custom state; set when custom_patch is present
    raw: AgentStreamChunk | None = None

AgentClient

Bases: typing.Generic[genkit._ai._agents._client.StateT]

Transport-backed agent client — wraps any AgentTransport and implements AgentAPI.

This is the one ergonomic surface (chat/load_chat/get_snapshot/ abort) for talking to an agent, whether it's remote (HTTP transport) or in-process (the local agent action). get_snapshot and load_chat read the store; chat() is how you start or continue a conversation.

state_schema types the custom session state so the resulting chat hands back a validated model instead of a bare dict; leave it None for untyped state.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
class AgentClient(Generic[StateT]):
    """Transport-backed agent client — wraps any AgentTransport and implements AgentAPI.

    This is the one ergonomic surface (``chat``/``load_chat``/``get_snapshot``/
    ``abort``) for talking to an agent, whether it's remote (HTTP transport) or
    in-process (the local agent action). ``get_snapshot`` and ``load_chat``
    read the store; ``chat()`` is how you start or continue a conversation.

    ``state_schema`` types the custom session state so the resulting chat hands
    back a validated model instead of a bare dict; leave it None for untyped state.
    """

    def __init__(
        self,
        transport: AgentTransport[StateT],
        *,
        state_schema: type[StateT] | None = None,
    ) -> None:
        self._transport = transport
        self._state_schema = state_schema

    def chat(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
        messages: list[Message] | None = None,
        artifacts: list[Artifact] | None = None,
        state: StateT | None = None,
    ) -> AgentChat[StateT]:
        """Starts a new session, or resumes one.

        Store-backed agents take ``snapshot_id`` and/or ``session_id``.
        ``snapshot_id`` resumes that exact row (it must be completed).
        ``session_id`` continues the conversation: skip a failed / aborted /
        pending leaf, or start fresh if there isn't a completed turn yet.
        Passing both is fine: the snapshot picks the row, the session id
        checks it belongs to that session.

        ``messages`` / ``artifacts`` / ``state`` are only for client-managed
        agents (no store). Mixing those with a resume id, or sending a state
        blob to a store-backed agent, raises :class:`AgentInitError`.
        """
        session_transport = copy.copy(self._transport)
        return AgentChat(
            session_transport,
            init_from(
                snapshot_id=snapshot_id,
                session_id=session_id,
                messages=messages,
                artifacts=artifacts,
                state=state,
            ),
            state_schema=self._state_schema,
        )

    async def load_chat(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> AgentChat[StateT]:
        """Loads a stored snapshot onto a new chat.

        Pass exactly one of ``snapshot_id`` or ``session_id``. The chat is
        pointed at that row as stored — including a failed, aborted, or
        still-pending turn. ``send()`` resumes that row, so a non-completed
        leaf is rejected. To continue the conversation, use ``chat(session_id=)``.
        """
        snapshot = await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)
        if snapshot is None:
            raise GenkitError(
                status='NOT_FOUND',
                message=f'Snapshot {lookup_label(snapshot_id=snapshot_id, session_id=session_id)!r} not found.',
                reason=ErrorReason.SNAPSHOT_NOT_FOUND,
            )
        session_transport = copy.copy(self._transport)
        session_transport.state_management = 'server'
        chat = AgentChat(session_transport, state_schema=self._state_schema)
        chat._load_from_snapshot(snapshot)
        return chat

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> SessionSnapshotVeneer | None:
        """Reads a stored snapshot without starting a session.

        Pass exactly one of ``snapshot_id`` or ``session_id``. A session
        lookup returns the newest row even when that turn failed or was
        aborted. ``chat(session_id=)`` is how you continue from the last
        good turn.
        """
        return await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)

    async def abort(self, snapshot_id: str) -> SnapshotStatus | None:
        """Aborts a running snapshot on the server.

        The return is the snapshot's status from *before* this call, not after.
        ``pending`` means the turn was still running and this call cancelled it
        (the row is now ``aborted``). A terminal status (``completed``,
        ``failed``, ``aborted``) means the turn had already finished — this
        call did not rewrite it. ``None`` means nothing was observed (no row,
        or the store never ran the abort write).
        """
        return await self._transport.abort_snapshot(snapshot_id)

abort(snapshot_id) async

Aborts a running snapshot on the server.

The return is the snapshot's status from before this call, not after. pending means the turn was still running and this call cancelled it (the row is now aborted). A terminal status (completed, failed, aborted) means the turn had already finished — this call did not rewrite it. None means nothing was observed (no row, or the store never ran the abort write).

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
691
692
693
694
695
696
697
698
699
700
701
async def abort(self, snapshot_id: str) -> SnapshotStatus | None:
    """Aborts a running snapshot on the server.

    The return is the snapshot's status from *before* this call, not after.
    ``pending`` means the turn was still running and this call cancelled it
    (the row is now ``aborted``). A terminal status (``completed``,
    ``failed``, ``aborted``) means the turn had already finished — this
    call did not rewrite it. ``None`` means nothing was observed (no row,
    or the store never ran the abort write).
    """
    return await self._transport.abort_snapshot(snapshot_id)

chat(*, snapshot_id=None, session_id=None, messages=None, artifacts=None, state=None)

Starts a new session, or resumes one.

Store-backed agents take snapshot_id and/or session_id. snapshot_id resumes that exact row (it must be completed). session_id continues the conversation: skip a failed / aborted / pending leaf, or start fresh if there isn't a completed turn yet. Passing both is fine: the snapshot picks the row, the session id checks it belongs to that session.

messages / artifacts / state are only for client-managed agents (no store). Mixing those with a resume id, or sending a state blob to a store-backed agent, raises :class:AgentInitError.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
def chat(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
    messages: list[Message] | None = None,
    artifacts: list[Artifact] | None = None,
    state: StateT | None = None,
) -> AgentChat[StateT]:
    """Starts a new session, or resumes one.

    Store-backed agents take ``snapshot_id`` and/or ``session_id``.
    ``snapshot_id`` resumes that exact row (it must be completed).
    ``session_id`` continues the conversation: skip a failed / aborted /
    pending leaf, or start fresh if there isn't a completed turn yet.
    Passing both is fine: the snapshot picks the row, the session id
    checks it belongs to that session.

    ``messages`` / ``artifacts`` / ``state`` are only for client-managed
    agents (no store). Mixing those with a resume id, or sending a state
    blob to a store-backed agent, raises :class:`AgentInitError`.
    """
    session_transport = copy.copy(self._transport)
    return AgentChat(
        session_transport,
        init_from(
            snapshot_id=snapshot_id,
            session_id=session_id,
            messages=messages,
            artifacts=artifacts,
            state=state,
        ),
        state_schema=self._state_schema,
    )

get_snapshot(*, snapshot_id=None, session_id=None) async

Reads a stored snapshot without starting a session.

Pass exactly one of snapshot_id or session_id. A session lookup returns the newest row even when that turn failed or was aborted. chat(session_id=) is how you continue from the last good turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
676
677
678
679
680
681
682
683
684
685
686
687
688
689
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> SessionSnapshotVeneer | None:
    """Reads a stored snapshot without starting a session.

    Pass exactly one of ``snapshot_id`` or ``session_id``. A session
    lookup returns the newest row even when that turn failed or was
    aborted. ``chat(session_id=)`` is how you continue from the last
    good turn.
    """
    return await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)

load_chat(*, snapshot_id=None, session_id=None) async

Loads a stored snapshot onto a new chat.

Pass exactly one of snapshot_id or session_id. The chat is pointed at that row as stored — including a failed, aborted, or still-pending turn. send() resumes that row, so a non-completed leaf is rejected. To continue the conversation, use chat(session_id=).

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
async def load_chat(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> AgentChat[StateT]:
    """Loads a stored snapshot onto a new chat.

    Pass exactly one of ``snapshot_id`` or ``session_id``. The chat is
    pointed at that row as stored — including a failed, aborted, or
    still-pending turn. ``send()`` resumes that row, so a non-completed
    leaf is rejected. To continue the conversation, use ``chat(session_id=)``.
    """
    snapshot = await self._transport.get_snapshot(snapshot_id=snapshot_id, session_id=session_id)
    if snapshot is None:
        raise GenkitError(
            status='NOT_FOUND',
            message=f'Snapshot {lookup_label(snapshot_id=snapshot_id, session_id=session_id)!r} not found.',
            reason=ErrorReason.SNAPSHOT_NOT_FOUND,
        )
    session_transport = copy.copy(self._transport)
    session_transport.state_management = 'server'
    chat = AgentChat(session_transport, state_schema=self._state_schema)
    chat._load_from_snapshot(snapshot)
    return chat

AgentContext

Bases: genkit._core._action.ActionContext[genkit._core._model.AgentStreamChunk]

Execution context passed to a custom agent function.

Provides ctx.send_chunk(chunk) for streaming :class:AgentStreamChunk items and ctx.context for caller context data.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
280
281
282
283
284
285
class AgentContext(ActionContext[AgentStreamChunk]):
    """Execution context passed to a custom agent function.

    Provides ``ctx.send_chunk(chunk)`` for streaming :class:`AgentStreamChunk`
    items and ``ctx.context`` for caller context data.
    """

context property

The request context (auth, headers, ...) the caller attached.

is_streaming property

True if a streaming callback is registered.

streaming_callback property

The streaming callback, if any.

Use this when you need to pass the callback to another action. For sending chunks directly, use send_chunk() instead.

send_chunk(chunk)

Send a streaming chunk to the client.

Parameters:

Name Type Description Default
chunk genkit._core._action.ChunkT

The chunk data to stream.

required
Source code in packages/genkit/src/genkit/_core/_action.py
1053
1054
1055
1056
1057
1058
1059
1060
def send_chunk(self, chunk: ChunkT) -> None:
    """Send a streaming chunk to the client.

    Args:
        chunk: The chunk data to stream.
    """
    if self._streaming_callback is not None:
        self._streaming_callback(chunk)

AgentFinishReason

Bases: genkit._core._compat.StrEnum

AgentFinishReason data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
37
38
39
40
41
42
43
44
45
46
47
48
class AgentFinishReason(StrEnum):
    """AgentFinishReason data type class."""

    STOP = 'stop'
    LENGTH = 'length'
    BLOCKED = 'blocked'
    INTERRUPTED = 'interrupted'
    OTHER = 'other'
    UNKNOWN = 'unknown'
    ABORTED = 'aborted'
    DETACHED = 'detached'
    FAILED = 'failed'

AgentInit

Bases: genkit._core._base.GenkitModel

Init payload whose state uses the public SessionState type.

Source code in packages/genkit/src/genkit/_core/_model.py
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
class AgentInit(GenkitModel):
    """Init payload whose state uses the public SessionState type."""

    session_id: str | None = None
    snapshot_id: str | None = None
    state: SessionState | None = None

    @field_validator('state', mode='before')
    @classmethod
    def _wrap_state(cls, v: object) -> object:
        if v is None:
            return v
        return as_session_state(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

AgentInitError

Bases: genkit._core._error.PublicError

API misuse on agent init that must surface as a thrown/HTTP error.

Covers calling an agent with an init that does not match its state-management mode (e.g. sending state to a server-managed agent). Recoverable pre-turn problems (missing or non-resumable snapshot, invalid custom state) are not subclasses of AgentInitError, so define_custom_agent absorbs them into finish_reason='failed'.

It is a PublicError: the message names only the init fields and ids the caller sent, so a served agent returns its status, message, and details.reason and a remote client reads the same reason it would in-process.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
class AgentInitError(PublicError):
    """API misuse on agent init that must surface as a thrown/HTTP error.

    Covers calling an agent with an init that does not match its state-management
    mode (e.g. sending ``state`` to a server-managed agent). Recoverable pre-turn
    problems (missing or non-resumable snapshot, invalid custom state) are not
    subclasses of ``AgentInitError``, so ``define_custom_agent`` absorbs them
    into ``finish_reason='failed'``.

    It is a ``PublicError``: the message names only the init fields and ids the
    caller sent, so a served agent returns its status, message, and
    ``details.reason`` and a remote client reads the same ``reason`` it would
    in-process.
    """

    def __init__(self, *, status: StatusName, message: str, reason: ErrorReason | None = None) -> None:
        """Initialize an AgentInitError.

        Args:
            status: The status name for this error.
            message: Caller-facing sentence; must not include server-side data.
            reason: Stable reason, sent on the wire as ``details.reason``.
        """
        super().__init__(status, message, reason=reason)

__init__(*, status, message, reason=None)

Initialize an AgentInitError.

Parameters:

Name Type Description Default
status genkit._core._error.StatusName

The status name for this error.

required
message str

Caller-facing sentence; must not include server-side data.

required
reason genkit._core._error.ErrorReason | None

Stable reason, sent on the wire as details.reason.

None
Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
343
344
345
346
347
348
349
350
351
def __init__(self, *, status: StatusName, message: str, reason: ErrorReason | None = None) -> None:
    """Initialize an AgentInitError.

    Args:
        status: The status name for this error.
        message: Caller-facing sentence; must not include server-side data.
        reason: Stable reason, sent on the wire as ``details.reason``.
    """
    super().__init__(status, message, reason=reason)

AgentInput

Bases: genkit._core._base.GenkitModel

Turn input whose message is the public Message type.

Source code in packages/genkit/src/genkit/_core/_model.py
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
class AgentInput(GenkitModel):
    """Turn input whose message is the public Message type."""

    detach: bool | None = None
    message: Message | None = None
    resume: Resume | None = None

    @field_validator('message', mode='before')
    @classmethod
    def _wrap_message(cls, v: object) -> object:
        if v is None:
            return v
        return as_message(v)

    @field_validator('resume', mode='before')
    @classmethod
    def _wrap_resume(cls, v: object) -> object:
        if v is None:
            return v
        return as_resume(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

AgentInterrupt

Bases: typing.Generic[genkit._ai._agents._client.InputT, genkit._ai._agents._client.OutputT]

Represents a tool request interrupt that paused the turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
class AgentInterrupt(Generic[InputT, OutputT]):
    """Represents a tool request interrupt that paused the turn."""

    def __init__(
        self,
        name: str,
        ref: str | None,
        input_data: InputT,
        metadata: dict[str, Any] | None = None,
    ) -> None:
        self.name = name
        self.ref = ref
        self.input = input_data
        # What the tool passed to ``Interrupt(...)``: approval reason, amount, etc.
        self.metadata = metadata

    def respond(self, output: OutputT) -> Part:
        """Tool response for ``chat.resume(respond=[...])``.

        Carries the output only. ``Part.respond`` is the call that attaches
        ``interruptResponse`` metadata.
        """
        return Part.from_tool_response(
            name=self.name,
            ref=self.ref,
            output=output,
        )

    def restart(
        self,
        *,
        resumed_metadata: dict[str, Any] | None = None,
    ) -> Part:
        """Tool request for ``chat.resume(restart=[...])``.

        The tool sees a resume (``ctx.is_resumed()`` is true). Pass
        ``resumed_metadata`` when it needs the approval payload.

        The request input stays the one the model asked for — a client
        cannot re-run a tool with arguments the model never sent.
        """
        part = Part.from_tool_request(
            name=self.name,
            ref=self.ref,
            input=self.input,
        )
        return part.restart(resumed_metadata=resumed_metadata)

respond(output)

Tool response for chat.resume(respond=[...]).

Carries the output only. Part.respond is the call that attaches interruptResponse metadata.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
207
208
209
210
211
212
213
214
215
216
217
def respond(self, output: OutputT) -> Part:
    """Tool response for ``chat.resume(respond=[...])``.

    Carries the output only. ``Part.respond`` is the call that attaches
    ``interruptResponse`` metadata.
    """
    return Part.from_tool_response(
        name=self.name,
        ref=self.ref,
        output=output,
    )

restart(*, resumed_metadata=None)

Tool request for chat.resume(restart=[...]).

The tool sees a resume (ctx.is_resumed() is true). Pass resumed_metadata when it needs the approval payload.

The request input stays the one the model asked for — a client cannot re-run a tool with arguments the model never sent.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
def restart(
    self,
    *,
    resumed_metadata: dict[str, Any] | None = None,
) -> Part:
    """Tool request for ``chat.resume(restart=[...])``.

    The tool sees a resume (``ctx.is_resumed()`` is true). Pass
    ``resumed_metadata`` when it needs the approval payload.

    The request input stays the one the model asked for — a client
    cannot re-run a tool with arguments the model never sent.
    """
    part = Part.from_tool_request(
        name=self.name,
        ref=self.ref,
        input=self.input,
    )
    return part.restart(resumed_metadata=resumed_metadata)

AgentOutput

Bases: genkit._core._base.GenkitModel

Turn output whose message and artifacts are the public types.

Source code in packages/genkit/src/genkit/_core/_model.py
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
class AgentOutput(GenkitModel):
    """Turn output whose message and artifacts are the public types."""

    session_id: str | None = None
    snapshot_id: str | None = None
    state: SessionState | None = None
    message: Message | None = None
    artifacts: list[Artifact] | None = None
    finish_reason: AgentFinishReason | None = None
    error: Failure | None = None
    usage: GenerationUsage | None = None

    @field_validator('message', mode='before')
    @classmethod
    def _wrap_message(cls, v: object) -> object:
        if v is None:
            return v
        return as_message(v)

    @field_validator('artifacts', mode='before')
    @classmethod
    def _wrap_artifacts(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_artifact(a) for a in v]

    @field_validator('state', mode='before')
    @classmethod
    def _wrap_state(cls, v: object) -> object:
        if v is None:
            return v
        return as_session_state(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

AgentResponse dataclass

Bases: typing.Generic[genkit._ai._agents._client.StateT]

Completed turn result — client-side wrapper around AgentOutput with rich accessors.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
@dataclass
class AgentResponse(Generic[StateT]):
    """Completed turn result — client-side wrapper around AgentOutput with rich accessors."""

    raw: AgentOutput
    messages: list[Message]
    state: StateT | None = None

    @property
    def text(self) -> str:
        """Full text content of the response message."""
        return text_of(self.message.content) if self.message else ''

    @property
    def reasoning(self) -> str:
        """Concatenated reasoning the model exposed for this turn."""
        return reasoning_of(self.message.content) if self.message else ''

    @property
    def media(self) -> Media | None:
        """First media part of the response message, if any."""
        return first_media_of(self.message.content) if self.message else None

    @property
    def data(self) -> Any:  # noqa: ANN401
        """Structured-output value of the response message, if the model returned one."""
        return first_data_of(self.message.content) if self.message else None

    @property
    def finish_reason(self) -> AgentFinishReason | None:
        """Why the turn ended."""
        return self.raw.finish_reason

    @property
    def finish_message(self) -> str | None:
        """Human-readable detail when a turn ends abnormally (e.g. blocked or failed)."""
        return self.raw.error.message if self.raw.error else None

    @property
    def snapshot_id(self) -> str | None:
        """Server snapshot id after this turn, if store-backed."""
        return self.raw.snapshot_id

    @property
    def session_id(self) -> str | None:
        """Session id this turn belongs to (store- or client-managed)."""
        return self.raw.session_id

    @property
    def artifacts(self) -> list[Artifact]:
        """Artifacts emitted during this turn."""
        return self.raw.artifacts or []

    @property
    def error(self) -> Failure | None:
        """Why this turn failed, or None when it didn't.

        Same fields generate puts on ``response.error`` (status, message,
        details, and reason), so one check reads both. A failed turn that
        carried no error still gets one, so ``if res.error:`` never reads a
        failure as success.
        """
        if self.raw.error is not None:
            return self.raw.error
        if self.raw.finish_reason == AgentFinishReason.FAILED:
            return _UNEXPLAINED_FAILURE
        return None

    @property
    def message(self) -> Message | None:
        """The response message.

        A failed or aborted turn's wire message is the previous reply.
        Showing it would look like this turn answered, so this is None and
        every accessor that reads the reply (text, data, interrupts, ...)
        comes back empty.
        """
        if self.raw.finish_reason in _NO_REPLY:
            return None
        return self.raw.message

    @property
    def tool_requests(self) -> list[Part]:
        """Tool requests in the response message."""
        return tool_requests_of(self.message.content) if self.message else []

    @property
    def interrupts(self) -> list[AgentInterrupt[Any, Any]]:
        """Tool requests that paused this turn."""
        return agent_interrupts_from_message(self.message)

artifacts property

Artifacts emitted during this turn.

data property

Structured-output value of the response message, if the model returned one.

error property

Why this turn failed, or None when it didn't.

Same fields generate puts on response.error (status, message, details, and reason), so one check reads both. A failed turn that carried no error still gets one, so if res.error: never reads a failure as success.

finish_message property

Human-readable detail when a turn ends abnormally (e.g. blocked or failed).

finish_reason property

Why the turn ended.

interrupts property

Tool requests that paused this turn.

media property

First media part of the response message, if any.

message property

The response message.

A failed or aborted turn's wire message is the previous reply. Showing it would look like this turn answered, so this is None and every accessor that reads the reply (text, data, interrupts, ...) comes back empty.

reasoning property

Concatenated reasoning the model exposed for this turn.

session_id property

Session id this turn belongs to (store- or client-managed).

snapshot_id property

Server snapshot id after this turn, if store-backed.

text property

Full text content of the response message.

tool_requests property

Tool requests in the response message.

AgentResult

Bases: genkit._core._base.GenkitModel

Agent result whose message and artifacts are the public types.

Source code in packages/genkit/src/genkit/_core/_model.py
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
class AgentResult(GenkitModel):
    """Agent result whose message and artifacts are the public types."""

    message: Message | None = None
    artifacts: list[Artifact] | None = None
    finish_reason: AgentFinishReason | None = None

    @field_validator('message', mode='before')
    @classmethod
    def _wrap_message(cls, v: object) -> object:
        if v is None:
            return v
        return as_message(v)

    @field_validator('artifacts', mode='before')
    @classmethod
    def _wrap_artifacts(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_artifact(a) for a in v]

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

AgentStreamChunk

Bases: genkit._core._base.GenkitModel

One streamed piece of an agent turn.

Source code in packages/genkit/src/genkit/_core/_model.py
2190
2191
2192
2193
2194
2195
2196
2197
2198
2199
2200
2201
2202
2203
2204
2205
2206
2207
2208
2209
2210
class AgentStreamChunk(GenkitModel):
    """One streamed piece of an agent turn."""

    model_chunk: ModelResponseChunk | None = None
    custom_patch: JsonPatch | None = None
    artifact: Artifact | None = None
    turn_end: TurnEnd | None = None

    @field_validator('model_chunk', mode='before')
    @classmethod
    def _wrap_chunk(cls, v: object) -> object:
        if v is None:
            return v
        return as_model_response_chunk(v)

    @field_validator('artifact', mode='before')
    @classmethod
    def _wrap_artifact(cls, v: object) -> object:
        if v is None:
            return v
        return as_artifact(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

AgentTransport

Bases: typing.Protocol, typing.Generic[genkit._ai._agents._client.StateT_co]

Interface implemented by the transport layer (local or websocket).

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
class AgentTransport(Protocol, Generic[StateT_co]):
    """Interface implemented by the transport layer (local or websocket)."""

    # Declares server- vs client-managed state; must be set explicitly on the transport.
    state_management: StateManagement

    async def run_turn(
        self,
        *,
        agent_input: AgentInput,
        init: AgentInit,
    ) -> tuple[AsyncIterable[AgentStreamChunk], Awaitable[AgentOutput]]:
        """Run a single turn, returning a (stream, output) pair.

        The transport must drive the turn to completion on its own — the returned
        output awaitable has to resolve whether or not the caller consumes the
        stream. The stream is an optional live view of the same turn, never the
        thing that advances it, so ``await output`` works without draining chunks.
        Concretely: read your own transport (socket, queue, SSE) to the end in a
        background task; don't rely on the client to pull the stream for you.

        ``init`` describes how to resume the conversation for this turn. A stateful
        in-process transport reads it only when it opens its connection; a
        stateless transport (HTTP) replays it on every request. The session keeps
        it current via ``_wire_init`` so the transport never has to know how state
        is managed.
        """
        ...

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> SessionSnapshotVeneer | None:
        """Retrieves a session snapshot from the server store."""
        ...

    async def abort_snapshot(self, snapshot_id: str) -> SnapshotStatus | None:
        """Aborts the specified snapshot on the server."""
        ...

abort_snapshot(snapshot_id) async

Aborts the specified snapshot on the server.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
165
166
167
async def abort_snapshot(self, snapshot_id: str) -> SnapshotStatus | None:
    """Aborts the specified snapshot on the server."""
    ...

get_snapshot(*, snapshot_id=None, session_id=None) async

Retrieves a session snapshot from the server store.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
156
157
158
159
160
161
162
163
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> SessionSnapshotVeneer | None:
    """Retrieves a session snapshot from the server store."""
    ...

run_turn(*, agent_input, init) async

Run a single turn, returning a (stream, output) pair.

The transport must drive the turn to completion on its own — the returned output awaitable has to resolve whether or not the caller consumes the stream. The stream is an optional live view of the same turn, never the thing that advances it, so await output works without draining chunks. Concretely: read your own transport (socket, queue, SSE) to the end in a background task; don't rely on the client to pull the stream for you.

init describes how to resume the conversation for this turn. A stateful in-process transport reads it only when it opens its connection; a stateless transport (HTTP) replays it on every request. The session keeps it current via _wire_init so the transport never has to know how state is managed.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
async def run_turn(
    self,
    *,
    agent_input: AgentInput,
    init: AgentInit,
) -> tuple[AsyncIterable[AgentStreamChunk], Awaitable[AgentOutput]]:
    """Run a single turn, returning a (stream, output) pair.

    The transport must drive the turn to completion on its own — the returned
    output awaitable has to resolve whether or not the caller consumes the
    stream. The stream is an optional live view of the same turn, never the
    thing that advances it, so ``await output`` works without draining chunks.
    Concretely: read your own transport (socket, queue, SSE) to the end in a
    background task; don't rely on the client to pull the stream for you.

    ``init`` describes how to resume the conversation for this turn. A stateful
    in-process transport reads it only when it opens its connection; a
    stateless transport (HTTP) replays it on every request. The session keeps
    it current via ``_wire_init`` so the transport never has to know how state
    is managed.
    """
    ...

AgentTurn

Bases: typing.Generic[genkit._ai._agents._client.StateT]

A single in-flight turn — read .stream for chunks, .response for the result.

Same handle shape as action.stream(): the turn runs whether or not you read .stream, and .response resolves to the final result either way.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
class AgentTurn(Generic[StateT]):
    """A single in-flight turn — read ``.stream`` for chunks, ``.response`` for the result.

    Same handle shape as ``action.stream()``: the turn runs whether or not you read
    ``.stream``, and ``.response`` resolves to the final result either way.
    """

    def __init__(
        self,
        *,
        stream: AsyncIterable[AgentChunk[StateT]],
        output: Awaitable[AgentResponse[StateT]],
        abort_fn: Callable[[], Awaitable[None] | None] | None = None,
    ) -> None:
        self._stream = stream
        self._output = output
        self._abort_fn = abort_fn

    @property
    def stream(self) -> AsyncIterator[AgentChunk[StateT]]:
        """The turn's chunk stream.

        Cancelling the consumer (``asyncio.timeout(...)`` or a task cancel around the
        loop) detaches the turn like ``turn.abort()`` — the client stops listening and
        the server finishes in the background — then the cancellation propagates so the
        deadline still surfaces.
        """
        return self._stream_detaching_on_cancel()

    async def _stream_detaching_on_cancel(self) -> AsyncIterator[AgentChunk[StateT]]:
        try:
            async for chunk in self._stream:
                yield chunk
        except asyncio.CancelledError:
            await self.abort()
            raise

    @property
    def response(self) -> Awaitable[AgentResponse[StateT]]:
        """The turn's final result. The turn runs whether or not you read ``.stream``."""
        return self._await_detaching_on_cancel()

    async def _await_detaching_on_cancel(self) -> AgentResponse[StateT]:
        """Awaits the result, detaching the turn if the awaiter is cancelled.

        Lets ``async with asyncio.timeout(...): await turn.response`` (or any task
        cancel) detach the client the same way ``turn.abort()`` would, then re-raises
        so the deadline still surfaces as a TimeoutError/CancelledError.
        """
        try:
            return await self._output
        except asyncio.CancelledError:
            await self.abort()
            raise

    def __aiter__(self) -> AsyncIterator[AgentChunk[StateT]]:
        return self.stream

    def __await__(self) -> Generator[Any, None, AgentResponse[StateT]]:
        return self.response.__await__()

    async def abort(self) -> None:
        """Detaches the client from this turn: stops streaming and settles the result now.

        This is a client-side abort. The server turn keeps running to completion
        in the background so its work still lands; we just stop listening and
        resolve the awaited result as cancelled. The prompt you sent stays in
        history — it was still asked — so the session reads like a turn that
        simply got no reply. To actually halt server-side work on a store-backed
        agent, use ``chat.abort()``.
        """
        if self._abort_fn:
            res = self._abort_fn()
            if inspect.isawaitable(res):
                await res
        # Detaching cancelled the result. But the turn may have already settled on
        # its own a beat earlier (succeeded or failed), in which case we didn't
        # cancel it. Read that terminal state so a failed turn's exception isn't
        # logged as never-retrieved; .exception() does this without raising (unlike
        # awaiting), and returns None for a successful turn.
        if isinstance(self._output, asyncio.Future) and self._output.done() and not self._output.cancelled():
            self._output.exception()

response property

The turn's final result. The turn runs whether or not you read .stream.

stream property

The turn's chunk stream.

Cancelling the consumer (asyncio.timeout(...) or a task cancel around the loop) detaches the turn like turn.abort() — the client stops listening and the server finishes in the background — then the cancellation propagates so the deadline still surfaces.

abort() async

Detaches the client from this turn: stops streaming and settles the result now.

This is a client-side abort. The server turn keeps running to completion in the background so its work still lands; we just stop listening and resolve the awaited result as cancelled. The prompt you sent stays in history — it was still asked — so the session reads like a turn that simply got no reply. To actually halt server-side work on a store-backed agent, use chat.abort().

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
async def abort(self) -> None:
    """Detaches the client from this turn: stops streaming and settles the result now.

    This is a client-side abort. The server turn keeps running to completion
    in the background so its work still lands; we just stop listening and
    resolve the awaited result as cancelled. The prompt you sent stays in
    history — it was still asked — so the session reads like a turn that
    simply got no reply. To actually halt server-side work on a store-backed
    agent, use ``chat.abort()``.
    """
    if self._abort_fn:
        res = self._abort_fn()
        if inspect.isawaitable(res):
            await res
    # Detaching cancelled the result. But the turn may have already settled on
    # its own a beat earlier (succeeded or failed), in which case we didn't
    # cancel it. Read that terminal state so a failed turn's exception isn't
    # logged as never-retrieved; .exception() does this without raising (unlike
    # awaiting), and returns None for a successful turn.
    if isinstance(self._output, asyncio.Future) and self._output.done() and not self._output.cancelled():
        self._output.exception()

Artifact

Bases: genkit._core._base.GenkitModel

Named session file whose parts are the public Part type.

Source code in packages/genkit/src/genkit/_core/_model.py
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
class Artifact(GenkitModel):
    """Named session file whose parts are the public Part type."""

    name: str | None = None
    parts: list[Part]
    metadata: dict[str, Any] | None = None

    @field_validator('parts', mode='before')
    @classmethod
    def _wrap_parts(cls, v: object) -> object:
        return parts_from_inbound(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

DetachedTask

Bases: typing.Generic[genkit._ai._agents._client.StateT]

A handle to a background (detached) turn running on the server.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
class DetachedTask(Generic[StateT]):
    """A handle to a background (detached) turn running on the server."""

    def __init__(
        self,
        *,
        snapshot_id: str,
        transport: AgentTransport[StateT],
        state_schema: type[StateT] | None = None,
    ) -> None:
        self.snapshot_id = snapshot_id
        self._transport = transport
        self._state_schema = state_schema

    def _parse_snapshot(self, raw: SessionSnapshotVeneer | None) -> SessionSnapshot[StateT] | None:
        if raw is None:
            return None
        snap = SessionSnapshot[StateT].model_validate_json(raw.model_dump_json(by_alias=True))
        if snap.state is not None and snap.state.custom is not None and self._state_schema is not None:
            try:
                snap.state.custom = self._state_schema.model_validate(snap.state.custom)
            except Exception:
                if snap.status is not None and snap.status in TERMINAL_SNAPSHOT_STATUSES:
                    raise
        return snap

    async def poll(self, interval: float = 1.0) -> AsyncIterator[SessionSnapshot[StateT]]:
        """Yields the task's snapshot every ``interval`` seconds until it settles.

        Re-reads the server snapshot on a fixed cadence and stops once it reaches
        a terminal status (completed, failed, aborted, or expired), so a caller
        can drive a live status UI with a plain ``async for``. For just the final
        result, await ``wait`` instead.
        """
        while True:
            raw = await self._transport.get_snapshot(snapshot_id=self.snapshot_id)
            snap = self._parse_snapshot(raw)
            if snap is not None:
                yield snap
                if snap.status is not None and snap.status in TERMINAL_SNAPSHOT_STATUSES:
                    return
            await asyncio.sleep(interval)

    async def wait(self, interval: float = 1.0) -> SessionSnapshot[StateT]:
        """Polls until the task settles and returns its final snapshot."""
        last: SessionSnapshot[StateT] | None = None
        async for snapshot in self.poll(interval):
            last = snapshot
        if last is None:
            raise ValueError(f'Detached task {self.snapshot_id} produced no snapshot.')
        return last

    async def abort(self) -> SnapshotStatus | None:
        """Aborts the detached task on the server.

        The return is the snapshot's status from *before* this call, not after.
        ``pending`` means this call cancelled a still-running turn (the row is
        now ``aborted``). A terminal status means the turn had already
        finished. ``None`` means nothing was observed.

        This does not edit the originating chat's transcript. The prompt was
        still asked; reload via ``chat(session_id=...)`` before the next send
        so you are not still pointed at the aborted leaf.
        """
        return await self._transport.abort_snapshot(self.snapshot_id)

abort() async

Aborts the detached task on the server.

The return is the snapshot's status from before this call, not after. pending means this call cancelled a still-running turn (the row is now aborted). A terminal status means the turn had already finished. None means nothing was observed.

This does not edit the originating chat's transcript. The prompt was still asked; reload via chat(session_id=...) before the next send so you are not still pointed at the aborted leaf.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
async def abort(self) -> SnapshotStatus | None:
    """Aborts the detached task on the server.

    The return is the snapshot's status from *before* this call, not after.
    ``pending`` means this call cancelled a still-running turn (the row is
    now ``aborted``). A terminal status means the turn had already
    finished. ``None`` means nothing was observed.

    This does not edit the originating chat's transcript. The prompt was
    still asked; reload via ``chat(session_id=...)`` before the next send
    so you are not still pointed at the aborted leaf.
    """
    return await self._transport.abort_snapshot(self.snapshot_id)

poll(interval=1.0) async

Yields the task's snapshot every interval seconds until it settles.

Re-reads the server snapshot on a fixed cadence and stops once it reaches a terminal status (completed, failed, aborted, or expired), so a caller can drive a live status UI with a plain async for. For just the final result, await wait instead.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
async def poll(self, interval: float = 1.0) -> AsyncIterator[SessionSnapshot[StateT]]:
    """Yields the task's snapshot every ``interval`` seconds until it settles.

    Re-reads the server snapshot on a fixed cadence and stops once it reaches
    a terminal status (completed, failed, aborted, or expired), so a caller
    can drive a live status UI with a plain ``async for``. For just the final
    result, await ``wait`` instead.
    """
    while True:
        raw = await self._transport.get_snapshot(snapshot_id=self.snapshot_id)
        snap = self._parse_snapshot(raw)
        if snap is not None:
            yield snap
            if snap.status is not None and snap.status in TERMINAL_SNAPSHOT_STATUSES:
                return
        await asyncio.sleep(interval)

wait(interval=1.0) async

Polls until the task settles and returns its final snapshot.

Source code in packages/genkit/src/genkit/_ai/_agents/_client.py
1602
1603
1604
1605
1606
1607
1608
1609
async def wait(self, interval: float = 1.0) -> SessionSnapshot[StateT]:
    """Polls until the task settles and returns its final snapshot."""
    last: SessionSnapshot[StateT] | None = None
    async for snapshot in self.poll(interval):
        last = snapshot
    if last is None:
        raise ValueError(f'Detached task {self.snapshot_id} produced no snapshot.')
    return last

FileSessionStore

Bases: genkit._ai._agents._session.SessionStoreLock, genkit._ai._agents._session.SessionStore[genkit._ai._agents._session.StateT], genkit._ai._agents._session.SnapshotSubscriber, typing.Generic[genkit._ai._agents._session.StateT]

File-backed snapshot store: one <snapshot_id>.json per snapshot.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
class FileSessionStore(SessionStoreLock, SessionStore[StateT], SnapshotSubscriber, Generic[StateT]):
    """File-backed snapshot store: one ``<snapshot_id>.json`` per snapshot."""

    def __init__(
        self,
        directory: str,
        *,
        reject_ambiguous_session: bool = False,
        max_persisted_chain_length: int | None = None,
    ) -> None:
        """Create the store, ensuring ``directory`` exists.

        See :class:`InMemorySessionStore` for ``reject_ambiguous_session``.

        ``max_persisted_chain_length`` caps how many snapshots of a chat's
        history stay on disk: once a chain grows past it, the oldest turns are
        deleted on each save so a long-lived conversation doesn't accumulate
        files forever. Resuming and continuing still work, but you lose the
        ability to rewind or branch past the retained window. Leave it unset to
        keep the full history.
        """
        self.reject_ambiguous = reject_ambiguous_session
        self.max_persisted_chain_length = max_persisted_chain_length
        self.directory = directory
        self.subs: Subs = {}
        os.makedirs(directory, exist_ok=True)

    def path(self, snapshot_id: str) -> str:
        """Return the file path for a snapshot ID."""
        assert_safe_snapshot_id(snapshot_id=snapshot_id)
        return os.path.join(self.directory, f'{snapshot_id}.json')

    def read_sync(self, snapshot_id: str) -> SessionSnapshot | None:
        """Read and validate a snapshot from disk synchronously."""
        path = self.path(snapshot_id)
        if not os.path.exists(path):
            return None
        with open(path, encoding='utf-8') as f:
            return SessionSnapshot.model_validate_json(f.read())

    def write_sync(self, snapshot: SessionSnapshot) -> None:
        """Atomically write a snapshot to disk synchronously."""
        path = self.path(snapshot.snapshot_id)
        temp_path = path + '.tmp'
        with open(temp_path, 'w', encoding='utf-8') as f:
            f.write(snapshot.model_dump_json(indent=2))
        os.replace(temp_path, path)

    def delete_sync(self, snapshot_id: str) -> None:
        """Delete a snapshot file, tolerating one that's already gone."""
        try:
            os.remove(self.path(snapshot_id))
        except FileNotFoundError:
            pass

    def prune_chain_sync(self, leaf: SessionSnapshot) -> None:
        """Trim a chat's ancestry to the newest ``max_persisted_chain_length`` turns.

        Walks ``parent_id`` back from the just-written snapshot and deletes the
        oldest links past the cap. The retained oldest snapshot keeps pointing at
        its (now-deleted) parent, so history reconstruction simply stops at the
        window's edge.
        """
        cap = self.max_persisted_chain_length
        if not cap or cap <= 0:
            return
        chain: list[str] = []
        seen: set[str] = set()
        cur: SessionSnapshot | None = leaf
        # `seen` stops a corrupt/cyclic parent chain from looping forever (each
        # hop is a disk read), the same guard walk_back_to_resumable uses.
        while cur is not None and cur.snapshot_id not in seen:
            seen.add(cur.snapshot_id)
            chain.append(cur.snapshot_id)
            cur = self.read_sync(cur.parent_id) if cur.parent_id else None
        for snapshot_id in chain[cap:]:
            self.delete_sync(snapshot_id)

    def read_session_sync(self, session_id: str) -> list[SessionSnapshot]:
        """Read all snapshots for a session from disk synchronously."""
        out: list[SessionSnapshot] = []
        if not os.path.isdir(self.directory):
            return out
        for name in os.listdir(self.directory):
            if not name.endswith('.json'):
                continue
            try:
                with open(os.path.join(self.directory, name), encoding='utf-8') as f:
                    snap = SessionSnapshot.model_validate_json(f.read())
            except (OSError, ValueError):
                continue
            if session_id_of(snap) == session_id:
                out.append(snap)
        return out

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Return a snapshot by id, or the session's latest leaf, read from disk."""
        require_one_selector(snapshot_id=snapshot_id, session_id=session_id)
        async with self.lock:
            if snapshot_id is not None:
                return await asyncio.to_thread(self.read_sync, snapshot_id)

            assert session_id is not None
            owned = await asyncio.to_thread(self.read_session_sync, session_id)
            return select_leaf(snapshots=owned, session_id=session_id, reject_ambiguous=self.reject_ambiguous)

    async def save_snapshot(
        self,
        snapshot_id: str,
        fn: SaveFn,
        *,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Read-modify-write a snapshot on disk, prune the chain, and notify subscribers."""
        _ = context
        async with self.lock:
            existing = await asyncio.to_thread(self.read_sync, snapshot_id)
            next_snapshot = apply_save(existing=existing, snapshot_id=snapshot_id, fn=fn)
            if next_snapshot is None:
                return None
            if not session_id_of(next_snapshot):
                raise GenkitError(
                    status='INVALID_ARGUMENT',
                    message="FileSessionStore requires 'sessionId' on the snapshot.",
                    reason=ErrorReason.SESSION_ID_REQUIRED,
                )
            await asyncio.to_thread(self.write_sync, next_snapshot)
            if self.max_persisted_chain_length:
                await asyncio.to_thread(self.prune_chain_sync, next_snapshot)
            notify(subs=self.subs, snapshot_id=next_snapshot.snapshot_id, status=next_snapshot.status)
            return next_snapshot

    async def on_snapshot_status_change(
        self, snapshot_id: str, *, context: dict[str, Any] | None = None
    ) -> SnapshotStatusStream:
        """Return an iterator that yields this snapshot's status changes.

        Call ``aclose()`` (or ``contextlib.aclosing``) to unsubscribe early;
        natural end after a terminal status also unsubscribes.
        """
        async with self.lock:
            current = await asyncio.to_thread(self.read_sync, snapshot_id)
            q = await subscribe(subs=self.subs, snapshot_id=snapshot_id, current=current)

            async def on_close() -> None:
                async with self.lock:
                    qs = self.subs.get(snapshot_id)
                    if qs is None:
                        return
                    with contextlib.suppress(ValueError):
                        qs.remove(q)
                    if not qs:
                        self.subs.pop(snapshot_id, None)

            return iterate_statuses(q, on_close=on_close)

lock property

Return a loop-local asyncio.Lock for this store instance.

__init__(directory, *, reject_ambiguous_session=False, max_persisted_chain_length=None)

Create the store, ensuring directory exists.

See :class:InMemorySessionStore for reject_ambiguous_session.

max_persisted_chain_length caps how many snapshots of a chat's history stay on disk: once a chain grows past it, the oldest turns are deleted on each save so a long-lived conversation doesn't accumulate files forever. Resuming and continuing still work, but you lose the ability to rewind or branch past the retained window. Leave it unset to keep the full history.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def __init__(
    self,
    directory: str,
    *,
    reject_ambiguous_session: bool = False,
    max_persisted_chain_length: int | None = None,
) -> None:
    """Create the store, ensuring ``directory`` exists.

    See :class:`InMemorySessionStore` for ``reject_ambiguous_session``.

    ``max_persisted_chain_length`` caps how many snapshots of a chat's
    history stay on disk: once a chain grows past it, the oldest turns are
    deleted on each save so a long-lived conversation doesn't accumulate
    files forever. Resuming and continuing still work, but you lose the
    ability to rewind or branch past the retained window. Leave it unset to
    keep the full history.
    """
    self.reject_ambiguous = reject_ambiguous_session
    self.max_persisted_chain_length = max_persisted_chain_length
    self.directory = directory
    self.subs: Subs = {}
    os.makedirs(directory, exist_ok=True)

delete_sync(snapshot_id)

Delete a snapshot file, tolerating one that's already gone.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
 97
 98
 99
100
101
102
def delete_sync(self, snapshot_id: str) -> None:
    """Delete a snapshot file, tolerating one that's already gone."""
    try:
        os.remove(self.path(snapshot_id))
    except FileNotFoundError:
        pass

get_snapshot(*, snapshot_id=None, session_id=None, context=None) async

Return a snapshot by id, or the session's latest leaf, read from disk.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Return a snapshot by id, or the session's latest leaf, read from disk."""
    require_one_selector(snapshot_id=snapshot_id, session_id=session_id)
    async with self.lock:
        if snapshot_id is not None:
            return await asyncio.to_thread(self.read_sync, snapshot_id)

        assert session_id is not None
        owned = await asyncio.to_thread(self.read_session_sync, session_id)
        return select_leaf(snapshots=owned, session_id=session_id, reject_ambiguous=self.reject_ambiguous)

on_snapshot_status_change(snapshot_id, *, context=None) async

Return an iterator that yields this snapshot's status changes.

Call aclose() (or contextlib.aclosing) to unsubscribe early; natural end after a terminal status also unsubscribes.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
async def on_snapshot_status_change(
    self, snapshot_id: str, *, context: dict[str, Any] | None = None
) -> SnapshotStatusStream:
    """Return an iterator that yields this snapshot's status changes.

    Call ``aclose()`` (or ``contextlib.aclosing``) to unsubscribe early;
    natural end after a terminal status also unsubscribes.
    """
    async with self.lock:
        current = await asyncio.to_thread(self.read_sync, snapshot_id)
        q = await subscribe(subs=self.subs, snapshot_id=snapshot_id, current=current)

        async def on_close() -> None:
            async with self.lock:
                qs = self.subs.get(snapshot_id)
                if qs is None:
                    return
                with contextlib.suppress(ValueError):
                    qs.remove(q)
                if not qs:
                    self.subs.pop(snapshot_id, None)

        return iterate_statuses(q, on_close=on_close)

path(snapshot_id)

Return the file path for a snapshot ID.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
76
77
78
79
def path(self, snapshot_id: str) -> str:
    """Return the file path for a snapshot ID."""
    assert_safe_snapshot_id(snapshot_id=snapshot_id)
    return os.path.join(self.directory, f'{snapshot_id}.json')

prune_chain_sync(leaf)

Trim a chat's ancestry to the newest max_persisted_chain_length turns.

Walks parent_id back from the just-written snapshot and deletes the oldest links past the cap. The retained oldest snapshot keeps pointing at its (now-deleted) parent, so history reconstruction simply stops at the window's edge.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
def prune_chain_sync(self, leaf: SessionSnapshot) -> None:
    """Trim a chat's ancestry to the newest ``max_persisted_chain_length`` turns.

    Walks ``parent_id`` back from the just-written snapshot and deletes the
    oldest links past the cap. The retained oldest snapshot keeps pointing at
    its (now-deleted) parent, so history reconstruction simply stops at the
    window's edge.
    """
    cap = self.max_persisted_chain_length
    if not cap or cap <= 0:
        return
    chain: list[str] = []
    seen: set[str] = set()
    cur: SessionSnapshot | None = leaf
    # `seen` stops a corrupt/cyclic parent chain from looping forever (each
    # hop is a disk read), the same guard walk_back_to_resumable uses.
    while cur is not None and cur.snapshot_id not in seen:
        seen.add(cur.snapshot_id)
        chain.append(cur.snapshot_id)
        cur = self.read_sync(cur.parent_id) if cur.parent_id else None
    for snapshot_id in chain[cap:]:
        self.delete_sync(snapshot_id)

read_session_sync(session_id)

Read all snapshots for a session from disk synchronously.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def read_session_sync(self, session_id: str) -> list[SessionSnapshot]:
    """Read all snapshots for a session from disk synchronously."""
    out: list[SessionSnapshot] = []
    if not os.path.isdir(self.directory):
        return out
    for name in os.listdir(self.directory):
        if not name.endswith('.json'):
            continue
        try:
            with open(os.path.join(self.directory, name), encoding='utf-8') as f:
                snap = SessionSnapshot.model_validate_json(f.read())
        except (OSError, ValueError):
            continue
        if session_id_of(snap) == session_id:
            out.append(snap)
    return out

read_sync(snapshot_id)

Read and validate a snapshot from disk synchronously.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
81
82
83
84
85
86
87
def read_sync(self, snapshot_id: str) -> SessionSnapshot | None:
    """Read and validate a snapshot from disk synchronously."""
    path = self.path(snapshot_id)
    if not os.path.exists(path):
        return None
    with open(path, encoding='utf-8') as f:
        return SessionSnapshot.model_validate_json(f.read())

save_snapshot(snapshot_id, fn, *, context=None) async

Read-modify-write a snapshot on disk, prune the chain, and notify subscribers.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
async def save_snapshot(
    self,
    snapshot_id: str,
    fn: SaveFn,
    *,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Read-modify-write a snapshot on disk, prune the chain, and notify subscribers."""
    _ = context
    async with self.lock:
        existing = await asyncio.to_thread(self.read_sync, snapshot_id)
        next_snapshot = apply_save(existing=existing, snapshot_id=snapshot_id, fn=fn)
        if next_snapshot is None:
            return None
        if not session_id_of(next_snapshot):
            raise GenkitError(
                status='INVALID_ARGUMENT',
                message="FileSessionStore requires 'sessionId' on the snapshot.",
                reason=ErrorReason.SESSION_ID_REQUIRED,
            )
        await asyncio.to_thread(self.write_sync, next_snapshot)
        if self.max_persisted_chain_length:
            await asyncio.to_thread(self.prune_chain_sync, next_snapshot)
        notify(subs=self.subs, snapshot_id=next_snapshot.snapshot_id, status=next_snapshot.status)
        return next_snapshot

write_sync(snapshot)

Atomically write a snapshot to disk synchronously.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_file_store.py
89
90
91
92
93
94
95
def write_sync(self, snapshot: SessionSnapshot) -> None:
    """Atomically write a snapshot to disk synchronously."""
    path = self.path(snapshot.snapshot_id)
    temp_path = path + '.tmp'
    with open(temp_path, 'w', encoding='utf-8') as f:
        f.write(snapshot.model_dump_json(indent=2))
    os.replace(temp_path, path)

HttpAgentTransport

Bases: genkit._ai._agents._client.AgentTransport[genkit._ai._agents._transports._http.StateT]

Client-side agent transport that talks to a remote agent over HTTP.

Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
class HttpAgentTransport(AgentTransport[StateT]):
    """Client-side agent transport that talks to a remote agent over HTTP."""

    def __init__(
        self,
        url: str,
        *,
        get_snapshot_url: str | None = None,
        abort_url: str | None = None,
        headers: HeadersProvider | None = None,
        state_management: StateManagement,
        timeout: float | None = DEFAULT_AGENT_TIMEOUT_SECONDS,
    ) -> None:
        """Initializes the HTTP transport.

        Args:
            url: Agent turn endpoint (e.g. ``/api/myAgent``).
            get_snapshot_url: ``getSnapshot`` route. Defaults to ``{url}/getSnapshot``.
            abort_url: ``abort`` route. Defaults to ``{url}/abort``.
            headers: Static headers, or a function called per request (sync or async).
            state_management: Declares server- vs client-managed state.
            timeout: Seconds to wait for the next bytes from the server. On a
                streamed turn this is the longest allowed gap between chunks,
                not a cap on the whole turn. ``None`` waits indefinitely.
                Connecting always gets 10 seconds.
        """
        self.url = url
        self.get_snapshot_url = get_snapshot_url or f'{url}/getSnapshot'
        self.abort_url = abort_url or f'{url}/abort'
        self.headers = headers
        self.state_management: StateManagement = state_management
        self._timeout = httpx.Timeout(timeout, connect=_CONNECT_TIMEOUT_SECONDS)
        self._background_tasks: set[asyncio.Task[Any]] = set()

    async def _resolve_headers(self) -> dict[str, str]:
        """Resolve caller headers for this request."""
        if self.headers is None:
            return {}
        if callable(self.headers):
            resolved = self.headers()
            if inspect.isawaitable(resolved):
                resolved = await resolved
            return dict(resolved)
        return dict(self.headers)

    async def _post_json(self, *, url: str, input_val: dict[str, Any]) -> Any:  # noqa: ANN401
        """POST JSON to a one-shot action endpoint and return the parsed body."""
        try:
            return await self._post_json_raw(url=url, input_val=input_val)
        except GenkitError:
            raise
        except Exception as e:
            raise transport_error(e) from e

    async def _post_json_raw(self, *, url: str, input_val: dict[str, Any]) -> Any:  # noqa: ANN401
        client = _agent_client()
        # Same callable/flow envelope as run_turn: handlers expect {"data": ...}.
        response = await client.post(
            url,
            json={'data': input_val},
            headers=await self._resolve_headers(),
            timeout=self._timeout,
        )
        if response.status_code == 404:
            return None
        if response.status_code != 200:
            body = response.text
            raise error_from_http(status_code=response.status_code, body=body)
        if not response.content:
            return None
        body = response.json()
        if isinstance(body, dict) and 'error' in body:
            raise error_from_wire(body['error'])
        if isinstance(body, dict) and 'result' in body:
            return body['result']
        return body

    def _lookup_payload(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> dict[str, str]:
        snapshot_id, session_id = parse_snapshot_lookup_kw(snapshot_id=snapshot_id, session_id=session_id)
        if snapshot_id is not None:
            return {'snapshotId': snapshot_id}
        assert session_id is not None
        return {'sessionId': session_id}

    async def run_turn(
        self,
        *,
        agent_input: AgentInput,
        init: AgentInit,
    ) -> tuple[AsyncIterable[AgentStreamChunk], Awaitable[AgentOutput]]:
        """Runs a single turn over HTTP using a streaming POST request."""
        client = _agent_client()

        # Callable/flow envelope used by expressHandler and FastAPI/Flask/Django
        # handlers: {"data": <AgentInput>, "init": <AgentInit>}. Streaming is
        # negotiated with Accept only (not ?stream=true).
        payload: dict[str, Any] = {
            'data': agent_input.model_dump(by_alias=True, exclude_none=True),
            'init': init.model_dump(by_alias=True, exclude_none=True),
        }

        output_future: asyncio.Future[AgentOutput] = asyncio.Future()
        stream_queue = CloseableQueue[AgentStreamChunk | Exception]()

        async def fetch_stream() -> None:
            try:
                # Accept/Content-Type win so a caller header can't break streaming.
                headers = {
                    **(await self._resolve_headers()),
                    'Accept': 'text/event-stream',
                    'Content-Type': 'application/json',
                }
                async with client.stream(
                    'POST',
                    self.url,
                    json=payload,
                    headers=headers,
                    timeout=self._timeout,
                ) as response:
                    if response.status_code != 200:
                        body = (await response.aread()).decode(errors='ignore')
                        raise error_from_http(status_code=response.status_code, body=body)

                    async for line in response.aiter_lines():
                        data = parse_stream_line(line)
                        if data is None:
                            continue

                        if 'result' in data:
                            output_val = AgentOutput.model_validate(data['result'])
                            if not output_future.done():
                                output_future.set_result(output_val)
                            break
                        if 'error' in data:
                            raise stream_error_from_payload(data)

                        chunk_payload = data['message'] if 'message' in data else data
                        chunk = AgentStreamChunk.model_validate(chunk_payload)
                        stream_queue.put_nowait(chunk)
                    else:
                        err = GenkitError(
                            status='UNAVAILABLE',
                            message='HTTP stream ended prematurely before agent turn completed',
                        )
                        if not output_future.done():
                            output_future.set_exception(err)
                        stream_queue.put_nowait(err)
            except Exception as e:
                err = transport_error(e)
                if not output_future.done():
                    output_future.set_exception(err)
                stream_queue.put_nowait(err)
            finally:
                # Wakes the stream consumer once buffered chunks drain, so the
                # generator ends cleanly on every path, not just the success one.
                stream_queue.close()

        # Aborting a turn is a client-side detach: the caller stops listening,
        # but we leave the streaming request running so the server turn finishes
        # and persists. Halting server-side work is a separate operation
        # (abort_snapshot), not part of running a turn.
        task = asyncio.create_task(fetch_stream())
        self._background_tasks.add(task)
        task.add_done_callback(self._background_tasks.discard)

        async def stream_generator() -> AsyncIterator[AgentStreamChunk]:
            async for chunk in stream_queue:
                if isinstance(chunk, Exception):
                    raise chunk
                yield chunk

        return stream_generator(), output_future

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
    ) -> SessionSnapshot | None:
        """Retrieves a session snapshot from the server."""
        result = await self._post_json(
            url=self.get_snapshot_url,
            input_val=self._lookup_payload(snapshot_id=snapshot_id, session_id=session_id),
        )
        if result is None:
            return None
        return _parse_response(SessionSnapshot, result, endpoint='getSnapshot')

    async def abort_snapshot(self, snapshot_id: str) -> SnapshotStatus | None:
        """Aborts the specified snapshot on the server."""
        result = await self._post_json(url=self.abort_url, input_val={'snapshotId': snapshot_id})
        if result is None:
            return None
        return _parse_response(AgentAbortResponse, result, endpoint='abort').status

__init__(url, *, get_snapshot_url=None, abort_url=None, headers=None, state_management, timeout=DEFAULT_AGENT_TIMEOUT_SECONDS)

Initializes the HTTP transport.

Parameters:

Name Type Description Default
url str

Agent turn endpoint (e.g. /api/myAgent).

required
get_snapshot_url str | None

getSnapshot route. Defaults to {url}/getSnapshot.

None
abort_url str | None

abort route. Defaults to {url}/abort.

None
headers genkit._ai._agents._transports._http.HeadersProvider | None

Static headers, or a function called per request (sync or async).

None
state_management genkit._ai._agents._types.StateManagement

Declares server- vs client-managed state.

required
timeout float | None

Seconds to wait for the next bytes from the server. On a streamed turn this is the longest allowed gap between chunks, not a cap on the whole turn. None waits indefinitely. Connecting always gets 10 seconds.

genkit._ai._agents._transports._http.DEFAULT_AGENT_TIMEOUT_SECONDS
Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
def __init__(
    self,
    url: str,
    *,
    get_snapshot_url: str | None = None,
    abort_url: str | None = None,
    headers: HeadersProvider | None = None,
    state_management: StateManagement,
    timeout: float | None = DEFAULT_AGENT_TIMEOUT_SECONDS,
) -> None:
    """Initializes the HTTP transport.

    Args:
        url: Agent turn endpoint (e.g. ``/api/myAgent``).
        get_snapshot_url: ``getSnapshot`` route. Defaults to ``{url}/getSnapshot``.
        abort_url: ``abort`` route. Defaults to ``{url}/abort``.
        headers: Static headers, or a function called per request (sync or async).
        state_management: Declares server- vs client-managed state.
        timeout: Seconds to wait for the next bytes from the server. On a
            streamed turn this is the longest allowed gap between chunks,
            not a cap on the whole turn. ``None`` waits indefinitely.
            Connecting always gets 10 seconds.
    """
    self.url = url
    self.get_snapshot_url = get_snapshot_url or f'{url}/getSnapshot'
    self.abort_url = abort_url or f'{url}/abort'
    self.headers = headers
    self.state_management: StateManagement = state_management
    self._timeout = httpx.Timeout(timeout, connect=_CONNECT_TIMEOUT_SECONDS)
    self._background_tasks: set[asyncio.Task[Any]] = set()

abort_snapshot(snapshot_id) async

Aborts the specified snapshot on the server.

Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
310
311
312
313
314
315
async def abort_snapshot(self, snapshot_id: str) -> SnapshotStatus | None:
    """Aborts the specified snapshot on the server."""
    result = await self._post_json(url=self.abort_url, input_val={'snapshotId': snapshot_id})
    if result is None:
        return None
    return _parse_response(AgentAbortResponse, result, endpoint='abort').status

get_snapshot(*, snapshot_id=None, session_id=None) async

Retrieves a session snapshot from the server.

Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
295
296
297
298
299
300
301
302
303
304
305
306
307
308
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
) -> SessionSnapshot | None:
    """Retrieves a session snapshot from the server."""
    result = await self._post_json(
        url=self.get_snapshot_url,
        input_val=self._lookup_payload(snapshot_id=snapshot_id, session_id=session_id),
    )
    if result is None:
        return None
    return _parse_response(SessionSnapshot, result, endpoint='getSnapshot')

run_turn(*, agent_input, init) async

Runs a single turn over HTTP using a streaming POST request.

Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
async def run_turn(
    self,
    *,
    agent_input: AgentInput,
    init: AgentInit,
) -> tuple[AsyncIterable[AgentStreamChunk], Awaitable[AgentOutput]]:
    """Runs a single turn over HTTP using a streaming POST request."""
    client = _agent_client()

    # Callable/flow envelope used by expressHandler and FastAPI/Flask/Django
    # handlers: {"data": <AgentInput>, "init": <AgentInit>}. Streaming is
    # negotiated with Accept only (not ?stream=true).
    payload: dict[str, Any] = {
        'data': agent_input.model_dump(by_alias=True, exclude_none=True),
        'init': init.model_dump(by_alias=True, exclude_none=True),
    }

    output_future: asyncio.Future[AgentOutput] = asyncio.Future()
    stream_queue = CloseableQueue[AgentStreamChunk | Exception]()

    async def fetch_stream() -> None:
        try:
            # Accept/Content-Type win so a caller header can't break streaming.
            headers = {
                **(await self._resolve_headers()),
                'Accept': 'text/event-stream',
                'Content-Type': 'application/json',
            }
            async with client.stream(
                'POST',
                self.url,
                json=payload,
                headers=headers,
                timeout=self._timeout,
            ) as response:
                if response.status_code != 200:
                    body = (await response.aread()).decode(errors='ignore')
                    raise error_from_http(status_code=response.status_code, body=body)

                async for line in response.aiter_lines():
                    data = parse_stream_line(line)
                    if data is None:
                        continue

                    if 'result' in data:
                        output_val = AgentOutput.model_validate(data['result'])
                        if not output_future.done():
                            output_future.set_result(output_val)
                        break
                    if 'error' in data:
                        raise stream_error_from_payload(data)

                    chunk_payload = data['message'] if 'message' in data else data
                    chunk = AgentStreamChunk.model_validate(chunk_payload)
                    stream_queue.put_nowait(chunk)
                else:
                    err = GenkitError(
                        status='UNAVAILABLE',
                        message='HTTP stream ended prematurely before agent turn completed',
                    )
                    if not output_future.done():
                        output_future.set_exception(err)
                    stream_queue.put_nowait(err)
        except Exception as e:
            err = transport_error(e)
            if not output_future.done():
                output_future.set_exception(err)
            stream_queue.put_nowait(err)
        finally:
            # Wakes the stream consumer once buffered chunks drain, so the
            # generator ends cleanly on every path, not just the success one.
            stream_queue.close()

    # Aborting a turn is a client-side detach: the caller stops listening,
    # but we leave the streaming request running so the server turn finishes
    # and persists. Halting server-side work is a separate operation
    # (abort_snapshot), not part of running a turn.
    task = asyncio.create_task(fetch_stream())
    self._background_tasks.add(task)
    task.add_done_callback(self._background_tasks.discard)

    async def stream_generator() -> AsyncIterator[AgentStreamChunk]:
        async for chunk in stream_queue:
            if isinstance(chunk, Exception):
                raise chunk
            yield chunk

    return stream_generator(), output_future

InMemorySessionStore

Bases: genkit._ai._agents._session.SessionStoreLock, genkit._ai._agents._session.SessionStore[genkit._ai._agents._session.StateT], genkit._ai._agents._session.SnapshotSubscriber, typing.Generic[genkit._ai._agents._session.StateT]

In-memory snapshot store. State is lost when the process exits.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_inmemory_store.py
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
class InMemorySessionStore(SessionStoreLock, SessionStore[StateT], SnapshotSubscriber, Generic[StateT]):
    """In-memory snapshot store. State is lost when the process exits."""

    def __init__(self, *, reject_ambiguous_session: bool = False) -> None:
        """Create the store.

        When ``reject_ambiguous_session`` is set, a ``session_id`` lookup on a
        history that has forked (more than one leaf) raises instead of picking
        the most recent branch — useful when accidental branching should surface
        loudly.
        """
        self.reject_ambiguous = reject_ambiguous_session
        self.snapshots: dict[str, SessionSnapshot] = {}
        self.subs: Subs = {}

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Return a snapshot by id, or the session's latest leaf, as a deep copy."""
        require_one_selector(snapshot_id=snapshot_id, session_id=session_id)
        async with self.lock:
            if snapshot_id is not None:
                snap = self.snapshots.get(snapshot_id)
                return _copy_snapshot(snap) if snap is not None else None

            assert session_id is not None
            owned = [snap for snap in self.snapshots.values() if session_id_of(snap) == session_id]
            leaf = select_leaf(snapshots=owned, session_id=session_id, reject_ambiguous=self.reject_ambiguous)
            return _copy_snapshot(leaf) if leaf is not None else None

    async def save_snapshot(
        self,
        snapshot_id: str,
        fn: SaveFn,
        *,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Read-modify-write a snapshot in memory and notify status subscribers."""
        _ = context
        async with self.lock:
            existing = self.snapshots.get(snapshot_id)
            next_snapshot = apply_save(
                existing=_copy_snapshot(existing) if existing is not None else None,
                snapshot_id=snapshot_id,
                fn=fn,
            )
            if next_snapshot is None:
                return None
            self.snapshots[next_snapshot.snapshot_id] = _copy_snapshot(next_snapshot)
            notify(subs=self.subs, snapshot_id=next_snapshot.snapshot_id, status=next_snapshot.status)
            return next_snapshot

    async def on_snapshot_status_change(
        self, snapshot_id: str, *, context: dict[str, Any] | None = None
    ) -> SnapshotStatusStream:
        """Return an iterator that yields this snapshot's status changes.

        Call ``aclose()`` (or ``contextlib.aclosing``) to unsubscribe early;
        natural end after a terminal status also unsubscribes.
        """
        async with self.lock:
            current = self.snapshots.get(snapshot_id)
            q = await subscribe(subs=self.subs, snapshot_id=snapshot_id, current=current)

            async def on_close() -> None:
                async with self.lock:
                    qs = self.subs.get(snapshot_id)
                    if qs is None:
                        return
                    with contextlib.suppress(ValueError):
                        qs.remove(q)
                    if not qs:
                        self.subs.pop(snapshot_id, None)

            return iterate_statuses(q, on_close=on_close)

lock property

Return a loop-local asyncio.Lock for this store instance.

__init__(*, reject_ambiguous_session=False)

Create the store.

When reject_ambiguous_session is set, a session_id lookup on a history that has forked (more than one leaf) raises instead of picking the most recent branch — useful when accidental branching should surface loudly.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_inmemory_store.py
65
66
67
68
69
70
71
72
73
74
75
def __init__(self, *, reject_ambiguous_session: bool = False) -> None:
    """Create the store.

    When ``reject_ambiguous_session`` is set, a ``session_id`` lookup on a
    history that has forked (more than one leaf) raises instead of picking
    the most recent branch — useful when accidental branching should surface
    loudly.
    """
    self.reject_ambiguous = reject_ambiguous_session
    self.snapshots: dict[str, SessionSnapshot] = {}
    self.subs: Subs = {}

get_snapshot(*, snapshot_id=None, session_id=None, context=None) async

Return a snapshot by id, or the session's latest leaf, as a deep copy.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_inmemory_store.py
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Return a snapshot by id, or the session's latest leaf, as a deep copy."""
    require_one_selector(snapshot_id=snapshot_id, session_id=session_id)
    async with self.lock:
        if snapshot_id is not None:
            snap = self.snapshots.get(snapshot_id)
            return _copy_snapshot(snap) if snap is not None else None

        assert session_id is not None
        owned = [snap for snap in self.snapshots.values() if session_id_of(snap) == session_id]
        leaf = select_leaf(snapshots=owned, session_id=session_id, reject_ambiguous=self.reject_ambiguous)
        return _copy_snapshot(leaf) if leaf is not None else None

on_snapshot_status_change(snapshot_id, *, context=None) async

Return an iterator that yields this snapshot's status changes.

Call aclose() (or contextlib.aclosing) to unsubscribe early; natural end after a terminal status also unsubscribes.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_inmemory_store.py
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
async def on_snapshot_status_change(
    self, snapshot_id: str, *, context: dict[str, Any] | None = None
) -> SnapshotStatusStream:
    """Return an iterator that yields this snapshot's status changes.

    Call ``aclose()`` (or ``contextlib.aclosing``) to unsubscribe early;
    natural end after a terminal status also unsubscribes.
    """
    async with self.lock:
        current = self.snapshots.get(snapshot_id)
        q = await subscribe(subs=self.subs, snapshot_id=snapshot_id, current=current)

        async def on_close() -> None:
            async with self.lock:
                qs = self.subs.get(snapshot_id)
                if qs is None:
                    return
                with contextlib.suppress(ValueError):
                    qs.remove(q)
                if not qs:
                    self.subs.pop(snapshot_id, None)

        return iterate_statuses(q, on_close=on_close)

save_snapshot(snapshot_id, fn, *, context=None) async

Read-modify-write a snapshot in memory and notify status subscribers.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_inmemory_store.py
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
async def save_snapshot(
    self,
    snapshot_id: str,
    fn: SaveFn,
    *,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Read-modify-write a snapshot in memory and notify status subscribers."""
    _ = context
    async with self.lock:
        existing = self.snapshots.get(snapshot_id)
        next_snapshot = apply_save(
            existing=_copy_snapshot(existing) if existing is not None else None,
            snapshot_id=snapshot_id,
            fn=fn,
        )
        if next_snapshot is None:
            return None
        self.snapshots[next_snapshot.snapshot_id] = _copy_snapshot(next_snapshot)
        notify(subs=self.subs, snapshot_id=next_snapshot.snapshot_id, status=next_snapshot.status)
        return next_snapshot

JsonPatchOp

Bases: genkit._core._compat.StrEnum

JsonPatchOp data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
58
59
60
61
62
63
64
65
66
class JsonPatchOp(StrEnum):
    """JsonPatchOp data type class."""

    ADD = 'add'
    REMOVE = 'remove'
    REPLACE = 'replace'
    MOVE = 'move'
    COPY = 'copy'
    TEST = 'test'

JsonPatchOperation

Bases: genkit._core._base.GenkitModel

Model for jsonpatchoperation data.

Source code in packages/genkit/src/genkit/_core/_typing.py
242
243
244
245
246
247
248
249
250
251
class JsonPatchOperation(GenkitModel):
    """Model for jsonpatchoperation data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    op: JsonPatchOp = Field(...)
    path: str = Field(...)
    from_: str | None = Field(default=None, alias='from')
    value: Any | None = Field(default=None)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

Session

Bases: typing.Generic[genkit._ai._agents._session.StateT]

Holds conversation state with asyncio-safe read/write access.

Parameterize with a custom-state type when agents carry typed custom blobs (Session[MyState]). Wire storage stays SessionState.custom.

version bumps on every mutation so the runtime can skip redundant snapshot writes without deep-comparing state.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
class Session(Generic[StateT]):
    """Holds conversation state with asyncio-safe read/write access.

    Parameterize with a custom-state type when agents carry typed ``custom``
    blobs (``Session[MyState]``). Wire storage stays ``SessionState.custom``.

    ``version`` bumps on every mutation so the runtime can skip redundant
    snapshot writes without deep-comparing state.
    """

    def __init__(self, initial_state: SessionState | None = None) -> None:
        self.lock = asyncio.Lock()
        # Own a copy so minting session_id (or later mutations) never reaches
        # back into a caller's AgentInit.state / snapshot blob.
        state = initial_state.model_copy(deep=True) if initial_state is not None else SessionState()
        # Every conversation needs a stable id for trace correlation and so
        # client-managed state is self-describing from the first turn.
        if not state.session_id:
            state.session_id = str(uuid4())
        self.session_state: SessionState = state
        self.version: int = 0
        self.custom_changed_listeners: list[Callable[[], Awaitable[None]]] = []
        self.artifact_changed_listeners: list[Callable[[Artifact], Awaitable[None]]] = []

    def on_custom_changed(self, listener: Callable[[], Awaitable[None]]) -> None:
        """Register a callback invoked after ``update_custom`` mutates state."""
        self.custom_changed_listeners.append(listener)

    def on_artifact_changed(self, listener: Callable[[Artifact], Awaitable[None]]) -> None:
        """Register a callback invoked after ``add_artifacts`` mutates state."""
        self.artifact_changed_listeners.append(listener)

    async def notify_custom_changed(self) -> None:
        for listener in self.custom_changed_listeners:
            await listener()

    async def notify_artifact_changed(self, artifact: Artifact) -> None:
        for listener in self.artifact_changed_listeners:
            await listener(artifact)

    async def state(self) -> SessionState:
        """Deep copy of current state."""
        async with self.lock:
            return self.session_state.model_copy(deep=True)

    async def get_messages(self) -> list[Message]:
        async with self.lock:
            return list(self.session_state.messages or [])

    async def add_messages(self, messages: list[Message]) -> None:
        async with self.lock:
            if self.session_state.messages is None:
                self.session_state.messages = []
            self.session_state.messages.extend(messages)
            self.version += 1

    async def set_messages(self, messages: list[Message]) -> None:
        async with self.lock:
            self.session_state.messages = list(messages)
            self.version += 1

    async def get_custom(self) -> StateT | None:
        async with self.lock:
            return cast(StateT | None, self.session_state.custom)

    async def update_custom(self, fn: Callable[[StateT | None], StateT]) -> None:
        async with self.lock:
            self.session_state.custom = fn(cast(StateT | None, self.session_state.custom))
            self.version += 1
        await self.notify_custom_changed()

    async def get_artifacts(self) -> list[Artifact]:
        async with self.lock:
            return list(self.session_state.artifacts or [])

    async def add_artifacts(self, artifacts: list[Artifact]) -> None:
        """Append artifacts; replace by name if artifact.name already exists."""
        changed: list[Artifact] = []
        async with self.lock:
            if self.session_state.artifacts is None:
                self.session_state.artifacts = []
            for art in artifacts:
                replaced = False
                if art.name:
                    for i, existing in enumerate(self.session_state.artifacts):
                        if existing.name == art.name:
                            self.session_state.artifacts[i] = art
                            replaced = True
                            break
                if not replaced:
                    self.session_state.artifacts.append(art)
                changed.append(art)
            self.version += 1
        for art in changed:
            await self.notify_artifact_changed(art)

add_artifacts(artifacts) async

Append artifacts; replace by name if artifact.name already exists.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
async def add_artifacts(self, artifacts: list[Artifact]) -> None:
    """Append artifacts; replace by name if artifact.name already exists."""
    changed: list[Artifact] = []
    async with self.lock:
        if self.session_state.artifacts is None:
            self.session_state.artifacts = []
        for art in artifacts:
            replaced = False
            if art.name:
                for i, existing in enumerate(self.session_state.artifacts):
                    if existing.name == art.name:
                        self.session_state.artifacts[i] = art
                        replaced = True
                        break
            if not replaced:
                self.session_state.artifacts.append(art)
            changed.append(art)
        self.version += 1
    for art in changed:
        await self.notify_artifact_changed(art)

on_artifact_changed(listener)

Register a callback invoked after add_artifacts mutates state.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
251
252
253
def on_artifact_changed(self, listener: Callable[[Artifact], Awaitable[None]]) -> None:
    """Register a callback invoked after ``add_artifacts`` mutates state."""
    self.artifact_changed_listeners.append(listener)

on_custom_changed(listener)

Register a callback invoked after update_custom mutates state.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
247
248
249
def on_custom_changed(self, listener: Callable[[], Awaitable[None]]) -> None:
    """Register a callback invoked after ``update_custom`` mutates state."""
    self.custom_changed_listeners.append(listener)

state() async

Deep copy of current state.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
263
264
265
266
async def state(self) -> SessionState:
    """Deep copy of current state."""
    async with self.lock:
        return self.session_state.model_copy(deep=True)

SessionRunner

Bases: typing.Generic[genkit._ai._agents._session.StateT]

Per-turn input loop for one agent invocation.

AgentFn calls session_runner.run(handle_turn); after each turn the runtime emits snapshots and turnEnd chunks via on_end_turn.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
class SessionRunner(Generic[StateT]):
    """Per-turn input loop for one agent invocation.

    ``AgentFn`` calls ``session_runner.run(handle_turn)``; after each turn the runtime
    emits snapshots and ``turnEnd`` chunks via ``on_end_turn``.
    """

    def __init__(
        self,
        *,
        session: Session[StateT],
        turn_inputs: CloseableQueue[AgentInput],
        store: SessionStore | None = None,
        get_parent_snapshot_id: Callable[[], str | None] | None = None,
        on_begin_turn: Callable[[], Awaitable[None]] | None = None,
        on_end_turn: Callable[[AgentFinishReason | None], Awaitable[str | None]] | None = None,
        agent_name: str | None = None,
    ) -> None:
        self.session = session
        # Names the agent in the server-side log when a turn error is redacted.
        self._agent_name = agent_name
        self.turn_inputs = turn_inputs
        self.store = store
        self.get_parent_snapshot_id = get_parent_snapshot_id
        self.on_begin_turn = on_begin_turn
        self.on_end_turn = on_end_turn
        self.turn_index: int = 0
        self.last_turn_finish_reason: AgentFinishReason | None = None
        self.last_turn_error: Failure | None = None
        self.last_good_state: SessionState | None = None
        self.last_good_state_version: int | None = None
        self.last_good_finish_reason: AgentFinishReason | None = None
        # Detach may pre-reserve the in-flight id; the next turn consumes it.
        self.new_snapshot_id: str | None = None
        # Id reserved for the turn currently running (None without a store).
        self.current_turn_snapshot_id: str | None = None

    async def seed_last_good_state(self) -> None:
        """Capture initial session state as the fallback for first-turn failures."""
        self.last_good_state = await self.session.state()
        self.last_good_state_version = self.session.version

    async def run(
        self,
        fn: Callable[[AgentInput, TurnContext], Awaitable[TurnResult | None]],
    ) -> None:
        """Consume inputs from the intake queue, calling fn for each turn.

        Each turn is wrapped in a trace span ``runTurn-N`` (1-based). Inbound
        messages are automatically added to the session before fn is called.
        When a store is configured the turn's snapshot id is reserved up front
        and handed to ``fn`` via ``TurnContext`` so handlers can name external
        resources before the turn runs; the snapshot at turn end reuses that id.
        After fn returns, on_end_turn is called (snapshot + chunk emission)
        and turn_index is incremented.

        Turn failures resolve gracefully: the invocation finishes with
        ``finish_reason=failed`` and ``error`` on ``AgentOutput``, and the
        turn loop stops.
        """
        async for inp in self.turn_inputs:
            # Auto-add inbound messages to session history
            if inp.message:
                await self.session.add_messages([inp.message])

            parent_snapshot_id = self.get_parent_snapshot_id() if self.get_parent_snapshot_id else None
            # Reserve the turn's snapshot id up front (when a store is configured)
            # so the handler can name snapshot-correlated external resources
            # before the turn runs. Detach may have already reserved one; reuse it.
            if self.store is not None and self.new_snapshot_id is None:
                self.new_snapshot_id = reserve_snapshot_id()
            turn_snapshot_id = self.new_snapshot_id
            self.new_snapshot_id = None
            self.current_turn_snapshot_id = turn_snapshot_id

            turn_ctx = TurnContext(
                snapshot_id=turn_snapshot_id,
                parent_snapshot_id=parent_snapshot_id,
                turn_index=self.turn_index,
            )

            if self.on_begin_turn is not None:
                await self.on_begin_turn()

            try:

                async def body(span: SpanContext, turn_input: AgentInput = inp, ctx: TurnContext = turn_ctx) -> object:
                    try:
                        turn_result = await fn(turn_input, ctx)
                    except (Interrupt, TaskGroupError) as exc:
                        # No generate loop here to pause. Convert inside the
                        # span so runTurn-N records the failure.
                        failure = interrupt_escape_error(exc)
                        if failure is None:
                            raise
                        raise failure from exc
                    finish_reason = turn_result.finish_reason if turn_result else None
                    self.last_turn_finish_reason = finish_reason
                    self.last_turn_error = None

                    snapshot_id: str | None = None
                    if self.on_end_turn is not None:
                        snapshot_id = await self.on_end_turn(finish_reason)

                    # Span output is the session state this turn committed
                    # (messages, artifacts, custom) so a trace can show what
                    # changed without reading the client response.
                    state = await self.session.state()
                    if snapshot_id:
                        span.set_metadata({'agent:snapshotId': snapshot_id})
                    return {'state': state.model_dump(by_alias=True, exclude_none=True, mode='json')}

                await run_in_new_span(
                    f'runTurn-{self.turn_index + 1}',
                    body,
                    action_type='flowStep',
                    input=inp,
                )

                self.last_good_state = await self.session.state()
                self.last_good_state_version = self.session.version
                self.last_good_finish_reason = self.last_turn_finish_reason
                self.turn_index += 1
            except (Exception, Interrupt, TaskGroupError) as exc:
                # body converts the turn's own Interrupt; this covers one
                # raised from a hook outside it.
                failure = interrupt_escape_error(exc)
                if failure is not None:
                    turn_error: Exception = failure
                elif isinstance(exc, Exception):
                    turn_error = exc
                else:
                    raise
                self.last_turn_finish_reason = AgentFinishReason.FAILED
                self.last_turn_error = to_error_details(turn_error, agent=self._agent_name)

                if self.on_end_turn is not None:
                    await self.on_end_turn(AgentFinishReason.FAILED)

                break
            finally:
                self.current_turn_snapshot_id = None

    async def result(self) -> AgentResult:
        """Last message, artifacts, and finish reason from the current session."""
        state = await self.session.state()
        msg = state.messages[-1] if state.messages else None
        arts = list(state.artifacts) if state.artifacts else []
        return AgentResult(
            message=msg,
            artifacts=arts,
            finish_reason=self.last_turn_finish_reason,
        )

    # --- Session passthrough helpers ---

    async def get_messages(self) -> list[Message]:
        return await self.session.get_messages()

    async def set_messages(self, messages: list[Message]) -> None:
        await self.session.set_messages(messages)

    async def add_messages(self, messages: list[Message]) -> None:
        await self.session.add_messages(messages)

    async def get_artifacts(self) -> list[Artifact]:
        return await self.session.get_artifacts()

    async def add_artifacts(self, artifacts: list[Artifact]) -> None:
        await self.session.add_artifacts(artifacts)

    async def get_custom(self) -> StateT | None:
        return await self.session.get_custom()

    async def update_custom(self, fn: Callable[[StateT | None], StateT]) -> None:
        await self.session.update_custom(fn)

result() async

Last message, artifacts, and finish reason from the current session.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
245
246
247
248
249
250
251
252
253
254
async def result(self) -> AgentResult:
    """Last message, artifacts, and finish reason from the current session."""
    state = await self.session.state()
    msg = state.messages[-1] if state.messages else None
    arts = list(state.artifacts) if state.artifacts else []
    return AgentResult(
        message=msg,
        artifacts=arts,
        finish_reason=self.last_turn_finish_reason,
    )

run(fn) async

Consume inputs from the intake queue, calling fn for each turn.

Each turn is wrapped in a trace span runTurn-N (1-based). Inbound messages are automatically added to the session before fn is called. When a store is configured the turn's snapshot id is reserved up front and handed to fn via TurnContext so handlers can name external resources before the turn runs; the snapshot at turn end reuses that id. After fn returns, on_end_turn is called (snapshot + chunk emission) and turn_index is incremented.

Turn failures resolve gracefully: the invocation finishes with finish_reason=failed and error on AgentOutput, and the turn loop stops.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
async def run(
    self,
    fn: Callable[[AgentInput, TurnContext], Awaitable[TurnResult | None]],
) -> None:
    """Consume inputs from the intake queue, calling fn for each turn.

    Each turn is wrapped in a trace span ``runTurn-N`` (1-based). Inbound
    messages are automatically added to the session before fn is called.
    When a store is configured the turn's snapshot id is reserved up front
    and handed to ``fn`` via ``TurnContext`` so handlers can name external
    resources before the turn runs; the snapshot at turn end reuses that id.
    After fn returns, on_end_turn is called (snapshot + chunk emission)
    and turn_index is incremented.

    Turn failures resolve gracefully: the invocation finishes with
    ``finish_reason=failed`` and ``error`` on ``AgentOutput``, and the
    turn loop stops.
    """
    async for inp in self.turn_inputs:
        # Auto-add inbound messages to session history
        if inp.message:
            await self.session.add_messages([inp.message])

        parent_snapshot_id = self.get_parent_snapshot_id() if self.get_parent_snapshot_id else None
        # Reserve the turn's snapshot id up front (when a store is configured)
        # so the handler can name snapshot-correlated external resources
        # before the turn runs. Detach may have already reserved one; reuse it.
        if self.store is not None and self.new_snapshot_id is None:
            self.new_snapshot_id = reserve_snapshot_id()
        turn_snapshot_id = self.new_snapshot_id
        self.new_snapshot_id = None
        self.current_turn_snapshot_id = turn_snapshot_id

        turn_ctx = TurnContext(
            snapshot_id=turn_snapshot_id,
            parent_snapshot_id=parent_snapshot_id,
            turn_index=self.turn_index,
        )

        if self.on_begin_turn is not None:
            await self.on_begin_turn()

        try:

            async def body(span: SpanContext, turn_input: AgentInput = inp, ctx: TurnContext = turn_ctx) -> object:
                try:
                    turn_result = await fn(turn_input, ctx)
                except (Interrupt, TaskGroupError) as exc:
                    # No generate loop here to pause. Convert inside the
                    # span so runTurn-N records the failure.
                    failure = interrupt_escape_error(exc)
                    if failure is None:
                        raise
                    raise failure from exc
                finish_reason = turn_result.finish_reason if turn_result else None
                self.last_turn_finish_reason = finish_reason
                self.last_turn_error = None

                snapshot_id: str | None = None
                if self.on_end_turn is not None:
                    snapshot_id = await self.on_end_turn(finish_reason)

                # Span output is the session state this turn committed
                # (messages, artifacts, custom) so a trace can show what
                # changed without reading the client response.
                state = await self.session.state()
                if snapshot_id:
                    span.set_metadata({'agent:snapshotId': snapshot_id})
                return {'state': state.model_dump(by_alias=True, exclude_none=True, mode='json')}

            await run_in_new_span(
                f'runTurn-{self.turn_index + 1}',
                body,
                action_type='flowStep',
                input=inp,
            )

            self.last_good_state = await self.session.state()
            self.last_good_state_version = self.session.version
            self.last_good_finish_reason = self.last_turn_finish_reason
            self.turn_index += 1
        except (Exception, Interrupt, TaskGroupError) as exc:
            # body converts the turn's own Interrupt; this covers one
            # raised from a hook outside it.
            failure = interrupt_escape_error(exc)
            if failure is not None:
                turn_error: Exception = failure
            elif isinstance(exc, Exception):
                turn_error = exc
            else:
                raise
            self.last_turn_finish_reason = AgentFinishReason.FAILED
            self.last_turn_error = to_error_details(turn_error, agent=self._agent_name)

            if self.on_end_turn is not None:
                await self.on_end_turn(AgentFinishReason.FAILED)

            break
        finally:
            self.current_turn_snapshot_id = None

seed_last_good_state() async

Capture initial session state as the fallback for first-turn failures.

Source code in packages/genkit/src/genkit/_ai/_agents/_runtime.py
139
140
141
142
async def seed_last_good_state(self) -> None:
    """Capture initial session state as the fallback for first-turn failures."""
    self.last_good_state = await self.session.state()
    self.last_good_state_version = self.session.version

SessionSnapshot

Bases: genkit._core._base.GenkitModel

Snapshot whose state uses the public SessionState type.

Source code in packages/genkit/src/genkit/_core/_model.py
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
class SessionSnapshot(GenkitModel):
    """Snapshot whose state uses the public SessionState type."""

    snapshot_id: str
    session_id: str | None = None
    parent_id: str | None = None
    created_at: str
    updated_at: str | None = None
    heartbeat_at: str | None = None
    status: SnapshotStatus | None = None
    finish_reason: AgentFinishReason | None = None
    error: Failure | None = None
    state: SessionState | None = None

    @field_validator('state', mode='before')
    @classmethod
    def _wrap_state(cls, v: object) -> object:
        if v is None:
            return v
        return as_session_state(v)

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

SessionState

Bases: genkit._core._base.GenkitModel

Session state whose conversation uses Message and Artifact.

Source code in packages/genkit/src/genkit/_core/_model.py
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
class SessionState(GenkitModel):
    """Session state whose conversation uses Message and Artifact."""

    session_id: str | None = None
    messages: list[Message] | None = None
    custom: Any | None = Field(default=None)
    artifacts: list[Artifact] | None = None
    usage: GenerationUsage | None = None

    @field_validator('messages', mode='before')
    @classmethod
    def _wrap_messages(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_message(m) for m in v]

    @field_validator('artifacts', mode='before')
    @classmethod
    def _wrap_artifacts(cls, v: object) -> object:
        if not isinstance(v, list):
            return v
        return [as_artifact(a) for a in v]

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

SessionStore

Bases: typing.Protocol, typing.Generic[genkit._ai._agents._session.StateT_co]

Structural interface for snapshot persistence backends.

Minimum: get_snapshot + save_snapshot. Optional detach/abort support: implement SnapshotSubscriber as well.

The StateT parameter names the custom-state shape a store round-trips, so a typed store agrees with its agent's state_schema. It's a phantom over the snapshot wire format (which stays plain JSON), so leaving it off just defaults to Any.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
class SessionStore(Protocol, Generic[StateT_co]):
    """Structural interface for snapshot persistence backends.

    Minimum: ``get_snapshot`` + ``save_snapshot``.
    Optional detach/abort support: implement ``SnapshotSubscriber`` as well.

    The ``StateT`` parameter names the custom-state shape a store round-trips,
    so a typed store agrees with its agent's ``state_schema``. It's a phantom
    over the snapshot wire format (which stays plain JSON), so leaving it off
    just defaults to ``Any``.
    """

    async def get_snapshot(
        self,
        *,
        snapshot_id: str | None = None,
        session_id: str | None = None,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Retrieve a snapshot by id or the latest leaf for a session.

        ``context`` is optional request side-channel data (e.g. auth) so
        backends can isolate tenants; in-memory/file stores ignore it.
        """
        ...

    async def save_snapshot(
        self,
        snapshot_id: str,
        fn: Callable[
            [SessionSnapshot | None],
            SessionSnapshot | None,
        ],
        *,
        context: dict[str, Any] | None = None,
    ) -> SessionSnapshot | None:
        """Atomically read-modify-write a snapshot under ``snapshot_id``.

        fn receives the existing snapshot (or None for new) and returns the
        snapshot to persist, or None to skip. Stores may call fn more than
        once under contention, so it must not mutate external state; recording
        what it observed is fine as long as a retried call may overwrite the
        record (last call wins).

        Callers reserve the id up front (``reserve_snapshot_id``) so it can be
        known before the write — e.g. handed to a turn handler via
        ``TurnContext``. When no row exists yet, this creates under that id.
        The store also fills ``created_at`` and defaults status when left empty.

        ``context`` is optional request side-channel data (e.g. auth) so
        backends can isolate tenants; in-memory/file stores ignore it.
        """
        ...

get_snapshot(*, snapshot_id=None, session_id=None, context=None) async

Retrieve a snapshot by id or the latest leaf for a session.

context is optional request side-channel data (e.g. auth) so backends can isolate tenants; in-memory/file stores ignore it.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
 99
100
101
102
103
104
105
106
107
108
109
110
111
async def get_snapshot(
    self,
    *,
    snapshot_id: str | None = None,
    session_id: str | None = None,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Retrieve a snapshot by id or the latest leaf for a session.

    ``context`` is optional request side-channel data (e.g. auth) so
    backends can isolate tenants; in-memory/file stores ignore it.
    """
    ...

save_snapshot(snapshot_id, fn, *, context=None) async

Atomically read-modify-write a snapshot under snapshot_id.

fn receives the existing snapshot (or None for new) and returns the snapshot to persist, or None to skip. Stores may call fn more than once under contention, so it must not mutate external state; recording what it observed is fine as long as a retried call may overwrite the record (last call wins).

Callers reserve the id up front (reserve_snapshot_id) so it can be known before the write — e.g. handed to a turn handler via TurnContext. When no row exists yet, this creates under that id. The store also fills created_at and defaults status when left empty.

context is optional request side-channel data (e.g. auth) so backends can isolate tenants; in-memory/file stores ignore it.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
async def save_snapshot(
    self,
    snapshot_id: str,
    fn: Callable[
        [SessionSnapshot | None],
        SessionSnapshot | None,
    ],
    *,
    context: dict[str, Any] | None = None,
) -> SessionSnapshot | None:
    """Atomically read-modify-write a snapshot under ``snapshot_id``.

    fn receives the existing snapshot (or None for new) and returns the
    snapshot to persist, or None to skip. Stores may call fn more than
    once under contention, so it must not mutate external state; recording
    what it observed is fine as long as a retried call may overwrite the
    record (last call wins).

    Callers reserve the id up front (``reserve_snapshot_id``) so it can be
    known before the write — e.g. handed to a turn handler via
    ``TurnContext``. When no row exists yet, this creates under that id.
    The store also fills ``created_at`` and defaults status when left empty.

    ``context`` is optional request side-channel data (e.g. auth) so
    backends can isolate tenants; in-memory/file stores ignore it.
    """
    ...

SnapshotStatus

Bases: genkit._core._compat.StrEnum

SnapshotStatus data type class.

Source code in packages/genkit/src/genkit/_core/_typing.py
69
70
71
72
73
74
75
76
77
class SnapshotStatus(StrEnum):
    """SnapshotStatus data type class."""

    PENDING = 'pending'
    ABORTING = 'aborting'
    COMPLETED = 'completed'
    ABORTED = 'aborted'
    FAILED = 'failed'
    EXPIRED = 'expired'

SnapshotStatusStream

Bases: typing.Protocol

Async iterator of snapshot status changes.

Consume with async for. Call aclose() (or contextlib.aclosing) to unsubscribe — Python does not tear subscriptions down on break alone. Natural end after a terminal status also unsubscribes.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
142
143
144
145
146
147
148
149
150
151
152
153
154
155
@runtime_checkable
class SnapshotStatusStream(Protocol):
    """Async iterator of snapshot status changes.

    Consume with ``async for``. Call ``aclose()`` (or ``contextlib.aclosing``)
    to unsubscribe — Python does not tear subscriptions down on ``break`` alone.
    Natural end after a terminal status also unsubscribes.
    """

    def __aiter__(self) -> SnapshotStatusStream: ...

    async def __anext__(self) -> SnapshotStatus: ...

    async def aclose(self) -> None: ...

SnapshotSubscriber

Bases: typing.Protocol

Optional capability that makes a store's snapshots abortable/detachable.

Aborting itself is just a save_snapshot that flips a pending snapshot to aborted — there's no separate abort method. This is the other half: a way to notice that flip (e.g. when a different request aborts a detached turn that's still running) so the runtime can cancel the background work. A store that can't signal status changes can't support detach.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
@runtime_checkable
class SnapshotSubscriber(Protocol):
    """Optional capability that makes a store's snapshots abortable/detachable.

    Aborting itself is just a ``save_snapshot`` that flips a pending snapshot to
    aborted — there's no separate abort method. This is the other half: a way to
    *notice* that flip (e.g. when a different request aborts a detached turn
    that's still running) so the runtime can cancel the background work. A store
    that can't signal status changes can't support detach.
    """

    async def on_snapshot_status_change(
        self, snapshot_id: str, *, context: dict[str, Any] | None = None
    ) -> SnapshotStatusStream:
        """Async stream of the snapshot's persisted status changes.

        Yields committed statuses such as pending, completed, failed, or aborted.
        ``expired`` is computed on read when a pending heartbeat goes stale — it
        is not written to the store and does not appear on this stream. Use
        ``get_snapshot`` / resolve paths for that liveness check.

        Iteration ends when the run resolves (the last yielded status is a
        persisted terminal) or when the store is closed locally (ends without
        one). Call ``aclose()`` (or wrap with ``contextlib.aclosing``) to
        unsubscribe early — ``break`` alone is not enough. ``context`` scopes
        the subscription for multi-tenant stores; stores without tenancy accept
        and ignore it.
        """
        ...

on_snapshot_status_change(snapshot_id, *, context=None) async

Async stream of the snapshot's persisted status changes.

Yields committed statuses such as pending, completed, failed, or aborted. expired is computed on read when a pending heartbeat goes stale — it is not written to the store and does not appear on this stream. Use get_snapshot / resolve paths for that liveness check.

Iteration ends when the run resolves (the last yielded status is a persisted terminal) or when the store is closed locally (ends without one). Call aclose() (or wrap with contextlib.aclosing) to unsubscribe early — break alone is not enough. context scopes the subscription for multi-tenant stores; stores without tenancy accept and ignore it.

Source code in packages/genkit/src/genkit/_ai/_agents/_session.py
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
async def on_snapshot_status_change(
    self, snapshot_id: str, *, context: dict[str, Any] | None = None
) -> SnapshotStatusStream:
    """Async stream of the snapshot's persisted status changes.

    Yields committed statuses such as pending, completed, failed, or aborted.
    ``expired`` is computed on read when a pending heartbeat goes stale — it
    is not written to the store and does not appear on this stream. Use
    ``get_snapshot`` / resolve paths for that liveness check.

    Iteration ends when the run resolves (the last yielded status is a
    persisted terminal) or when the store is closed locally (ends without
    one). Call ``aclose()`` (or wrap with ``contextlib.aclosing``) to
    unsubscribe early — ``break`` alone is not enough. ``context`` scopes
    the subscription for multi-tenant stores; stores without tenancy accept
    and ignore it.
    """
    ...

TurnContext dataclass

Per-turn context handed to a custom-agent handler before the turn runs.

snapshot_id is reserved at turn start (when a store is configured) and is the id the snapshot persisted at turn end will reuse. That lets a handler name external, snapshot-correlated resources — e.g. a worktree or scratch directory — up front, then commit them under that id, so a later rollback to the snapshot can restore the external state too. None when the agent has no store (client-managed).

Source code in packages/genkit/src/genkit/_ai/_agents/_types.py
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
@dataclass(frozen=True)
class TurnContext:
    """Per-turn context handed to a custom-agent handler before the turn runs.

    ``snapshot_id`` is reserved at turn start (when a store is configured) and is
    the id the snapshot persisted at turn end will reuse. That lets a handler
    name external, snapshot-correlated resources — e.g. a worktree or scratch
    directory — up front, then commit them under that id, so a later rollback to
    the snapshot can restore the external state too. ``None`` when the agent has
    no store (client-managed).
    """

    snapshot_id: str | None
    parent_snapshot_id: str | None
    turn_index: int

TurnEnd

Bases: genkit._core._base.GenkitModel

Model for turnend data.

Source code in packages/genkit/src/genkit/_core/_typing.py
285
286
287
288
289
290
291
292
293
class TurnEnd(GenkitModel):
    """Model for turnend data."""

    model_config: ClassVar[ConfigDict] = ConfigDict(
        alias_generator=to_camel, extra='forbid', validate_by_name=True, validate_by_alias=True
    )
    snapshot_id: str | None = None
    finish_reason: AgentFinishReason | None = None
    usage: GenerationUsage | None = None

model_dump(**kwargs)

Dump model with Genkit defaults (by_alias=True, exclude_none=True).

Source code in packages/genkit/src/genkit/_core/_base.py
130
131
132
133
134
135
def model_dump(self, **kwargs: Any) -> dict[str, Any]:
    """Dump model with Genkit defaults (by_alias=True, exclude_none=True)."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump(**kwargs)

model_dump_json(**kwargs)

Dump model to JSON with Genkit defaults.

Source code in packages/genkit/src/genkit/_core/_base.py
137
138
139
140
141
142
def model_dump_json(self, **kwargs: Any) -> str:
    """Dump model to JSON with Genkit defaults."""
    kwargs.setdefault('by_alias', True)
    kwargs.setdefault('exclude_none', True)
    kwargs.setdefault('fallback', _default_serializer)
    return super().model_dump_json(**kwargs)

TurnResult dataclass

What an agent turn function returns to tell the loop how the turn ended.

Source code in packages/genkit/src/genkit/_ai/_agents/_types.py
70
71
72
73
74
75
@dataclass
class TurnResult:
    """What an agent turn function returns to tell the loop how the turn ended."""

    finish_reason: AgentFinishReason | None = None
    error: Failure | None = None

apply_json_patch(*, doc, patch)

Apply RFC 6902 JSON Patch operations to a document and return the transformed copy.

Lenient by design so a stream of deltas stays robust: an add/replace whose parent container is missing initializes it, and a remove/replace of a missing member is a no-op. test is honored (raises on mismatch); an unrecognized op raises rather than silently letting client state drift.

Source code in packages/genkit/src/genkit/_ai/_json_patch.py
246
247
248
249
250
251
252
253
254
255
256
257
def apply_json_patch(*, doc: Any, patch: list[JsonPatchOperation]) -> Any:
    """Apply RFC 6902 JSON Patch operations to a document and return the transformed copy.

    Lenient by design so a stream of deltas stays robust: an add/replace whose
    parent container is missing initializes it, and a remove/replace of a missing
    member is a no-op. ``test`` is honored (raises on mismatch); an unrecognized
    op raises rather than silently letting client state drift.
    """
    result = clone(doc)
    for op in patch:
        result = apply_op(result, op)
    return result

apply_save(*, existing, snapshot_id, fn)

Run a save mutator and stamp the result under snapshot_id, or None to skip.

When existing is None this creates under the reserved id. Mutators that only update (abort, heartbeat) return None when existing is missing.

Terminal statuses are absorbing: once a snapshot is completed, failed, or aborted, a mutation may still rewrite its state or metadata, but changing its status raises FAILED_PRECONDITION — an aborted run must never be rewritten into a completed one.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_util.py
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def apply_save(*, existing: SessionSnapshot | None, snapshot_id: str, fn: SaveFn) -> SessionSnapshot | None:
    """Run a save mutator and stamp the result under ``snapshot_id``, or None to skip.

    When ``existing`` is None this creates under the reserved id. Mutators that
    only update (abort, heartbeat) return None when ``existing`` is missing.

    Terminal statuses are absorbing: once a snapshot is completed, failed, or
    aborted, a mutation may still rewrite its state or metadata, but changing
    its status raises ``FAILED_PRECONDITION`` — an aborted run must never be
    rewritten into a completed one.
    """
    next_snapshot = fn(existing.model_copy(deep=True) if existing is not None else None)
    if inspect.iscoroutine(next_snapshot):
        next_snapshot.close()
        raise GenkitError(
            status='INVALID_ARGUMENT',
            message=("save mutator must be a synchronous function; got a coroutine — remove 'async' from the mutator"),
        )
    if next_snapshot is None:
        return None
    if (
        existing is not None
        and existing.session_id
        and next_snapshot.session_id
        and existing.session_id != next_snapshot.session_id
    ):
        raise GenkitError(
            status='FAILED_PRECONDITION',
            message=(
                f"Snapshot '{snapshot_id}' belongs to session '{existing.session_id}' "
                f"and cannot be rewritten by session '{next_snapshot.session_id}'. "
                'Snapshot ids share one namespace per store prefix; use ids that are '
                'unique across sessions.'
            ),
        )
    if existing is not None and existing.status in TERMINAL_STATUSES and next_snapshot.status != existing.status:
        raise GenkitError(
            status='FAILED_PRECONDITION',
            message=(
                f"Snapshot '{snapshot_id}' already has terminal status "
                f"'{existing.status and existing.status.value}' and cannot transition to "
                f"'{next_snapshot.status and next_snapshot.status.value}'."
            ),
        )
    stamp_store_fields(snapshot=next_snapshot, snapshot_id=snapshot_id)
    return next_snapshot

diff_json(*, from_value, to_value)

Return add/remove/replace ops that transform from_value into to_value.

Source code in packages/genkit/src/genkit/_ai/_json_patch.py
59
60
61
62
63
def diff_json(*, from_value: Any, to_value: Any) -> list[JsonPatchOperation]:
    """Return add/remove/replace ops that transform ``from_value`` into ``to_value``."""
    patch: list[JsonPatchOperation] = []
    diff_recursive(from_value, to_value, '', patch)
    return patch

iterate_statuses(q, *, on_close=None)

Expose a status queue as a closable async stream.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_util.py
250
251
252
253
254
255
256
def iterate_statuses(
    q: asyncio.Queue[SnapshotStatus | None],
    *,
    on_close: OnClose | None = None,
) -> SnapshotStatusStream:
    """Expose a status queue as a closable async stream."""
    return _StatusStream(q, on_close=on_close)

remote_agent(url, *, get_snapshot_url=None, abort_url=None, headers=None, state_management, state_schema=None, timeout=DEFAULT_AGENT_TIMEOUT_SECONDS)

Create a remote agent client over HTTP. timeout is as on :class:HttpAgentTransport.

Source code in packages/genkit/src/genkit/_ai/_agents/_transports/_http.py
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
def remote_agent(
    url: str,
    *,
    get_snapshot_url: str | None = None,
    abort_url: str | None = None,
    headers: HeadersProvider | None = None,
    state_management: StateManagement,
    state_schema: type[StateT] | None = None,
    timeout: float | None = DEFAULT_AGENT_TIMEOUT_SECONDS,
) -> AgentClient[StateT]:
    """Create a remote agent client over HTTP. ``timeout`` is as on :class:`HttpAgentTransport`."""
    transport: HttpAgentTransport[StateT] = HttpAgentTransport(
        url=url,
        get_snapshot_url=get_snapshot_url,
        abort_url=abort_url,
        headers=headers,
        state_management=state_management,
        timeout=timeout,
    )
    return AgentClient(transport, state_schema=state_schema)

require_one_selector(*, snapshot_id, session_id)

Enforce that a get_snapshot call names exactly one of snapshot_id / session_id.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_util.py
87
88
89
def require_one_selector(*, snapshot_id: str | None, session_id: str | None) -> None:
    """Enforce that a get_snapshot call names exactly one of snapshot_id / session_id."""
    parse_snapshot_lookup_kw(snapshot_id=snapshot_id, session_id=session_id)

session_id_of(snapshot)

Session a snapshot belongs to, preferring the top-level id over state's.

Source code in packages/genkit/src/genkit/_ai/_agents/_session_stores/_util.py
80
81
82
83
84
def session_id_of(snapshot: SessionSnapshot) -> str | None:
    """Session a snapshot belongs to, preferring the top-level id over state's."""
    if snapshot.session_id is not None:
        return snapshot.session_id
    return snapshot.state.session_id if snapshot.state is not None else None