agent

Documentation

Overview

Package agent provides entities to build agents using ADK.

Index

• type AfterAgentCallback
• type Agent
  • func New(cfg Config) (Agent, error)
• type Artifacts
• type BeforeAgentCallback
• type CallbackContext
• type Config
• type InvocationContext
• type Loader
  • func NewMultiLoader(root Agent, agents ...Agent) (Loader, error)
  • func NewSingleLoader(a Agent) Loader
• type Memory
• type ReadonlyContext
• type RunConfig
• type StreamingMode

Types

type AfterAgentCallback

type AfterAgentCallback func(CallbackContext) (*genai.Content, error)

AfterAgentCallback is a function that is called after the agent has completed its run. If it returns non-nil content or error, a new event will be created.

The callback will be skipped also if EndInvocation was called before or BeforeAgentCallbacks returned non-nil results.

type Agent

type Agent interface {
	Name() string
	Description() string
	Run(InvocationContext) iter.Seq2[*session.Event, error]
	SubAgents() []Agent
	// contains filtered or unexported methods
}

Agent is the base interface which all agents must implement.

Agents are created with ADK constructors to ensure correct init & configuration. The constructors are available in this package and its subpackages. For example: llmagent.New, workflow agents, remote agent or agent.New. NOTE: in future releases we will allow just implementing this interface. For now agent.New is a correct solution to create custom agents.

func New

func New(cfg Config) (Agent, error)

New creates an Agent with a custom logic defined by Run function.

type Artifacts

type Artifacts interface {
	Save(ctx context.Context, name string, data *genai.Part) (*artifact.SaveResponse, error)
	List(context.Context) (*artifact.ListResponse, error)
	Load(ctx context.Context, name string) (*artifact.LoadResponse, error)
	LoadVersion(ctx context.Context, name string, version int) (*artifact.LoadResponse, error)
}

Artifacts interface provides methods to work with artifacts of the current session.

type BeforeAgentCallback

type BeforeAgentCallback func(CallbackContext) (*genai.Content, error)

BeforeAgentCallback is a function that is called before the agent starts its run. If it returns non-nil content or error, the agent run will be skipped and a new event will be created.

type CallbackContext

type CallbackContext interface {
	ReadonlyContext

	Artifacts() Artifacts
	State() session.State
}

CallbackContext is passed to user callbacks during agent execution.

type Config

type Config struct {
	// Name must be a non-empty string, unique within the agent tree.
	// Agent name cannot be "user", since it's reserved for end-user's input.
	Name string
	// Description of the agent's capability.
	//
	// LLM uses this to determine whether to delegate control to the agent.
	// One-line description is enough and preferred.
	Description string
	// SubAgents are the child agents that this agent can delegate tasks to.
	// ADK will automatically set a parent of each sub-agent to this agent to
	// allow agent transferring across the tree.
	SubAgents []Agent

	// BeforeAgentCallbacks is a list of callbacks that are called sequentially
	// before the agent starts its run.
	//
	// If any callback returns non-nil content or error, then the agent run and
	// the remaining callbacks will be skipped, and a new event will be created
	// from the content or error of that callback.
	BeforeAgentCallbacks []BeforeAgentCallback
	// Run is the function that defines the agent's behavior.
	Run func(InvocationContext) iter.Seq2[*session.Event, error]
	// AfterAgentCallbacks is a list of callbacks that are called sequentially
	// after the agent has completed its run.
	//
	// If any callback returns non-nil content or error, then a new event will be
	// created from the content or error of that callback and the remaining
	// callbacks will be skipped.
	AfterAgentCallbacks []AfterAgentCallback
}

Config is the configuration for creating a new Agent.

type InvocationContext

