agent

package
v0.0.0-...-02ca4c9 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 31, 2025 License: Apache-2.0 Imports: 17 Imported by: 0

Documentation

Overview

Package agent provides hierarchical agent implementations for building sophisticated AI agents.

The agent package implements a hierarchical, event-driven agent architecture with four core agent types:

  • LLMAgent: Full-featured agents powered by language models with tools, instructions, callbacks, planners, and code execution
  • SequentialAgent: Executes sub-agents one after another, supports live mode with taskCompleted() flow control
  • ParallelAgent: Runs sub-agents concurrently in isolated branches, merges event streams
  • LoopAgent: Repeatedly executes sub-agents until escalation or max iterations

All agents embed types.BaseAgent for common functionality and use event streaming via iter.Seq2[*Event, error] iterators for real-time processing. The rich InvocationContext tracks execution state, session, and hierarchy with before/after callbacks for customizing behavior.

Basic Usage

Creating an LLM agent: 

agent := agent.NewLLMAgent(ctx, "my_agent",
	agent.WithModel("gemini-2.0-flash-exp"),
	agent.WithInstruction("You are a helpful assistant"),
	agent.WithTools(tool1, tool2),
)

Creating a sequential agent: 

sequential := agent.NewSequentialAgent("coordinator").
	WithAgents(subAgent1, subAgent2, subAgent3)

Running an agent: 

for event, err := range agent.Run(ctx, invocationContext) {
	if err != nil {
		log.Fatal(err)
	}
	// Process event
}

Agent Types

LLMAgent provides comprehensive LLM integration with features like:

  • Model abstraction supporting multiple providers
  • Tool execution with parallel processing
  • Custom instructions and dynamic context
  • Before/after callbacks for customization
  • Planning and reasoning capabilities
  • Code execution support

SequentialAgent executes child agents in order:

  • Useful for multi-step workflows
  • Supports live mode for real-time interactions
  • Maintains conversation flow between agents

ParallelAgent runs multiple agents concurrently:

  • Isolated execution branches
  • Event stream merging
  • Useful for multi-perspective analysis

LoopAgent provides iterative execution:

  • Configurable maximum iterations
  • Escalation-based termination
  • Useful for refinement workflows

Event-Driven Architecture

All agents use Go 1.23+ iterators for streaming results: 

for event, err := range agent.Run(ctx, ictx) {
	if err != nil {
		// Handle error
		continue
	}

	switch event.Type {
	case types.EventTypeTextDelta:
		// Handle streaming text
	case types.EventTypeFunctionCall:
		// Handle tool execution
	}
}

Callbacks and Customization

Agents support before/after callbacks for customization: 

agent.WithBeforeModelCallback(func(cctx *types.CallbackContext, req *types.LLMRequest) (*types.LLMResponse, error) {
	// Modify request before sending to model
	return nil, nil
})

agent.WithAfterModelCallback(func(cctx *types.CallbackContext, resp *types.LLMResponse) (*types.LLMResponse, error) {
	// Process response after receiving from model
	return resp, nil
})

Hierarchical Composition

Agents form trees with parent/child relationships: 

coordinator := agent.NewSequentialAgent("coordinator")
analyzer := agent.NewLLMAgent(ctx, "analyzer", ...)
reporter := agent.NewLLMAgent(ctx, "reporter", ...)

coordinator.WithAgents(analyzer, reporter)

The agent hierarchy enables complex workflows with proper context propagation and state management throughout the execution tree.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func MergeAgentRun 

func MergeAgentRun(ctx context.Context, agentRuns []iter.Seq2[*types.Event, error]) iter.Seq2[*types.Event, error]

MergeAgentRun merges the agent run event generator.

This implementation guarantees for each agent, it won't move on until the generated event is processed by upstream runner.

Types

type LLMAgent 

type LLMAgent struct {
	// contains filtered or unexported fields
}

LLMAgent represents an agent powered by a Large Language Model.

func NewLLMAgent 

func NewLLMAgent(ctx context.Context, name string, opts ...LLMAgentOption) (*LLMAgent, error)

NewLLMAgent creates a new LLMAgent with the given name and options.

func (*LLMAgent) AfterAgentCallbacks 

func (a *LLMAgent) AfterAgentCallbacks() []types.AgentCallback

