exp

type Agents ¶

type Agents struct {
	// Agents lists the sub-agents available for delegation: by name
	// (aix.AgentRef{Name: ...}) or as a captured instance (agentValue.Ref()).
	// At least one is required.
	Agents []aix.AgentRef `json:"agents,omitempty" jsonschema_description:"Sub-agents available for delegation. At least one is required."`
	// ToolPrefix is the prefix for generated delegation tool names. A nil value
	// defaults to "delegate_to" (tools become delegate_to_<agent>); a pointer to
	// the empty string uses bare agent names. An explicitly set, non-empty
	// prefix also namespaces the shared tools: the [Agents.Async]
	// background-task tools (e.g. research_check_background_tasks) and the
	// continue tool (registered whenever any configured sub-agent may be
	// server-managed). Two instances in one generate call that both register
	// shared tools therefore need distinct, explicitly set prefixes: left at
	// the default they emit the same bare names, and the generate call is
	// rejected for duplicate tools. New rejects colliding names within one
	// instance; it cannot see a sibling.
	ToolPrefix *string `` /* 296-byte string literal not displayed */
	// MaxDelegations caps the number of sub-agent delegations per generate call,
	// preventing runaway delegation loops. 0 means unlimited.
	MaxDelegations int `` /* 191-byte string literal not displayed */
	// HistoryLength is the number of recent user/model messages forwarded to a
	// sub-agent as context. 0 means only the task description is sent. History is
	// forwarded only to client-managed sub-agents (those without a session
	// store); server-managed sub-agents receive only the task.
	HistoryLength int `` /* 231-byte string literal not displayed */
	// ArtifactStrategy controls how sub-agent artifacts are surfaced. Defaults to
	// ArtifactStrategyInline.
	ArtifactStrategy ArtifactStrategy `` /* 264-byte string literal not displayed */
	// Async enables background delegation. Delegation tools gain a "background"
	// input flag that starts the sub-agent through its detach support and
	// returns a task ID immediately, and three shared tools are added, one per
	// control the orchestrator has over a launched task:
	// check_background_tasks (non-blocking status and results),
	// wait_for_background_tasks (blocks until the listed tasks settle), and
	// abort_background_tasks (stops tasks whose results are no longer needed).
	// Background delegation requires server-managed sub-agents whose stores
	// implement [aix.SnapshotSubscriber].
	Async bool `` /* 320-byte string literal not displayed */

}

Agents is a middleware that enables sub-agent delegation.

For every configured agent it injects a dedicated delegation tool (e.g. delegate_to_researcher) whose description is the agent's configured description or, in the system prompt, the description auto-discovered from the registry. A <sub-agents> block listing the available agents is appended to the system prompt.

When the model calls a delegation tool the middleware resolves the target agent from the registry (via the github.com/firebase/genkit/go/genkit.Genkit instance carried on the context), optionally forwards recent conversation history, runs the sub-agent with the task, and returns its response as the tool result.

Artifact handling follows Agents.ArtifactStrategy: ArtifactStrategyInline (default) returns artifact content in the tool result and merges artifacts into the parent session; ArtifactStrategySession merges into the session only and returns names. Merged artifacts are namespaced by an invocation ID (<agent>_<snapshotId prefix>/<name> for a run with a snapshot behind it, <agent>_<n>/<name> otherwise) and tagged with the source agent.

If a sub-agent interrupts (e.g. for human input) it is reported back to the orchestrator as a normal tool response, not propagated as an interrupt: there is no stateful sub-agent runtime to resume into, so interactive sub-agent interaction is a future feature.

With Agents.Async set, delegation tools additionally accept a "background" flag. A background delegation starts the sub-agent through its detach support (aix.AgentInput.Detach): the sub-agent's runtime persists a pending snapshot, hands back a task ID immediately, and keeps working in the background, so the orchestrator can continue calling tools and collect the result later through the added check_background_tasks and wait_for_background_tasks tools, or drop it with abort_background_tasks. The pending snapshot (heartbeated while the worker lives, finalized in place with the cumulative state when the work settles) is the durable record, and task IDs are self-contained ("<agent>:<snapshotId>"), so a re-instantiated orchestrator can pick results up using nothing but the IDs recorded in its conversation history. Background delegation requires server-managed sub-agents whose stores implement aix.SnapshotSubscriber (e.g. the localstore stores); launches on other agents are rejected by the sub-agent runtime and reported as tool text.

