Embabel Agent Documentation/com.embabel.agent.api.tool/Subagent

Subagent

class Subagent : 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.

Usage

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("...")

Input Type Resolution

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.

Types

sealed class Builder

Builder step that requires specifying the input type. Use consuming to complete the Subagent creation.

object Companion

Properties

open override val definition: Tool.Definition

Tool definition for LLM

open override val metadata: Tool.Metadata

Optional metadata

Functions

open override fun call(input: String): Tool.Result

Execute the tool with JSON input.

inline fun <T : Any> Tool.requireType(message: String? = null): Tool

Wrap this tool to require a value of type T before execution (reified).

fun <T : Any> Tool.requireType(type: Class<T>, messageProvider: (String) -> String? = { null }): Tool

Wrap this tool to require a value of type T before execution.

toSpringToolCallback

fun Tool.toSpringToolCallback(): <Error class: unknown class>

Extension function to convert an Embabel Tool to a Spring AI ToolCallback.

open override fun toString(): String

inline fun <T : Tool> Tool.unwrapAs(): T?

Unwrap a tool to find a specific type, or return null if not found.

fun Tool.withAwaiting(decider: AwaitDecider): Tool

Wrap this tool to conditionally await before execution.

withConfirmation

fun Tool.withConfirmation(messageProvider: (String) -> String): Tool

fun Tool.withConfirmation(message: String): Tool

Wrap this tool to always require confirmation before execution.

withDescription

open fun withDescription(newDescription: String): Tool

Create a new tool with a different description. Useful for providing context-specific descriptions while keeping the same functionality.

withEventPublication

fun Tool.withEventPublication(agentProcess: AgentProcess, action: Action?, llmOptions: <Error class: unknown class>): Tool

Extension function to wrap a Tool with event publication.

open fun withName(newName: String): Tool

Create a new tool with a different name. Useful for namespacing tools when combining multiple tool sources.

open fun withNote(note: String): Tool

Create a new tool with an additional note appended to the description. Useful for adding context-specific hints to an existing tool.