Package com.google.genkit.plugins.middleware.internal

Class Delegation

java.lang.Object
com.google.genkit.plugins.middleware.internal.Delegation
public final class Delegation extends Object
Internal helper that runs a single one-shot turn against a sub-agent and packages the result.

This isolates the registry lookup, the runBidiJson one-shot invocation, output parsing, artifact namespacing/merging, and cross-call history bookkeeping from the public Agents façade.

History forwarding (per parent-session, per-sub-agent)

Each (parent session id, sub-agent name) pair gets its own stable sub-session key (subSessionKey(java.lang.String)). For a client-managed sub-agent (no SessionStore), this class keeps a small in-memory ledger (CLIENT_HISTORY) of that sub-session's accumulated messages and forwards the trailing historyLength of them via AgentInit.state.messages on every call, then updates the ledger from the returned AgentOutput.state afterward. This leans on the existing client-managed hydration path in SessionResolver.resolve (state → new Session<>(state)) rather than inventing new persistence.

For a server-managed sub-agent (has a SessionStore), the sub-session key is forwarded as AgentInit.sessionId; the sub-agent's own store then naturally accumulates history via SessionResolver.resolveBySessionId across repeated delegation calls. Note: historyLength trimming is not applied in the server-managed case — the store resolves and hands the agent its full accumulated history, and there is no seam in defineCustomAgent to truncate what a resolved session sees before AgentFn runs without mutating the sub-agent's own persisted snapshot (out of scope for this fix; see Agents/AgentsOptions javadoc).

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static final class 
    Delegation.NamedArtifact
    A sub-agent artifact after namespacing, ready for the tool output.
    static final class 
    Delegation.Result
    Result of a single delegation run, ready to be mapped onto the delegation tool output.

  • Method Summary

    Modifier and Type
    Method
    Description
    static Delegation.Result
    run(ActionContext ctx, String agentName, String task, boolean includeArtifactContent, int historyLength)
    Runs the sub-agent named agentName for a single turn with task as the user message, merges any produced artifacts (namespaced by a fresh invocation id) into the active parent session, and returns the sub-agent's text plus the (namespaced) artifacts.

    Methods inherited from class java.lang.Object

    equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

  • Method Details

    • run

      public static Delegation.Result run(ActionContext ctx, String agentName, String task, boolean includeArtifactContent, int historyLength)
      Runs the sub-agent named agentName for a single turn with task as the user message, merges any produced artifacts (namespaced by a fresh invocation id) into the active parent session, and returns the sub-agent's text plus the (namespaced) artifacts.

      Up to historyLength prior messages from this (parent session, sub-agent) pair's own accumulated conversation are forwarded to the sub-agent (see class Javadoc for the client-managed vs. server-managed mechanics). A historyLength <= 0 means no history is forwarded (task-only), matching the pre-fix behavior.

      Parameters:
      ctx - the calling tool's action context (provides the registry)
      agentName - the bare sub-agent name (looked up at /agent/<name>)
      task - the task text to send as the sub-agent's user message
      includeArtifactContent - whether to include artifact content in the returned artifacts (ArtifactStrategy.INLINE) or names only (ArtifactStrategy.SESSION)
      historyLength - the number of trailing prior messages to forward to the sub-agent ( <= 0 means task-only, no history forwarded)
      Returns:
      the delegation result
      Throws:
      ToolInterruptException - if the sub-agent's turn finished INTERRUPTED; carries the sub-agent's interrupted tool name/input as metadata so the parent's own generate loop pauses too
      GenkitException - if the sub-agent's turn finished FAILED, or the sub-agent's runBidiJson call itself threw