Task handles are not access-scoped: the background-task tools read any snapshot ID belonging to a configured sub-agent, whether or not this conversation launched it (mirroring the sub-agent's getSnapshot companion action, which is itself unscoped). In multi-tenant deployments treat snapshot IDs as capability-like secrets: text that reaches the orchestrator model can steer these tools at any ID it names.

The middleware resolves agents through genkit.FromContext, which is seeded by genkit.Generate and by agents defined via the genkit/exp constructors (genkitx.DefineAgent and friends). It is therefore typically attached to an orchestrator agent (or a genkit.Generate call).

Usage:

orchestrator := genkitx.DefineAgent(g, "orchestrator",
    aix.InlinePrompt{
        ai.WithModelName("googleai/gemini-flash-latest"),
        ai.WithSystem("You are a helpful project assistant."),
        ai.WithUse(
            &middlewarex.Agents{
                Agents: []aix.AgentRef{
                    {Name: "researcher"}, // by name
                    coderAgent.Ref(),     // by instance (carries its description)
                },
                MaxDelegations:   5,
                HistoryLength:    4,
                ArtifactStrategy: middlewarex.ArtifactStrategySession,
            },
            &middlewarex.Artifacts{},
        ),
    },
)

func (a Agents) Name() string

func (a Agents) New(ctx context.Context) (*ai.Hooks, error)

type ArtifactStrategy ¶

type ArtifactStrategy string

ArtifactStrategy controls how a sub-agent's artifacts are surfaced back to the orchestrator by the Agents middleware.

const (
	// ArtifactStrategyInline includes artifact content in the delegation tool
	// result so the orchestrator model can see it, and also merges artifacts
	// into the parent session. This is the default.
	ArtifactStrategyInline ArtifactStrategy = "inline"
	// ArtifactStrategySession merges artifacts into the parent session only; the
	// tool result names the artifacts but omits their content. Pair it with the
	// [Artifacts] middleware so the model can read/write session artifacts.
	ArtifactStrategySession ArtifactStrategy = "session"
)

type Artifacts ¶

type Artifacts struct {
	// Readonly, when true, provides only the read_artifact tool; the model
	// cannot create or update artifacts. Defaults to false.
	Readonly bool `` /* 154-byte string literal not displayed */
}

Artifacts is a middleware that gives the model tools to interact with session artifacts and injects a listing of available artifacts into the system prompt.

It provides:

• read_artifact: reads an artifact by name from the session and returns its text content.
• write_artifact (unless Readonly): creates or updates a session artifact. Artifacts are deduplicated by name, so writing to an existing name replaces it.

On every generate turn an <artifacts> block listing the names and sizes of the session's artifacts is injected into (or refreshed within) the system message, so the model knows what is available without spending context on the full content.

This is useful standalone (e.g. a workspace-builder agent that creates files as artifacts) or combined with Agents using ArtifactStrategySession, where sub-agent artifacts are merged into the parent session and the model reaches them through these tools.

Artifacts live on the active agent session, so this middleware only has an effect when generation runs inside an agent invocation (see github.com/firebase/genkit/go/genkit/exp.DefineAgent). With no active session the tools report that gracefully and the listing is empty.

Usage:

builder := genkitx.DefineAgent(g, "builder",
    aix.InlinePrompt{
        ai.WithModelName("googleai/gemini-flash-latest"),
        ai.WithSystem("You are a code generator. Use write_artifact to create files."),
        ai.WithUse(&middlewarex.Artifacts{}),
    },
)

func (a Artifacts) Name() string

func (a Artifacts) New(ctx context.Context) (*ai.Hooks, error)

type Middleware ¶

type Middleware struct{}

Middleware provides the experimental agent middleware (Agents, Artifacts) as a Genkit plugin. Register it with genkit.WithPlugins during genkit.Init to make them resolvable by name (e.g. for the Dev UI). Using them directly via ai.WithUse does not require the plugin.

func (p *Middleware) Init(ctx context.Context) []api.Action

func (p *Middleware) Middlewares(ctx context.Context) ([]*ai.MiddlewareDesc, error)

func (p *Middleware) Name() string