Class AgentBuilder<TOut, TMulti>

AgentBuilder - A fluent interface for creating AI agents with automatic session management

Provides a simple, chainable API for building different types of agents (LLM, Sequential, Parallel, Loop, LangGraph) with tools, custom instructions, and multi-agent workflows. Sessions are automatically created using in-memory storage by default.

Example

// Simple usage
const response = await AgentBuilder.withModel("gemini-2.5-flash").ask("Hello");

// With tools and instructions
const { runner } = await AgentBuilder
  .create("research-agent")
  .withModel("gemini-2.5-flash")
  .withTools(new GoogleSearch())
  .withInstruction("You are a research assistant")
  .build();

// With plugins
const { runner } = await AgentBuilder
  .create("monitored-agent")
  .withModel("gemini-2.5-flash")
  .withPlugins(new LoggingPlugin(), new MetricsPlugin())
  .build();

Type Parameters

TOut = string
TMulti extends boolean = false

Methods

`Static`create

create(name?): AgentBuilder<string, false>
Create a new AgentBuilder instance
Parameters
- name: string = "default_agent"
  The name of the agent (defaults to "default_agent")
Returns AgentBuilder<string, false>
New AgentBuilder instance
- Defined in packages/adk/src/agents/agent-builder.ts:259

`Static`withModel

withModel(model): AgentBuilder<string, false>
Convenience method to start building with a model directly
Parameters
- model:
      | string
      | BaseLlm
      | string & {}
      | LanguageModelV2
  The model identifier (e.g., "gemini-2.5-flash")
Returns AgentBuilder<string, false>
New AgentBuilder instance with model set
- Defined in packages/adk/src/agents/agent-builder.ts:268

withModel

withModel(model): this
Set the model for the agent
Parameters
- model:
      | string
      | BaseLlm
      | string & {}
      | LanguageModelV2
  The model identifier (e.g., "gemini-2.5-flash")
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:279

withDescription

withDescription(description): this
Set the description for the agent
Parameters
- description: string
  Agent description
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:290

withInstruction

withInstruction(instruction): this
Set the instruction for the agent
Parameters
- instruction: string
  System instruction for the agent
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:301

withInputSchema

withInputSchema(schema): this
Parameters
- schema: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>
Returns this
- Defined in packages/adk/src/agents/agent-builder.ts:307

withOutputSchema

withOutputSchema<T>(schema): AgentBuilderWithSchema<T, TMulti>
Type Parameters
- T
Parameters
- schema: ZodType<T, unknown, $ZodTypeInternals<T, unknown>>
Returns AgentBuilderWithSchema<T, TMulti>
- Defined in packages/adk/src/agents/agent-builder.ts:313

withTools

withTools(...tools): this
Add tools to the agent
Parameters
- Rest...tools: BaseTool[]
  Tools to add to the agent
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:336

withPlanner

withPlanner(planner): this
Set the planner for the agent
Parameters
- planner: BasePlanner
  The planner to use
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:347

withCodeExecutor

withCodeExecutor(codeExecutor): this
Set the code executor for the agent
Parameters
- codeExecutor: BaseCodeExecutor
  The code executor to use for running code
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:358

withOutputKey

withOutputKey(outputKey): this
Set the output key for the agent
Parameters
- outputKey: string
  The output key in session state to store the output of the agent
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:369

withSubAgents

withSubAgents(subAgents): this
Add sub-agents to the agent
Parameters
- subAgents: BaseAgent[]
  Sub-agents to add to the agent
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:391

withBeforeAgentCallback

withBeforeAgentCallback(callback): this
Set the before agent callback
Parameters
- callback: BeforeAgentCallback
  Callback to invoke before agent execution
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:402

withAfterAgentCallback

withAfterAgentCallback(callback): this
Set the after agent callback
Parameters
- callback: AfterAgentCallback
  Callback to invoke after agent execution
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:413

withBeforeModelCallback