AfterAgentCallbacks implements types.Agent.

func (*LLMAgent) AfterModelCallbacks 

func (a *LLMAgent) AfterModelCallbacks() []types.AfterModelCallback

AfterModelCallbacks returns the resolved self.before_tool_callback field as a list of BeforeToolCallback.

This method is only for use by Agent Development Kit.

func (*LLMAgent) AfterToolCallbacks 

func (a *LLMAgent) AfterToolCallbacks() []types.AfterToolCallback

AfterToolCallbacks returns the resolved self.after_tool_callback field as a list of AfterToolCallback.

This method is only for use by Agent Development Kit.

func (*LLMAgent) AsLLMAgent 

func (a *LLMAgent) AsLLMAgent() (types.LLMAgent, bool)

AsLLMAgent implements types.Agent.

func (*LLMAgent) BeforeAgentCallbacks 

func (a *LLMAgent) BeforeAgentCallbacks() []types.AgentCallback

BeforeAgentCallbacks implements types.Agent.

func (*LLMAgent) BeforeModelCallbacks 

func (a *LLMAgent) BeforeModelCallbacks() []types.BeforeModelCallback

BeforeModelCallbacks returns the resolved self.before_model_callback field as a list of _SingleBeforeModelCallback.

This method is only for use by Agent Development Kit.

func (*LLMAgent) BeforeToolCallback 

func (a *LLMAgent) BeforeToolCallback() []types.BeforeToolCallback

BeforeToolCallbacks returns the resolved self.before_tool_callback field as a list of BeforeToolCallback.

This method is only for use by Agent Development Kit.

func (*LLMAgent) CanonicalGlobalInstruction 

func (a *LLMAgent) CanonicalGlobalInstruction(rctx *types.ReadOnlyContext) (string, bool)

CanonicalGlobalInstruction returns the resolved self.instruction field to construct global instruction.

This method is only for use by Agent Development Kit.

func (*LLMAgent) CanonicalInstructions 

func (a *LLMAgent) CanonicalInstructions(rctx *types.ReadOnlyContext) string

CanonicalInstructions returns the resolved self.instruction field to construct instruction for this agent.

This method is only for use by Agent Development Kit.

func (*LLMAgent) CanonicalModel 

func (a *LLMAgent) CanonicalModel(ctx context.Context) (types.Model, error)

CanonicalModel returns the resolved model field as model.Model.

This method is only for use by Agent Development Kit.

func (*LLMAgent) CanonicalTool 

func (a *LLMAgent) CanonicalTool(rctx *types.ReadOnlyContext) []types.Tool

CanonicalTool returns the resolved tools field as a list of [Tool] based on the context.

This method is only for use by Agent Development Kit.

func (*LLMAgent) CodeExecutor 

func (a *LLMAgent) CodeExecutor() types.CodeExecutor

CodeExecutor returns the code executor for the agent.

func (*LLMAgent) Description 

func (a *LLMAgent) Description() string

Description implements types.Agent.

func (*LLMAgent) DisallowTransferToParent 

func (a *LLMAgent) DisallowTransferToParent() bool

DisallowTransferToParent reports whether teh disallows LLM-controlled transferring to the parent agent.

func (*LLMAgent) DisallowTransferToPeers 

func (a *LLMAgent) DisallowTransferToPeers() bool

DisallowTransferToPeers reports whether teh disallows LLM-controlled transferring to the peer agents.

func (*LLMAgent) Execute 

