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"`
	// 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.
	ToolPrefix *string `json:"toolPrefix,omitempty"`
	// MaxDelegations caps the number of sub-agent delegations per generate call,
	// preventing runaway delegation loops. 0 means unlimited.
	MaxDelegations int `json:"maxDelegations,omitempty"`
	// 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 `json:"historyLength,omitempty"`
	// ArtifactStrategy controls how sub-agent artifacts are surfaced. Defaults to
	// ArtifactStrategyInline.
	ArtifactStrategy ArtifactStrategy `json:"artifactStrategy,omitempty"`
}

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>_<n>/<name>) 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.

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 `json:"readonly,omitempty"`
}

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