withBeforeModelCallback(callback): this
Set the before model callback for LLM interaction
Parameters
- callback: BeforeModelCallback
  Callback to invoke before calling the LLM
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:424

withAfterModelCallback

withAfterModelCallback(callback): this
Set the after model callback for LLM interaction
Parameters
- callback: AfterModelCallback
  Callback to invoke after receiving LLM response
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:435

withBeforeToolCallback

withBeforeToolCallback(callback): this
Set the before tool callback for tool execution
Parameters
- callback: BeforeToolCallback
  Callback to invoke before running a tool
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:446

withAfterToolCallback

withAfterToolCallback(callback): this
Set the after tool callback for tool execution
Parameters
- callback: AfterToolCallback
  Callback to invoke after running a tool
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:457

withPlugins

withPlugins(...plugins): this
Add plugins to the agent for lifecycle hooks and behavior extensions
Parameters
- Rest...plugins: BasePlugin[]
  Plugin instances to add to the agent
Returns this
This builder instance for chaining
Example
```
const { runner } = await AgentBuilder
  .create("monitored-agent")
  .withModel("gemini-2.5-flash")
  .withPlugins(
    new LoggingPlugin(),
    new MetricsPlugin(),
    new RateLimitPlugin()
  )
  .build();
```
- Defined in packages/adk/src/agents/agent-builder.ts:480

withFallbackModels

withFallbackModels(...models): this
Configure fallback models to use when the primary model hits rate limits. Models will be tried in order when the primary model fails with a 429 error.
Parameters
- Rest...models: string[]
  Fallback model names in priority order
Returns this
This builder instance for chaining
Example
```
const response = await AgentBuilder
  .withModel("gpt-4o")
  .withFallbackModels("gpt-3.5-turbo", "gemini-2.0-flash")
  .ask("Hello");
```
- Defined in packages/adk/src/agents/agent-builder.ts:500

`Static`withAgent

withAgent(agent): AgentBuilder<string, false>
Convenience method to start building with an existing agent
Parameters
- agent: BaseAgent
  The agent instance to wrap
Returns AgentBuilder<string, false>
New AgentBuilder instance with agent set
- Defined in packages/adk/src/agents/agent-builder.ts:511

withAgent

withAgent(agent): this
Provide an already constructed agent instance. Further definition-mutating calls (model/tools/instruction/etc.) will be ignored with a dev warning.
Parameters
- agent: BaseAgent
Returns this
- Defined in packages/adk/src/agents/agent-builder.ts:519

asSequential

asSequential(subAgents): AgentBuilder<TOut, true>
Configure as a sequential agent
Parameters
- subAgents: BaseAgent[]
  Sub-agents to execute in sequence
Returns AgentBuilder<TOut, true>
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:533

asParallel

asParallel(subAgents): AgentBuilder<TOut, true>
Configure as a parallel agent
Parameters
- subAgents: BaseAgent[]
  Sub-agents to execute in parallel
Returns AgentBuilder<TOut, true>
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:574

asLoop

asLoop(subAgents, maxIterations?): this
Configure as a loop agent
Parameters
- subAgents: BaseAgent[]
  Sub-agents to execute iteratively
- maxIterations: number = 3
  Maximum number of iterations
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:615

asLangGraph

asLangGraph(nodes, rootNode): this
Configure as a LangGraph agent
Parameters
- nodes: LangGraphNode[]
  Graph nodes defining the workflow
- rootNode: string
  The starting node name
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:629

withSessionService

withSessionService(service, options?): this
Configure session management with optional smart defaults
Parameters
- service: BaseSessionService
  Session service to use
- options: SessionOptions = {}
  Session configuration options (userId and appName)
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:643

withSession

withSession(session): this
Configure with an existing session instance
Parameters
- session: Session
  Existing session to use
Returns this
This builder instance for chaining

Throws
Error if no session service has been configured via withSessionService()
- Defined in packages/adk/src/agents/agent-builder.ts:663

withMemory

