Package com.embabel.agent.api.tool

Class Subagent

  • All Implemented Interfaces:
    com.embabel.agent.api.tool.Tool , com.embabel.agent.api.tool.ToolInfo 
    
public final class Subagent
 implements Tool

    A Tool that delegates to another agent as a subagent/handoff.

    When the LLM invokes this tool, it runs the specified agent as a subprocess, sharing the parent process's blackboard context. This enables composition of agents and "handoff" patterns where one agent delegates specialized tasks to another.

    Create a Subagent using one of the factory methods:

    // From an @Agent annotated class
Subagent.ofClass(MyAgent::class.java)
Subagent.ofClass<MyAgent>()  // Kotlin reified version

// From an agent name (resolved at runtime)
Subagent.byName("MyAgent")

// From an Agent instance
Subagent.ofInstance(resolvedAgent)

// From an instance of an @Agent annotated class
Subagent.ofAnnotatedInstance(myAgentBean)

    Use with withTool() on a PromptRunner:

    context.ai()
    .withTool(Subagent.ofClass(MyAgent::class.java))
    .creating(Result::class.java)
    .fromPrompt("...")

    For asset tracking, wrap with AssetAddingTool:

    context.ai()
    .withTool(assetTracker.addReturnedAssets(Subagent.ofClass(MyAgent::class.java)))
    .creating(Result::class.java)
    .fromPrompt("...")

    The input type for the subagent is automatically determined by introspecting the agent's actions. It finds the first non-injected input binding from the agent's first action.

    • Constructor Detail

    • Method Detail

      • call

         Tool.Result call(String input)

        Execute the tool with JSON input.

        Parameters:
        input - JSON string matching inputSchema
        Returns:

        Result to send back to LLM

      • ofClass

         final static Subagent.Builder ofClass(Class<?> agentClass)

        Create a Subagent from an @Agent annotated class. Call Builder.consuming to specify the input type.

        Example:

        Subagent.ofClass(MyAgent.class).consuming(MyInput.class)
        Parameters:
        agentClass - the class annotated with @Agent
        Returns:

        a Builder to specify the input type

      • byName

         final static Subagent.Builder byName(String name)

        Create a Subagent by agent name. The agent will be resolved from the platform at runtime. Call Builder.consuming to specify the input type.

        Example:

        Subagent.byName("MyAgent").consuming(MyInput.class)
        Parameters:
        name - the name of the agent to delegate to
        Returns:

        a Builder to specify the input type

      • ofInstance

         final static Subagent.Builder ofInstance(Agent agent)

        Create a Subagent from an already-resolved Agent instance. Call Builder.consuming to specify the input type.

        Parameters:
        agent - the Agent to delegate to
        Returns:

        a Builder to specify the input type

      • ofAnnotatedInstance

         final static Subagent.Builder ofAnnotatedInstance(Object annotatedInstance)

        Create a Subagent from an instance of an @Agent annotated class. The agent name is extracted from the instance's class metadata. Call Builder.consuming to specify the input type.

        Parameters:
        annotatedInstance - an instance of a class annotated with @Agent
        Returns:

        a Builder to specify the input type