feat(go): experimental agent middleware for sub-agent delegation and artifacts

[apascal07]

Adds an experimental middleware package, plugins/middleware/exp, that brings two composable middlewares to the agent APIs in ai/exp: Agents lets one agent delegate to registered sub-agents through auto-generated per-agent tools, and Artifacts gives a model read/write tools over the session's named artifact collection. Both are ordinary generate middlewares (ai.NewMiddleware / ai.Hooks), attached with ai.WithUse on an agent's prompt, and they compose. To make them work, the Genkit instance is seeded into every agent's turn context automatically so middleware can resolve and run other registered actions via genkit.FromContext, and ai/exp gains the supporting surface: AgentRef (name a sub-agent, the agent analog of ai.ModelRef) and a State-agnostic ArtifactStore accessor for tools that touch artifacts without knowing the agent's State type.

Stacked on the agent API PR #4462; this PR targets ap/go-session-flow and its diff is just the middleware feature on top of that branch.

Examples

Orchestrator delegating to sub-agents

The Agents middleware turns each referenced agent into a delegate_to_<name> tool and injects a <sub-agents> listing into the system prompt. The orchestrator model delegates by calling the tool; the middleware runs the chosen sub-agent and returns its result.

import middlewarex "github.com/firebase/genkit/go/plugins/middleware/exp"

researcher := genkit.DefineAgent(g, "researcher",
    aix.InlinePrompt{
        ai.WithModelName("googleai/gemini-flash-latest"),
        ai.WithSystem("You are a research assistant. Summarize findings, then " +
            "call write_artifact to save them as a markdown artifact."),
        ai.WithUse(&middlewarex.Artifacts{}),
    },
    aix.WithDescription[any]("Researches a topic and summarizes well-sourced findings."),
)

engineer := genkit.DefineAgent(g, "engineer",
    aix.InlinePrompt{
        ai.WithModelName("googleai/gemini-flash-latest"),
        ai.WithSystem("You are an expert programmer. Write clean code, then call " +
            "write_artifact to save it as a file artifact."),
        ai.WithUse(&middlewarex.Artifacts{}),
    },
    aix.WithDescription[any]("Writes and explains code, producing file artifacts."),
)

orchestrator := genkit.DefineAgent(g, "orchestrator",
    aix.InlinePrompt{
        ai.WithModelName("googleai/gemini-flash-latest"),
        ai.WithSystem("You are a project coordinator. Delegate to the appropriate " +
            "sub-agent, then synthesize a final answer."),
        ai.WithUse(
            &middlewarex.Agents{
                // Descriptions are auto-discovered from each agent via Ref().
                Agents:           []aix.AgentRef{researcher.Ref(), engineer.Ref()},
                MaxDelegations:   5,
                HistoryLength:    4,
                ArtifactStrategy: middlewarex.ArtifactStrategySession,
            },
            &middlewarex.Artifacts{Readonly: true},
        ),
    },
    aix.WithSessionStore(store),
)

Sub-agents are referenced by AgentRef, either by name (aix.AgentRef{Name: "researcher"}) or captured from an agent value with agent.Ref() (which carries the agent's description into the system listing). The full version of this sample is in go/samples/basic-agents as the orchestrator agent.

Artifacts middleware

Artifacts gives the model read_artifact and write_artifact tools backed by the active session's artifacts. With no active agent session the tools degrade gracefully (empty listing), so the same prompt is safe to run standalone.

builder := genkit.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{}),
    },
)

// Read-only: only the read_artifact tool is provided.
reviewer := aix.InlinePrompt{
    ai.WithModelName("googleai/gemini-flash-latest"),
    ai.WithUse(&middlewarex.Artifacts{Readonly: true}),
}

Composing delegation with shared artifacts

ArtifactStrategySession merges a sub-agent's artifacts into the parent session and keeps them out of the (potentially large) tool result. Pairing it with the Artifacts middleware on the orchestrator lets the coordinator read what its sub-agents produced before answering:

ai.WithUse(
    &middlewarex.Agents{
        Agents:           []aix.AgentRef{researcher.Ref(), engineer.Ref()},
        ArtifactStrategy: middlewarex.ArtifactStrategySession, // merge, don't inline
    },
    &middlewarex.Artifacts{Readonly: true}, // orchestrator reviews, doesn't produce
)

The default, ArtifactStrategyInline, instead includes artifact content in the delegation tool result so the orchestrator model sees it directly, and also merges it into the session.

Registering as a plugin (optional)

Using the middlewares via ai.WithUse needs no plugin. Register the plugin only to make them resolvable by name (e.g. for the Dev UI):