withMemory(memoryService): this
Configure memory service for the agent
Parameters
- memoryService: MemoryService
  Memory service to use for conversation history and context
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:693

withArtifactService

withArtifactService(artifactService): this
Configure artifact service for the agent
Parameters
- artifactService: BaseArtifactService
  Artifact service to use for managing generated artifacts
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:703

withRunConfig

withRunConfig(config): this
Configure runtime behavior for runs
Parameters
- config: RunConfig | Partial<RunConfig>
Returns this
- Defined in packages/adk/src/agents/agent-builder.ts:711

withEventsCompaction

withEventsCompaction(config): this

Configure event compaction for automatic history management

Parameters

config: EventsCompactionConfig
Event compaction configuration

Returns this

This builder instance for chaining

Example

const { runner } = await AgentBuilder
  .create("assistant")
  .withModel("gemini-2.5-flash")
  .withEventsCompaction({
    compactionInterval: 10,  // Compact every 10 invocations
    overlapSize: 2,          // Include 2 prior invocations
  })
  .build();

withQuickSession

withQuickSession(options?): this
Configure with an in-memory session with custom IDs Note: In-memory sessions are created automatically by default, use this only if you need custom appName/userId
Parameters
- options: SessionOptions = {}
  Session configuration options (userId and appName)
Returns this
This builder instance for chaining
- Defined in packages/adk/src/agents/agent-builder.ts:746

withContextCacheConfig

withContextCacheConfig(config): this
Parameters
- config: ContextCacheConfig
Returns this
- Defined in packages/adk/src/agents/agent-builder.ts:750

build

build<T>(): Promise<BuiltAgent<T, TMulti>>
Build the agent and optionally create runner and session
Type Parameters
- T = TOut
Returns Promise<BuiltAgent<T, TMulti>>
Built agent with optional runner and session
- Defined in packages/adk/src/agents/agent-builder.ts:759

buildWithSchema

buildWithSchema<T>(): Promise<BuiltAgent<T, TMulti>>
Type-safe build method for agents with output schemas Provides better type inference for the ask method return type
Type Parameters
- T
Returns Promise<BuiltAgent<T, TMulti>>
- Defined in packages/adk/src/agents/agent-builder.ts:825

ask

ask(message): Promise<RunnerAskReturn<TOut, TMulti>>
Quick execution helper - build and run a message
Parameters
- message: string | FullMessage
  Message to send to the agent (string or full message object)
Returns Promise<RunnerAskReturn<TOut, TMulti>>
Agent response
- Defined in packages/adk/src/agents/agent-builder.ts:835

Class AgentBuilder<TOut, TMulti>

Example

Type Parameters

Index

Methods

Methods

Staticcreate

Parameters

Returns AgentBuilder<string, false>

StaticwithModel

Parameters

Returns AgentBuilder<string, false>

withModel

Parameters

Returns this

withDescription

Parameters

Returns this

withInstruction

Parameters

Returns this

withInputSchema

Parameters

Returns this

withOutputSchema

Type Parameters

Parameters

Returns AgentBuilderWithSchema<T, TMulti>

withTools

Parameters

Returns this

withPlanner

Parameters

Returns this

withCodeExecutor

Parameters

Returns this

withOutputKey

Parameters

Returns this

withSubAgents

Parameters

Returns this

withBeforeAgentCallback

Parameters

Returns this

withAfterAgentCallback

Parameters

Returns this

withBeforeModelCallback

Parameters

Returns this

withAfterModelCallback

Parameters

Returns this

withBeforeToolCallback

Parameters

Returns this

withAfterToolCallback

Parameters

Returns this

withPlugins

Parameters

Returns this

Example

withFallbackModels

Parameters

Returns this

Example

StaticwithAgent

Parameters

Returns AgentBuilder<string, false>

withAgent

Parameters

Returns this

asSequential

Parameters

Returns AgentBuilder<TOut, true>

asParallel

Parameters

`Static`create

`Static`withModel

`Static`withAgent