type InvocationContext interface {
	context.Context

	// Agent of this invocation context.
	Agent() Agent

	// Artifacts of the current session.
	Artifacts() Artifacts

	// Memory is scoped to sessions of the current user_id.
	Memory() Memory

	// Session of the current invocation context.
	Session() session.Session

	InvocationID() string

	// Branch of the invocation context.
	// The format is like agent_1.agent_2.agent_3, where agent_1 is the parent
	// of agent_2, and agent_2 is the parent of agent_3.
	//
	// Branch is used when multiple sub-agents shouldn't see their peer agents'
	// conversation history.
	//
	// Applicable to parallel agent because its sub-agents run concurrently.
	Branch() string

	// UserContent that started this invocation.
	UserContent() *genai.Content

	// RunConfig stores the runtime configuration used during this invocation.
	RunConfig() *RunConfig

	// EndInvocation ends the current invocation. This stops any planned agent
	// calls.
	EndInvocation()
	// Ended returns whether the invocation has ended.
	Ended() bool
}

InvocationContext represents the context of an agent invocation.

An invocation:

1. Starts with a user message and ends with a final response.
2. Can contain one or multiple agent calls.
3. Is handled by runner.Run().

An invocation runs an agent until it does not request to transfer to another agent.

An agent call:

1. Is handled by agent.Run().
2. Ends when agent.Run() ends.

An agent call can contain one or multiple steps. For example, LLM agent runs steps in a loop until:

1. A final response is generated.
2. The agent transfers to another agent.
3. EndInvocation() was called by the invocation context.

A step:

1. Calls the LLM only once and yields its response.
2. Calls the tools and yields their responses if requested.

The summarization of the function response is considered another step, since it is another LLM call. A step ends when it's done calling LLM and tools, or if the EndInvocation() was called by invocation context at any time.

┌─────────────────────── invocation ──────────────────────────┐
┌──────────── llm_agent_call_1 ────────────┐ ┌─ agent_call_2 ─┐
┌──── step_1 ────────┐ ┌───── step_2 ──────┐
[call_llm] [call_tool] [call_llm] [transfer]

type Loader

type Loader interface {
	// ListAgents returns a list of names of all agents
	ListAgents() []string
	// LoadAgent returns an agent by its name. Returns error if there is no agent with such a name.
	LoadAgent(name string) (Agent, error)
	// RootAgent returns the root agent
	RootAgent() Agent
}

Loader allows to load a particular agent by name and get the root agent

func NewMultiLoader

func NewMultiLoader(root Agent, agents ...Agent) (Loader, error)

NewMultiLoader returns a new AgentLoader with the given root Agent and other agents. Returns an error if more than one agent (including root) shares the same name

func NewSingleLoader

func NewSingleLoader(a Agent) Loader

NewSingleLoader returns a loader with only one agent, which becomes the root agent

type Memory

type Memory interface {
	AddSession(context.Context, session.Session) error
	Search(ctx context.Context, query string) (*memory.SearchResponse, error)
}

Memory interface provides methods to access agent memory across the sessions of the current user_id.

type ReadonlyContext

type ReadonlyContext interface {
	context.Context

	// UserContent that started this invocation.
	UserContent() *genai.Content
	InvocationID() string
	AgentName() string
	ReadonlyState() session.ReadonlyState

	UserID() string
	AppName() string
	SessionID() string
	// Branch of the current invocation.
	Branch() string
}

ReadonlyContext provides read-only access to invocation context data.

type RunConfig

type RunConfig struct {
	// StreamingMode defines the streaming mode for an agent.
	StreamingMode StreamingMode
	// If true, ADK runner will save each part of the user input that is a blob
	// (e.g., images, files) as an artifact.
	SaveInputBlobsAsArtifacts bool
}

RunConfig controls runtime behavior of an agent.

type StreamingMode

type StreamingMode string

StreamingMode defines the streaming mode for agent execution.

const (
	// StreamingModeNone indicates no streaming.
	StreamingModeNone StreamingMode = "none"
	// StreamingModeSSE enables server-sent events streaming, one-way, where
	// LLM response parts are streamed immediately as they are generated.
	StreamingModeSSE StreamingMode = "sse"
)