func (a *LLMAgent) Execute(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

Execute implements types.Agent.

func (*LLMAgent) ExecuteLive 

func (a *LLMAgent) ExecuteLive(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

ExecuteLive implements types.Agent.

func (*LLMAgent) FindAgent 

func (a *LLMAgent) FindAgent(name string) types.Agent

FindAgent implements types.Agent.

func (*LLMAgent) FindSubAgent 

func (a *LLMAgent) FindSubAgent(name string) types.Agent

FindSubAgent implements types.Agent.

func (*LLMAgent) GenerateContentConfig 

func (a *LLMAgent) GenerateContentConfig() *genai.GenerateContentConfig

GenerateContentConfig returns the *genai.GenerateContentConfig for LLMAgent agent.

func (*LLMAgent) IncludeContents 

func (a *LLMAgent) IncludeContents() types.IncludeContents

IncludeContents returns the mode of include contents in the model request.

func (*LLMAgent) InputSchema 

func (a *LLMAgent) InputSchema() *genai.Schema

InputSchema returns the structured input.

func (*LLMAgent) Name 

func (a *LLMAgent) Name() string

Name implements types.Agent.

func (*LLMAgent) OutputKey 

func (a *LLMAgent) OutputKey() string

OutputKey returns the key in session state to store the output of the agent.

func (*LLMAgent) OutputSchema 

func (a *LLMAgent) OutputSchema() *genai.Schema

OutputSchema returns the structured output.

func (*LLMAgent) ParentAgent 

func (a *LLMAgent) ParentAgent() types.Agent

ParentAgent implements types.Agent.

func (*LLMAgent) Planner 

func (a *LLMAgent) Planner() types.Planner

Planner returns the instructs the agent to make a plan and execute it step by step.

func (*LLMAgent) RootAgent 

func (a *LLMAgent) RootAgent() types.Agent

RootAgent implements types.Agent.

func (*LLMAgent) Run 

func (a *LLMAgent) Run(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

Run implements types.Agent.

func (*LLMAgent) RunLive 

func (a *LLMAgent) RunLive(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

RunLive implements types.Agent.

func (*LLMAgent) SubAgents 

func (a *LLMAgent) SubAgents() []types.Agent

SubAgents implements types.Agent.

type LLMAgentOption 

type LLMAgentOption func(*LLMAgent)

LLMAgentOption configures an LLMAgent.

func WithAfterModelCallback 

func WithAfterModelCallback(callback types.AfterModelCallback) LLMAgentOption

WithAfterModelCallback adds a callback to run after receiving a response from the model.

func WithAfterToolCallback 

func WithAfterToolCallback(callback types.AfterToolCallback) LLMAgentOption

WithAfterToolCallback adds a callback to run after executing a tool.

func WithBeforeModelCallback 

func WithBeforeModelCallback(callback types.BeforeModelCallback) LLMAgentOption

WithBeforeModelCallback adds a callback to run before sending a request to the model.

func WithBeforeToolCallback 

func WithBeforeToolCallback(callback types.BeforeToolCallback) LLMAgentOption

WithBeforeToolCallback adds a callback to run before executing a tool.

func WithCodeExecutor 

func WithCodeExecutor(codeExecutor types.CodeExecutor) LLMAgentOption

WithCodeExecutor sets the codeExecutor for the agent.

func WithDisallowTransferToParent 

func WithDisallowTransferToParent(disallow bool) LLMAgentOption

WithDisallowTransferToParent prevents transferring control to parent.

func WithDisallowTransferToPeers 

func WithDisallowTransferToPeers(disallow bool) LLMAgentOption

WithDisallowTransferToPeers prevents transferring control to peers.

func WithExamples 

func WithExamples(examples any) LLMAgentOption

WithExamples sets the examples for the agent.

func WithFunctionTools 

func WithFunctionTools(tools ...tools.Function) LLMAgentOption

WithTools sets the [tools.function] for the agent.

func WithGenerateContentConfig 

func WithGenerateContentConfig(config *genai.GenerateContentConfig) LLMAgentOption

WithGenerateContentConfig sets the genai.GenerateContentConfig for the agent.

func WithGlobalInstruction 

func WithGlobalInstruction[T string | types.InstructionProvider](instruction T) LLMAgentOption

WithGlobalInstruction sets the global instruction for the agent.

func WithIncludeContents 

func WithIncludeContents(includeContents types.IncludeContents) LLMAgentOption

WithIncludeContents sets the [IncludeContents] for the agent.

func WithInputSchema 

func WithInputSchema(schema *genai.Schema) LLMAgentOption

WithInputSchema sets the input schema for structured input.

func WithInstruction 

func WithInstruction[T string | types.InstructionProvider](instruction T) LLMAgentOption

WithInstruction sets the instruction for the agent.

func WithModel 

func WithModel(model types.Model) LLMAgentOption

WithModel sets the model to use.

func WithModelString 

func WithModelString(model string) LLMAgentOption

WithModelString sets the model to use.

func WithOutputKey 

func WithOutputKey(key string) LLMAgentOption

WithOutputKey sets the key where to store model output in state.

func WithOutputSchema 

func WithOutputSchema(schema *genai.Schema) LLMAgentOption

WithOutputSchema sets the output schema for structured output.

func WithPlanner 

func WithPlanner(plan types.Planner) LLMAgentOption

WithPlanner sets the planner for the agent.

func WithTools 

func WithTools(tools ...types.Tool) LLMAgentOption

WithTools sets the [Tool] for the agent.

func WithToolset 

func WithToolset(tools ...types.Toolset) LLMAgentOption

WithToolset sets the [Toolset] for the agent.

type LoopAgent 

type LoopAgent struct {
	// contains filtered or unexported fields
}

LoopAgent runs an agent repeatedly until a condition is met.

func NewLoopAgent 

func NewLoopAgent(name string) *LoopAgent

NewLoopAgent creates a new loop agent with the given name and options.

func (*LoopAgent) AfterAgentCallbacks 

func (a *LoopAgent) AfterAgentCallbacks() []types.AgentCallback

AfterAgentCallbacks implements types.Agent.

func (*LoopAgent) AsLLMAgent 

func (a *LoopAgent) AsLLMAgent() (types.LLMAgent, bool)

AsLLMAgent implements types.Agent.

func (*LoopAgent) BeforeAgentCallbacks 

func (a *LoopAgent) BeforeAgentCallbacks() []types.AgentCallback

BeforeAgentCallbacks implements types.Agent.

func (*LoopAgent) Description 

func (a *LoopAgent) Description() string

Description implements types.Agent.

func (*LoopAgent) Execute 

func (a *LoopAgent) Execute(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

Execute implements types.Agent.

func (*LoopAgent) ExecuteLive 

func (a *LoopAgent) ExecuteLive(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

ExecuteLive implements types.Agent.

func (*LoopAgent) FindAgent 

func (a *LoopAgent) FindAgent(name string) types.Agent

FindAgent implements types.Agent.

func (*LoopAgent) FindSubAgent 

func (a *LoopAgent) FindSubAgent(name string) types.Agent

FindSubAgent implements types.Agent.

func (*LoopAgent) Name 

func (a *LoopAgent) Name() string

Name implements types.Agent.

func (*LoopAgent) ParentAgent 

func (a *LoopAgent) ParentAgent() types.Agent

ParentAgent implements types.Agent.

func (*LoopAgent) RootAgent 

func (a *LoopAgent) RootAgent() types.Agent

RootAgent implements types.Agent.

func (*LoopAgent) Run 

func (a *LoopAgent) Run(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

Run implements types.Agent.

func (*LoopAgent) RunLive 

func (a *LoopAgent) RunLive(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

RunLive implements types.Agent.

func (*LoopAgent) SubAgents 

func (a *LoopAgent) SubAgents() []types.Agent

SubAgents implements types.Agent.

func (*LoopAgent) WithMaxIterations 

func (a *LoopAgent) WithMaxIterations(maxIterations int) *LoopAgent

WithMaxIterations sets the maximum number of iterations.

type ParallelAgent 

type ParallelAgent struct {
	// contains filtered or unexported fields
}

A shell agent that run its sub-agents in parallel in isolated manner.

This approach is beneficial for scenarios requiring multiple perspectives or attempts on a single task, such as:

  • Running different algorithms simultaneously.
  • Generating multiple responses for review by a subsequent evaluation agent.

func NewParallelAgent 

func NewParallelAgent(name string, agents ...types.Agent) *ParallelAgent

NewParallelAgent creates a new parallel agent with the given name and options.

func (*ParallelAgent) AfterAgentCallbacks 

func (a *ParallelAgent) AfterAgentCallbacks() []types.AgentCallback

AfterAgentCallbacks implements types.Agent.

func (*ParallelAgent) AsLLMAgent 

func (a *ParallelAgent) AsLLMAgent() (types.LLMAgent, bool)

AsLLMAgent implements types.Agent.

func (*ParallelAgent) BeforeAgentCallbacks 

func (a *ParallelAgent) BeforeAgentCallbacks() []types.AgentCallback

BeforeAgentCallbacks implements types.Agent.

func (*ParallelAgent) Description 

func (a *ParallelAgent) Description() string

Description implements types.Agent.

func (*ParallelAgent) Execute 

func (a *ParallelAgent) Execute(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

Execute implements types.Agent.

func (*ParallelAgent) ExecuteLive 

func (a *ParallelAgent) ExecuteLive(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

ExecuteLive implements types.Agent.

func (*ParallelAgent) FindAgent 

func (a *ParallelAgent) FindAgent(name string) types.Agent

FindAgent implements types.Agent.

func (*ParallelAgent) FindSubAgent 

func (a *ParallelAgent) FindSubAgent(name string) types.Agent

FindSubAgent implements types.Agent.

func (*ParallelAgent) Name 

func (a *ParallelAgent) Name() string

Name implements types.Agent.

func (*ParallelAgent) ParentAgent 

func (a *ParallelAgent) ParentAgent() types.Agent

ParentAgent implements types.Agent.

func (*ParallelAgent) RootAgent 

func (a *ParallelAgent) RootAgent() types.Agent

RootAgent implements types.Agent.

func (*ParallelAgent) Run 

func (a *ParallelAgent) Run(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

Run implements types.Agent.

func (*ParallelAgent) RunLive 

func (a *ParallelAgent) RunLive(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

RunLive implements types.Agent.

func (*ParallelAgent) SubAgents 

func (a *ParallelAgent) SubAgents() []types.Agent

SubAgents implements types.Agent.

type SequentialAgent 

type SequentialAgent struct {
	// contains filtered or unexported fields
}

SequentialAgent represents a shell agent that run its sub-agents in sequence.

func NewSequentialAgent 

func NewSequentialAgent(name string) *SequentialAgent

NewSequentialAgent creates a new sequential agent with the given name and options.

func (*SequentialAgent) AfterAgentCallbacks 

func (a *SequentialAgent) AfterAgentCallbacks() []types.AgentCallback

AfterAgentCallbacks implements types.Agent.

func (*SequentialAgent) AsLLMAgent 

func (a *SequentialAgent) AsLLMAgent() (types.LLMAgent, bool)

AsLLMAgent implements types.Agent.

func (*SequentialAgent) BeforeAgentCallbacks 

func (a *SequentialAgent) BeforeAgentCallbacks() []types.AgentCallback

BeforeAgentCallbacks implements types.Agent.

func (*SequentialAgent) Description 

func (a *SequentialAgent) Description() string

Description implements types.Agent.

func (*SequentialAgent) Execute 

func (a *SequentialAgent) Execute(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

Execute implements types.Agent.

func (*SequentialAgent) ExecuteLive 

func (a *SequentialAgent) ExecuteLive(ctx context.Context, ictx *types.InvocationContext) iter.Seq2[*types.Event, error]

ExecuteLive implements types.Agent.

ExecuteLive implementation for live SequentialAgent.

Compared to non-live case, live agents process a continous streams of audio or video, so it doesn't have a way to tell if it's finished and should pass to next agent or not. So we introduce a task_compelted() function so the model can call this function to signal that it's finished the task and we can move on to next agent.

func (*SequentialAgent) FindAgent 

func (a *SequentialAgent) FindAgent(name string) types.Agent

FindAgent implements types.Agent.

func (*SequentialAgent) FindSubAgent 

func (a *SequentialAgent) FindSubAgent(name string) types.Agent

FindSubAgent implements types.Agent.

func (*SequentialAgent) Name 

func (a *SequentialAgent) Name() string

Name implements types.Agent.

func (*SequentialAgent) ParentAgent 

func (a *SequentialAgent) ParentAgent() types.Agent

ParentAgent implements types.Agent.

func (*SequentialAgent) RootAgent 

func (a *SequentialAgent) RootAgent() types.Agent

RootAgent implements types.Agent.

func (*SequentialAgent) Run 

func (a *SequentialAgent) Run(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

Run implements types.Agent.

func (*SequentialAgent) RunLive 

func (a *SequentialAgent) RunLive(ctx context.Context, parentContext *types.InvocationContext) iter.Seq2[*types.Event, error]

RunLive implements types.Agent.

func (*SequentialAgent) SubAgents 

func (a *SequentialAgent) SubAgents() []types.Agent

SubAgents implements types.Agent.

func (*SequentialAgent) WithAgents 

func (a *SequentialAgent) WithAgents(agents ...types.Agent) *SequentialAgent

WithAgents sets the agents for the sequential agent.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.