Agent.Builder

Kotlin |Java

public final class Agent.Builder

---

Builder for constructing Agent instances.

Summary

Public constructors
Builder()

Public methods
final @NonNull Agent.Builder	@CanIgnoreReturnValue addAppFunctionId(@NonNull String functionId) Registers a specific AppFunction identifier (either a full ID such as "com.example.MyAppFunctionService#createNote" or a short method name such as "createNote") to be made available to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addAppFunctionIds(@NonNull List<@NonNull String> functionIds) Registers a list of AppFunction identifiers (either full IDs such as "com.example.MyAppFunctionService#createNote" or short method names such as "createNote") to be made available to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addAppFunctionIds(@NonNull String... functionIds) Registers AppFunction identifiers (either full IDs such as "com.example.MyAppFunctionService#createNote" or short method names such as "createNote") to be made available to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addTool(@NonNull AgentTool tool) Adds a single AppFunction tool (or a decorator wrapping one) to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addTools(@NonNull AgentTool tool) Adds a single AppFunction tool (or a decorator wrapping one) to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addTools(@NonNull AgentTool... tools) Adds multiple AppFunction tools (or decorators wrapping them) to the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue addTools(@NonNull List<@NonNull AgentTool> tools) Adds a collection of AppFunction tools (or decorators wrapping them) to the agent.
final @NonNull Agent	build() Builds the Agent instance.
final @NonNull Agent.Builder	@CanIgnoreReturnValue enableAppFunctions(boolean enabled) Enables automatic discovery and execution of functions annotated with @androidx.appfunctions.AppFunction across the calling application.
final @NonNull Agent.Builder	@CanIgnoreReturnValue setInstructions(@NonNull String instructions) Sets the system instructions for the agent.
final @NonNull Agent.Builder	@CanIgnoreReturnValue setMaxTurns(int maxTurns) Sets the maximum execution steps allowed per turn before forced termination.
final @NonNull Agent.Builder	@CanIgnoreReturnValue setName(@NonNull String name) Sets the name of the agent.

Public constructors

Builder

public Builder()

Public methods

addAppFunctionId

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addAppFunctionId(@NonNull String functionId)

Registers a specific AppFunction identifier (either a full ID such as "com.example.MyAppFunctionService#createNote" or a short method name such as "createNote") to be made available to the agent.

Scoping to specific function IDs disables package-level metadata instructions injection.

Parameters
@NonNull String functionId	The AppFunction identifier or method name to enable.

Returns
@NonNull Agent.Builder	This builder

addAppFunctionIds

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addAppFunctionIds(@NonNull List<@NonNull String> functionIds)

Registers a list of AppFunction identifiers (either full IDs such as "com.example.MyAppFunctionService#createNote" or short method names such as "createNote") to be made available to the agent.

Parameters
@NonNull List<@NonNull String> functionIds	The AppFunction identifiers or method names to enable.

Returns
@NonNull Agent.Builder	This builder

addAppFunctionIds

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addAppFunctionIds(@NonNull String... functionIds)

Registers AppFunction identifiers (either full IDs such as "com.example.MyAppFunctionService#createNote" or short method names such as "createNote") to be made available to the agent.

Parameters
@NonNull String... functionIds	The AppFunction identifiers or method names to enable.

Returns
@NonNull Agent.Builder	This builder

addTool

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addTool(@NonNull AgentTool tool)

Adds a single AppFunction tool (or a decorator wrapping one) to the agent.

Parameters
@NonNull AgentTool tool	Tool to add

Returns
@NonNull Agent.Builder	This builder

Throws
IllegalArgumentException	if tool is not an AppFunction tool discovered via AppFunctionAgentTools.discover (or a decorator wrapping one).

addTools

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addTools(@NonNull AgentTool tool)

Adds a single AppFunction tool (or a decorator wrapping one) to the agent.

Parameters
@NonNull AgentTool tool	Tool to add

Returns
@NonNull Agent.Builder	This builder

Throws
IllegalArgumentException	if tool is not an AppFunction tool discovered via AppFunctionAgentTools.discover (or a decorator wrapping one).

addTools

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addTools(@NonNull AgentTool... tools)

Adds multiple AppFunction tools (or decorators wrapping them) to the agent.

Parameters
@NonNull AgentTool... tools	Vararg tools to be made available to the agent

Returns
@NonNull Agent.Builder	This builder

Throws
IllegalArgumentException	if any tool in tools is not an AppFunction tool discovered via AppFunctionAgentTools.discover (or a decorator wrapping one).

addTools

@CanIgnoreReturnValue
public final @NonNull Agent.Builder addTools(@NonNull List<@NonNull AgentTool> tools)

Adds a collection of AppFunction tools (or decorators wrapping them) to the agent.

Parameters
@NonNull List<@NonNull AgentTool> tools	Tools to be made available to the agent

Returns
@NonNull Agent.Builder	This builder

Throws
IllegalArgumentException	if any tool in tools is not an AppFunction tool discovered via AppFunctionAgentTools.discover (or a decorator wrapping one).

build

public final @NonNull Agent build()

Builds the Agent instance.

enableAppFunctions

@CanIgnoreReturnValue
public final @NonNull Agent.Builder enableAppFunctions(boolean enabled)

Enables automatic discovery and execution of functions annotated with @androidx.appfunctions.AppFunction across the calling application.

When enabled, discovered functions are invoked automatically by AgentRunner during a turn whenever the model emits a matching tool call. If a function requires user confirmation (Human-in-the-Loop), runtime permissions, or custom validation before execution, use AppFunctionAgentTools.discover instead, wrap the sensitive AgentTool's AgentTool.execute method to prompt the user before delegating, and register the wrapped tools via addTools.

Parameters
boolean enabled	Whether to enable AppFunctions discovery and execution. Defaults to true.

Returns
@NonNull Agent.Builder	This builder

setInstructions

@CanIgnoreReturnValue
public final @NonNull Agent.Builder setInstructions(@NonNull String instructions)

Sets the system instructions for the agent. Defaults to an empty string.

Parameters
@NonNull String instructions	System prompt guiding agent behavior and personality

Returns
@NonNull Agent.Builder	This builder

setMaxTurns

@CanIgnoreReturnValue
public final @NonNull Agent.Builder setMaxTurns(int maxTurns)

Sets the maximum execution steps allowed per turn before forced termination. Defaults to 10.

Parameters
int maxTurns	Maximum turns allowed. Must be greater than 0

Returns
@NonNull Agent.Builder	This builder

setName

@CanIgnoreReturnValue
public final @NonNull Agent.Builder setName(@NonNull String name)

Sets the name of the agent. Defaults to "Assistant".

Parameters
@NonNull String name	Identifier name for the agent

Returns
@NonNull Agent.Builder	This builder