g := genkit.Init(ctx, genkit.WithPlugins(&googlegenai.GoogleAI{}, &middlewarex.Middleware{}))

API Reference

plugins/middleware/exp (experimental)

// Agents delegates to registered sub-agents through one generated tool per
// agent (delegate_to_<name>) plus a <sub-agents> system-prompt listing.
type Agents struct {
    Agents           []aix.AgentRef   // sub-agents available for delegation; >= 1 required
    ToolPrefix       *string          // tool-name prefix; nil => "delegate_to", &"" => bare names
    MaxDelegations   int              // cap per generate call; 0 = unlimited
    HistoryLength    int              // recent messages forwarded to client-managed sub-agents; 0 = task only
    ArtifactStrategy ArtifactStrategy // how sub-agent artifacts surface; default Inline
}

// ArtifactStrategy controls how a sub-agent's artifacts are surfaced.
type ArtifactStrategy string
const (
    ArtifactStrategyInline  ArtifactStrategy = "inline"  // content in tool result + merged into session (default)
    ArtifactStrategySession ArtifactStrategy = "session" // merged into session only; result names them
)

// Artifacts provides read_artifact / write_artifact tools over the active
// session's artifacts. With no active session the tools report so and list empty.
type Artifacts struct {
    Readonly bool // when true, only read_artifact is provided
}

// Middleware registers Agents and Artifacts as named Genkit middlewares.
// Only needed for name-based resolution (e.g. Dev UI); ai.WithUse does not need it.
type Middleware struct{}

ai/exp additions

// AgentRef names an agent for resolution against a registry (the agent analog
// of ai.ModelRef / ai.ToolRef). Resolves by Name, so the agent must be registered
// wherever the ref is consumed.
type AgentRef struct {
    Name        string // resolved as /agent/<Name>; required
    Description string // human-readable; filled by Agent.Ref; optional
}

// Ref derives an AgentRef from an agent value, capturing its name and description.
func (a *Agent[State]) Ref() AgentRef

// ArtifactStore is the State-agnostic view of a session's artifacts. Every Session
// satisfies it regardless of State, since artifact ops do not touch custom state.
type ArtifactStore interface {
    Artifacts() []*Artifact
    AddArtifacts(artifacts ...*Artifact)
}

// ArtifactStoreFromContext returns the active session's ArtifactStore, or nil if
// none. The accessor for middleware/tools that work with artifacts without knowing
// the session's State type (where SessionFromContext cannot help).
func ArtifactStoreFromContext(ctx context.Context) ArtifactStore

genkit additions

// FromContext returns the Genkit instance seeded into the context, or nil.
func FromContext(ctx context.Context) *Genkit

DefineAgent, DefinePromptAgent, and DefineCustomAgent seed their Genkit instance into each invocation's context automatically, so middleware running inside any agent's turns can resolve and run other registered actions with genkit.FromContext, just as genkit.Generate already seeds it. This is what lets the Agents middleware look up and run a sub-agent from inside a delegation tool.

Notes

• The middlewares and their supporting ai/exp surface are experimental and may change in any minor release, tracking the agent APIs they build on.
• History forwarding (HistoryLength) applies only to client-managed sub-agents (no session store); server-managed sub-agents receive only the task description, since their own store owns their history.
• go/samples/basic-agents gains an orchestrator agent demonstrating delegation end to end; its .gitignore entry covers the compiled sample binary.

[gemini-code-assist]

Code Review

This pull request introduces experimental middleware for Genkit's Go agent APIs, specifically adding an Agents middleware for sub-agent delegation and an Artifacts middleware for session artifact access. It also introduces context decorators to propagate context values (like the Genkit instance) to agent turns, adds an AgentRef type for serializable agent references, and provides a state-agnostic ArtifactStore interface. The basic-agents sample has been updated to demonstrate an orchestrator agent coordinating specialized sub-agents. The review feedback highlights two potential nil pointer dereference panics: one in isClientManaged when handling a nil *aix.AgentMetadata pointer, and another in buildArtifactsListing if the slice of artifacts contains nil elements.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[pavelgj]

Took a pass comparing against the JS @genkit-ai/middleware impl (agents.ts/artifacts.ts). Reads as a faithful, clean port and the test coverage is solid. A few small things inline.

One open question, not blocking: about half the Go plugins ship a README.md (alloydb, mcp, ollama, googlegenai, etc.) and the JS middleware package has one too, but plenty of Go plugins don't. The package doc comment in plugin.go is already good. Is it worth adding a short README.md here for parity, or do we consider the package doc sufficient? No strong opinion either way.