types

type APIKeyIn string

type APIKeySecurityScheme struct {
	Type AuthCredentialTypes `json:"type"`
	In   APIKeyIn            `json:"in,omitzero"`
	Name string              `json:"name,omitzero"`
}

type ActiveStreamingTool[T any] struct {
	// The active task of this streaming tool.
	Task *pyasyncio.Task[T]

	// Stream is the active LiveRequestQueue for this tool.
	Stream *LiveRequestQueue
	// contains filtered or unexported fields
}

type AfterModelCallback func(cctx *CallbackContext, response *LLMResponse) (*LLMResponse, error)

type AfterToolCallback func(tool Tool, args map[string]any, toolCtx *ToolContext, toolResponse map[string]any) (map[string]any, error)

type Agent interface {
	// Name returns the agent's name.
	//
	// Agent name must be a Python identifier and unique within the agent tree.
	// Agent name cannot be "user", since it's reserved for end-user's input.
	Name() string

	// Description returns the description about the agent's capability.
	//
	// The model uses this to determine whether to delegate control to the agent.
	// One-line description is enough and preferred.
	Description() string

	// ParentAgent is the parent agent of this agent.
	//
	// Note that an agent can ONLY be added as sub-agent once.
	//
	// If you want to add one agent twice as sub-agent, consider to create two agent
	// instances with identical config, but with different name and add them to the
	// agent tree.
	ParentAgent() Agent

	// SubAgents returns the sub-agents of this agent.
	SubAgents() []Agent

	// BeforeAgentCallbacks returns the list of [AgentCallback] to be invoked before the agent run.
	//
	// When a list of callbacks is provided, the callbacks will be called in the
	// order they are listed until a callback does not return None.
	BeforeAgentCallbacks() []AgentCallback

	// AfterAgentCallbacks returns the list of [AgentCallback] to be invoked after the agent run.
	//
	// When a list of callbacks is provided, the callbacks will be called in the
	// order they are listed until a callback does not return None.
	AfterAgentCallbacks() []AgentCallback

	// Execute is the core logic to run this agent via text-based conversation.
	//
	// Execute is equivalent to [agents._run_async_impl] in adk-python.
	Execute(ctx context.Context, ictx *InvocationContext) iter.Seq2[*Event, error]

	// ExecuteLive is the core logic to run this agent via video/audio-based conversation.
	//
	// ExecuteLive is equivalent to [agents._run_live_impl] in adk-python.
	ExecuteLive(ctx context.Context, ictx *InvocationContext) iter.Seq2[*Event, error]

	// Run is the entry method to run an agent via text-based conversation.
	//
	// Run is equivalent to [agents.run_async] in adk-python.
	Run(ctx context.Context, parentContext *InvocationContext) iter.Seq2[*Event, error]

	// RunLive is the entry method to run an agent via video/audio-based conversation.
	//
	// RunLive is equivalent to [agents.run_live] in adk-python.
	RunLive(ctx context.Context, parentContext *InvocationContext) iter.Seq2[*Event, error]

	// Gets the root agent of this agent.
	RootAgent() Agent

	// FindAgent finds the agent with the given name in this agent and its descendants.
	FindAgent(name string) Agent

	// FindSubAgent finds the agent with the given name in this agent's descendants.
	FindSubAgent(name string) Agent

	// AsLLMAgent reports whether this agent is an [LLMAgent].
	AsLLMAgent() (LLMAgent, bool)
}

type AgentCallback func(cctx *CallbackContext) (*genai.Content, error)

type ArtifactService interface {
	// SaveArtifact saves an artifact to the artifact service storage.
	//
	// The artifact is a file identified by the app name, user ID, session ID, and
	// filename. After saving the artifact, a revision ID is returned to identify
	// the artifact version.
	SaveArtifact(ctx context.Context, appName, userID, sessionID, filename string, artifact *genai.Part) (int, error)

	// LoadArtifact gets an artifact from the artifact service storage.
	//
	// The artifact is a file identified by the app name, user ID, session ID, and filename.
	LoadArtifact(ctx context.Context, appName, userID, sessionID, filename string, version int) (*genai.Part, error)

	// ListArtifactKey lists all the artifact filenames within a session.
	ListArtifactKey(ctx context.Context, appName, userID, sessionID string) ([]string, error)

	// DeleteArtifact deletes an artifact.
	DeleteArtifact(ctx context.Context, appName, userID, sessionID, filename string) error

	// ListVersions lists all versions of an artifact.
	ListVersions(ctx context.Context, appName, userID, sessionID, filename string) ([]int, error)

	// Close closes the artifact service connection.
	Close() error
}

type AuthConfig struct {
	// The auth scheme used to collect credentials
	AuthScheme AuthScheme

	// The raw auth credential used to collect credentials. The raw auth
	// credentials are used in some auth scheme that needs to exchange auth
	// credentials. e.g. OAuth2 and OIDC. For other auth scheme, it could be None.
	RawAuthCredential *AuthCredential

	// The exchanged auth credential used to collect credentials. adk and client
	// will work together to fill it. For those auth scheme that doesn't need to
	// exchange auth credentials, e.g. API key, service account etc. It's filled by
	// client directly. For those auth scheme that need to exchange auth credentials,
	// e.g. OAuth2 and OIDC, it's first filled by adk. If the raw credentials
	// passed by tool only has client id and client credential, adk will help to
	// generate the corresponding authorization uri and state and store the processed
	// credential in this field. If the raw credentials passed by tool already has
	// authorization uri, state, etc. then it's copied to this field. Client will use
	// this field to guide the user through the OAuth2 flow and fill auth response in
	// this field.
	ExchangedAuthCredential *AuthCredential
	// contains filtered or unexported fields
}

type AuthCredential struct {
	AuthType AuthCredentialTypes `json:"auth_type,omitzero"`

	// Resource reference for the credential.
	// This will be supported in the future.
	ResourceRef string `json:"resource_ref,omitzero"`

	APIKey         string          `json:"api_key,omitzero"`
	HTTP           *HTTPAuth       `json:"http,omitzero"`
	ServiceAccount *ServiceAccount `json:"service_account,omitzero"`
	OAuth2         *OAuth2Auth     `json:"oauth2,omitzero"`
}

type AuthCredentialTypes string

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

type AuthScheme interface {
	AuthType() AuthCredentialTypes
}

type AuthToolArguments struct {
	// FunctionCallID is the ID of the function call requesting authentication.
	FunctionCallID string `json:"function_call_id"`

	// AuthConfig is the authentication configuration requested.
	AuthConfig *AuthConfig `json:"auth_config"`
}

type AuthenticatedTool interface {
	Tool

	// Execute executes the tool logic with the provided arguments, tool context, and authentication credential.
	Execute(ctx context.Context, args map[string]any, toolCtx *ToolContext, credential *AuthCredential) (any, error)
}

type BaseAgent struct {
	*Config
}

type BeforeModelCallback func(cctx *CallbackContext, request *LLMRequest) (*LLMResponse, error)

type BeforeToolCallback func(tool Tool, args map[string]any, toolCtx *ToolContext) (map[string]any, error)

type CallbackContext struct {
	*ReadOnlyContext
	// contains filtered or unexported fields
}

type CodeExecutionFile struct {
	// Name is the filename, including any relative path.
	Name string `json:"name"`

	// Content is the raw file content as bytes.
	Content []byte `json:"-"`

	// MIMEType specifies the MIME type of the file content.
	// If empty, it will be inferred from the file extension or content.
	MIMEType string `json:"mime_type,omitempty"`

	// Size is the size of the content in bytes.
	Size int64 `json:"size"`
}

type CodeExecutionInput struct {
	// Code is the code to execute.
	Code string `json:"code"`

	// Language specifies the programming language (e.g., "python", "go", "javascript").
	// If empty, the executor may attempt to auto-detect or use a default.
	Language string `json:"language,omitempty"`

	// InputFiles are files that should be available to the code during execution.
	InputFiles []*CodeExecutionFile `json:"input_files,omitempty"`

	// ExecutionID is an optional identifier for stateful execution sessions.
	// When provided, stateful executors will maintain session state across calls.
	ExecutionID string `json:"execution_id,omitempty"`

	// WorkingDirectory specifies the directory where code should be executed.
	// If empty, a temporary directory will be used.
	WorkingDirectory string `json:"working_directory,omitempty"`

	// Environment contains environment variables to set during execution.
	Environment map[string]string `json:"environment,omitempty"`

	// Timeout specifies the maximum execution time.
	// If zero, the executor's default timeout will be used.
	Timeout time.Duration `json:"timeout,omitempty"`
}

type CodeExecutionResult struct {
	// Code is the code to execute.
	Code string `json:"code"`

	// Stdout contains the standard output from the executed code.
	Stdout string `json:"stdout"`

	// Stderr contains the standard error output from the executed code.
	Stderr string `json:"stderr"`

	// OutputFiles contains files generated during code execution.
	OutputFiles []*CodeExecutionFile `json:"output_files,omitempty"`

	// ExitCode is the exit code returned by the executed code.
	// A value of 0 typically indicates success.
	ExitCode int `json:"exit_code"`

	Timestamp time.Time `json:"timestamp"`

	// ExecutionTime is the duration the code took to execute.
	ExecutionTime time.Duration `json:"execution_time"`

	// ExecutionID is the session identifier used for this execution.
	ExecutionID string `json:"execution_id,omitempty"`

	// Error contains any execution error that occurred.
	// This is separate from stderr and represents infrastructure errors.
	Error error `json:"error,omitempty"`
}

type CodeExecutor interface {
	// OptimizeDataFile reports whether the extract and process data files from the model request
	// and attach them to the code executor.
	// Supported data file MimeTypes are [text/csv].
	//
	// Default to false.
	OptimizeDataFile() bool

	// IsLongRunning reports whether the code executor supports long-running operations.
	IsLongRunning() bool

	// IsStateful reports whether the code executor is stateful.
	//
	// Stateful executors can reuse variables and imports across multiple Execute calls.
	IsStateful() bool

	// ErrorRetryAttempts returns the number of attempts to retry on consecutive code execution errors.
	//
	// Default to 2.
	ErrorRetryAttempts() int

	// CodeBlockDelimiters returns the list of the enclosing delimiters to identify the code blocks.
	//
	// For example, the delimiter ('“`python\n', '\n“`') can be
	// used to identify code blocks with the following format:
	//
	//  “`python
	//  print("hello")
	//  “`
	CodeBlockDelimiters() []DelimiterPair

	// ExecutionResultDelimiters returns the delimiters to format the code execution result.
	ExecutionResultDelimiters() DelimiterPair

	// Execute runs the provided code and returns the execution result.
	// The context can be used for cancellation and timeout control.
	ExecuteCode(ctx context.Context, ictx *InvocationContext, input *CodeExecutionInput) (*CodeExecutionResult, error)

	// Close cleans up any resources used by the executor.
	Close() error
}

type Config struct {
	// The agent's Name.
	//
	// Agent Name must be a Go identifier and unique within the agent tree.
	// Agent Name cannot be "user", since it's reserved for end-user's input.
	Name string

	// Description about the agent's capability.
	//
	// The model uses this to determine whether to delegate control to the agent.
	// One-line Description is enough and preferred.
	Description string
	// contains filtered or unexported fields
}

type CredentialExchangError string

type CredentialExchanger interface {
	// Exchange exchange credential if needed.
	Exchange(ctx context.Context, authCredential *AuthCredential, authScheme AuthScheme) (*AuthCredential, error)
}

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

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

type CredentialRefresher interface {
	// IsRefreshNeeded checks if a credential needs to be refreshed.
	IsRefreshNeeded(ctx context.Context, authCredential *AuthCredential, authScheme AuthScheme) bool

	// Refresh refreshes a credential if needed.
	Refresh(ctx context.Context, authCredential *AuthCredential, authScheme AuthScheme) (*AuthCredential, error)
}

type CredentialRefresherError string

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

type CredentialService interface {
	// LoadCredential loads the credential by auth config and current tool context from the
	// backend credential store.
	LoadCredential(ctx context.Context, authConfig *AuthConfig, toolCtx *ToolContext) (*AuthCredential, error)

	// SaveCredential saves the exchanged_auth_credential in auth config to the backend credential
	// store.
	SaveCredential(ctx context.Context, authConfig *AuthConfig, toolCtx *ToolContext) error
}

type DelimiterPair struct {
	Start string
	End   string
}

type Event struct {
	*LLMResponse

	// InvocationID is The invocation ID of the event.
	// TODO(adk-python): revert to be required after spark migration
	InvocationID string

	// Author is the 'user' or the name of the agent, indicating who appended the event to the session.
	Author string

	// Actions is the Actions taken by the agent
	Actions *EventActions

	// LongRunningToolIDs set of ids of the long running function calls.
	//
	// Agent client will know from this field about which function call is long running.
	// Only valid for function call event.
	LongRunningToolIDs py.Set[string]

	// Branch is The Branch of the event.
	//
	// 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-agent shouldn't see their peer agents'
	// conversation history.
	Branch string

	// ID is the unique identifier of the event.
	//
	// ReadOnly. It will be assigned by the session layer.
	ID string

	// Timestamp is The Timestamp of the event.
	//
	// ReadOnly. It will be assigned by the session layer.
	Timestamp time.Time
}

type EventActions struct {
	// SkipSummarization if true, it won't call model to summarize function response.
	//
	// Only used for functionResponse event.
	SkipSummarization bool

	// StateDelta indicates that the event is updating the state with the given delta.
	StateDelta map[string]any

	// ArtifactDelta indicates that the event is updating an artifact. key is the filename, value is the version.
	ArtifactDelta map[string]int

	// TransferToAgent if set, the event transfers to the specified agent.
	TransferToAgent string

	// Escalate is the agent is escalating to a higher level agent.
	Escalate bool

	// RequestedAuthConfigs authentication configurations requested by tool responses.
	//
	// This field will only be set by a tool response event indicating tool request
	// auth credential.
	//
	// Keys:
	// The function call id. Since one function response event could contain
	// multiple function responses that correspond to multiple function calls. Each
	// function call could request different auth configs. This id is used to
	// identify the function call.
	//
	// Values:
	// The requested auth config.
	RequestedAuthConfigs map[string]*AuthConfig
}

type ExecutionConfig struct {
	// OptimizeDataFiles enables optimization for large data files (e.g., CSV processing).
	OptimizeDataFiles bool

	// LongRunning indicates whether the code executor supports long-running operations.
	LongRunning bool

	// Stateful whether the code executor is stateful.
	Stateful bool

	// MaxRetries specifies the maximum number of retry attempts for failed executions.
	MaxRetries int

	// RetryDelay specifies the delay between retry attempts.
	RetryDelay time.Duration

	// DefaultTimeout specifies the default execution timeout.
	DefaultTimeout time.Duration

	// CodeBlockDelimiters defines the patterns used to extract code blocks from text.
	CodeBlockDelimiters []DelimiterPair

	// ExecutionResultDelimiters defines the patterns used to format execution results.
	ExecutionResultDelimiters DelimiterPair
}

type ExecutionOption func(*ExecutionConfig)

type Flow interface {
	// Run runs the flow with the given invocation context and returns a sequence of events.
	Run(ctx context.Context, ictx *InvocationContext) iter.Seq2[*Event, error]

	// RunLive runs the flow with the given invocation context in a live mode and returns a sequence of events.
	RunLive(ctx context.Context, ictx *InvocationContext) iter.Seq2[*Event, error]
}

type GetSessionConfig struct {
	NumRecentEvents int
	AfterTimestamp  time.Time
}

type HTTPAuth struct {
	Scheme      string          `json:"scheme"`
	Credentials HTTPCredentials `json:"Credentials"`
}

type HTTPBaseSecurityScheme struct {
	Type   AuthCredentialTypes `json:"type"`
	Scheme string              `json:"scheme,omitzero"`
}

type HTTPCredentials struct {
	Username string `json:"username"`
	Password string `json:"password"`
	Token    string `json:"token"`
}

type IncludeContents string

type InstructionProvider func(rctx *ReadOnlyContext) string

type InvocationContext struct {
	ArtifactService   ArtifactService
	SessionService    SessionService
	MemoryService     MemoryService
	CredentialService CredentialService

	// InvocationID is the id of this invocation context. Readonly.
	InvocationID string

	// The 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.
	Branch string

	// The current agent of this invocation context. Readonly.
	Agent Agent

	// The user content that started this invocation. Readonly.
	UserContent *genai.Content

	// The current session of this invocation context. Readonly.
	Session Session

	// Whether to end this invocation.
	//
	// Set to True in callbacks or tools to terminate this invocation.
	EndInvocation bool

	// The queue to receive live requests.
	LiveRequestQueue *LiveRequestQueue

	// The running streaming tools of this invocation.
	ActiveStreamingTools map[string]*ActiveStreamingTool[any]

	// Caches necessary, data audio or contents, that are needed by transcription.
	TranscriptionCache []*TranscriptionEntry

	// Configurations for live agents under this invocation.
	RunConfig *RunConfig
	// contains filtered or unexported fields
}

type InvocationContextOption func(*InvocationContext)

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

type LLMAgent interface {
	Agent

	// CanonicalModel returns the resolved model field as [model.Model].
	//
	// This method is only for use by Agent Development Kit.
	CanonicalModel(ctx context.Context) (Model, error)

	// CanonicalInstructions returns the resolved self.instruction field to construct instruction for this agent.
	//
	// This method is only for use by Agent Development Kit.
	CanonicalInstructions(rctx *ReadOnlyContext) string

	// CanonicalGlobalInstruction returns the resolved self.instruction field to construct global instruction.
	//
	// This method is only for use by Agent Development Kit.
	CanonicalGlobalInstruction(rctx *ReadOnlyContext) (string, bool)

	// 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.
	CanonicalTool(rctx *ReadOnlyContext) []Tool

	// GenerateContentConfig returns the [*genai.GenerateContentConfig] for [LLMAgent] agent.
	GenerateContentConfig() *genai.GenerateContentConfig

	// DisallowTransferToParent reports whether teh disallows LLM-controlled transferring to the parent agent.
	DisallowTransferToParent() bool

	// DisallowTransferToPeers reports whether teh disallows LLM-controlled transferring to the peer agents.
	DisallowTransferToPeers() bool

	// IncludeContents returns the mode of include contents in the model request.
	IncludeContents() IncludeContents

	// InputSchema returns the structured input.
	InputSchema() *genai.Schema

	// OutputSchema returns the structured output.
	OutputSchema() *genai.Schema

	// OutputKey returns the key in session state to store the output of the agent.
	OutputKey() string

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

	// CodeExecutor returns the code executor for the agent.
	CodeExecutor() CodeExecutor

	// BeforeModelCallbacks returns the resolved self.before_model_callback field as a list of _SingleBeforeModelCallback.
	//
	// This method is only for use by Agent Development Kit.
	BeforeModelCallbacks() []BeforeModelCallback

	// AfterModelCallbacks returns the resolved self.before_tool_callback field as a list of BeforeToolCallback.
	//
	// This method is only for use by Agent Development Kit.
	AfterModelCallbacks() []AfterModelCallback

	// BeforeToolCallbacks returns the resolved self.before_tool_callback field as a list of BeforeToolCallback.
	//
	// This method is only for use by Agent Development Kit.
	BeforeToolCallback() []BeforeToolCallback

	// AfterToolCallbacks returns the resolved self.after_tool_callback field as a list of AfterToolCallback.
	//
	// This method is only for use by Agent Development Kit.
	AfterToolCallbacks() []AfterToolCallback
}

type LLMCallsLimitExceededError string

type LLMRequest struct {
	// The model name.
	Model string `json:"model,omitempty"`

	// The contents to send to the model.
	Contents []*genai.Content `json:"contents"`

	// Additional config for the generate content request.
	//
	// tools in generate_content_config should not be set.
	Config            *genai.GenerateContentConfig `json:"config,omitempty"`
	LiveConnectConfig *genai.LiveConnectConfig     `json:"live_connect_config,omitempty"`

	// The tools map.
	ToolMap map[string]Tool `json:"tool_map,omitempty"`
}

type LLMRequestOption func(*LLMRequest)

type LLMRequestProcessor interface {
	// Run runs the processor.
	Run(ctx context.Context, ictx *InvocationContext, request *LLMRequest) iter.Seq2[*Event, error]
}

type LLMResponse struct {
	// Content is the content of the response.
	Content *genai.Content

	// GroundingMetadata is the grounding metadata of the response.
	GroundingMetadata *genai.GroundingMetadata

	// Partial indicates whether the text content is part of an unfinished text stream.
	// Only used for streaming mode and when the content is plain text.
	Partial bool

	// TurnComplete indicates whether the response from the model is complete.
	// Only used for streaming mode.
	TurnComplete bool

	// ErrorCode is the error code if the response is an error. Code varies by model.
	ErrorCode string

	// ErrorMessage is the error message if the response is an error.
	ErrorMessage string

	// Interrupted indicates that LLM was interrupted when generating the content.
	// Usually it's due to user interruption during a bidirectional streaming.
	Interrupted bool

	// CustomMetadata is the custom metadata of the LLMResponse.
	// An optional key-value pair to label an LLMResponse.
	// The entire map must be JSON serializable.
	CustomMetadata map[string]any

	FinishReason genai.FinishReason

	UsageMetadata *genai.GenerateContentResponseUsageMetadata
}

type LLMResponseProcessor interface {
	// Run processes the LLM response.
	Run(ctx context.Context, ictx *InvocationContext, response *LLMResponse) iter.Seq2[*Event, error]
}

type ListEventsResponse struct {
	Events        []*Event
	NextPageToken string
}

type ListSessionsResponse struct {
	Sessions []Session
}

type LiveRequest struct {
	// Send the content to the model in turn-by-turn mode if any.
	Content *genai.Content `json:"content,omitempty"`

	// Send the blob to the model in realtime mode if any.
	Blob *genai.Blob `json:"blob,omitempty"`

	// Close the queue.
	Close bool `json:"close"`
}

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

type MemoryEntry struct {
	// The main content of the memory.
	Content *genai.Content

	// The author of the memory.
	Author string

	// The timestamp when the original content of this memory happened.
	//
	// This string will be forwarded to LLM. Preferred format is ISO 8601 format.
	Timestamp time.Time
}

type MemoryService interface {
	// AddSessionToMemory adds the contents of a session to memory.
	AddSessionToMemory(ctx context.Context, session Session) error

	// SearchMemory searches for sessions that match the query.
	SearchMemory(ctx context.Context, appName, userID, query string) (*SearchMemoryResponse, error)

	// Close closes the underlying memory client and releases resources.
	Close() error
}

type Model interface {
	// Name returns the name of the LLM model.
	//
	// e.g. gemini-1.5-flash or gemini-1.5-flash-001.
	Name() string

	// SupportedModels returns a list of supported models for the [LLMRegistry].
	SupportedModels() []string

	// Connect creates a live connection to the LLM.
	Connect(ctx context.Context, request *LLMRequest) (ModelConnection, error)

	// GenerateContent Generates one content from the given contents and tools.
	GenerateContent(ctx context.Context, request *LLMRequest) (*LLMResponse, error)

	// StreamGenerateContent generates one content from the given contents and tools with streaming call.
	StreamGenerateContent(ctx context.Context, request *LLMRequest) iter.Seq2[*LLMResponse, error]
}

type ModelConnection interface {
	// SendHistory sends the conversation history to the model.
	// The model will respond if the last content is from user, otherwise it will
	// wait for new user input before responding.
	SendHistory(ctx context.Context, history []*genai.Content) error

	// SendContent sends a user content to the model.
	// The model will respond immediately upon receiving the content.
	SendContent(ctx context.Context, content *genai.Content) error

	// SendRealtime sends a chunk of audio or a frame of video to the model in realtime.
	// The model may not respond immediately upon receiving the blob.
	SendRealtime(ctx context.Context, blob []byte, mimeType string) error

	// Receive returns a channel that yields model responses.
	// It should be called after SendHistory, SendContent, or SendRealtime.
	Receive(ctx context.Context) iter.Seq2[*LLMResponse, error]

	// Close terminates the connection to the model.
	// The connection object should not be used after this call.
	Close() error
}

type NotImplementedError string

type OAuth2Auth struct {
	ClientID     string `json:"client_id,omitzero"`
	ClientSecret string `json:"client_secret,omitzero"`
	// tool or adk can generate the auth_uri with the state info thus client
	// can verify the state
	AuthURI string `json:"auth_uri,omitzero"`
	State   string `json:"state,omitzero"`
	// tool or adk can decide the redirect_uri if they don't want client to decide
	RedirectURI     string    `json:"redirect_uri,omitzero"`
	AuthResponseURI string    `json:"auth_response_uri,omitzero"`
	AuthCode        string    `json:"auth_code,omitzero"`
	AccessToken     string    `json:"access_token,omitzero"`
	RefreshToken    string    `json:"refresh_token,omitzero"`
	ExpiresAt       time.Time `json:"expires_at,omitzero"`
	ExpiresIn       int64     `json:"expires_in,omitzero"`
}

type OAuth2CredentialRefresher struct{}

type OAuth2SecurityScheme struct {
	Type  AuthCredentialTypes `json:"type"`
	Flows *OAuthFlows         `json:"flows"`
}

type OAuth2Session struct {
	*oauth2.Config
	State string
}

type OAuthFlow struct {
	AuthorizationURL string            `json:"authorizationUrl,omitzero"`
	TokenURL         string            `json:"tokenUrl,omitzero"`
	RefreshURL       string            `json:"refreshUrl,omitzero"`
	Scopes           map[string]string `json:"scopes,omitzero"`
}

type OAuthFlows struct {
	Implicit          *OAuthFlow `json:"implicit,omitzero"`
	Password          *OAuthFlow `json:"password,omitzero"`
	ClientCredentials *OAuthFlow `json:"clientCredentials,omitzero"`
	AuthorizationCode *OAuthFlow `json:"authorizationCode,omitzero"`
}

type OAuthGrantType string

type OpenIDConnectWithConfig struct {
	Type                              AuthCredentialTypes `json:"type"`
	AuthorizationEndpoint             string              `json:"authorization_endpoint"`
	TokenEndpoint                     string              `json:"token_endpoint"`
	UserinfoEndpoint                  string              `json:"userinfo_endpoint,omitzero"`
	RevocationEndpoint                string              `json:"revocation_endpoint,omitzero"`
	TokenEndpointAuthMethodsSupported string              `json:"token_endpoint_auth_methods_supported,omitzero"`
	GrantTypesSupported               []string            `json:"grant_types_supported,omitzero"`
	Scopes                            []string            `json:"scopes,omitzero"`
}

type OpenIdConnectSecurityScheme struct {
	Type             AuthCredentialTypes `json:"type"`
	OpenIDConnectURL string              `json:"openIdConnectUrl"`
}

type Option interface {
	// contains filtered or unexported methods
}

type Planner interface {
	// BuildPlanningInstruction builds the system instruction to be appended to the LLM request for planning.
	BuildPlanningInstruction(ctx context.Context, rctx *ReadOnlyContext, request *LLMRequest) string

	// ProcessPlanningResponse Processes the LLM response for planning.
	ProcessPlanningResponse(ctx context.Context, cctx *CallbackContext, responseParts []*genai.Part) []*genai.Part
}

type ReadOnlyContext struct {
	InvocationContext *InvocationContext
}

type RunConfig struct {
	// Speech configuration for the live agent.
	SpeechConfig *genai.SpeechConfig

	// The output modalities. If not set, it's default to AUDIO.
	ResponseModalities []genai.Modality

	// Whether or not to save the input blobs as artifacts.
	SaveInputBlobsAsArtifacts bool

	// Whether to support CFC (Compositional Function Calling). Only applicable for
	// StreamingMode.SSE. If it's true. the LIVE API will be invoked. Since only LIVE
	// API supports CFC
	SupportCFC bool

	// Streaming mode.
	StreamingMode StreamingMode

	// Output transcription for live agents with audio response.
	OutputAudioTranscription *genai.AudioTranscriptionConfig

	// Input transcription for live agents with audio input from user.
	InputAudioTranscription *genai.AudioTranscriptionConfig

	// A limit on the total number of llm calls for a given run.
	MaxLLMCalls int
}

type SearchMemoryResponse struct {
	// Results are the memory items matching the search.
	Memories []*MemoryEntry `json:"memories"`
}

type SecurityScheme interface {
	AuthScheme
	// contains filtered or unexported methods
}

type ServiceAccount struct {
	ServiceAccountCredential ServiceAccountCredential `json:"service_account_credential,omitzero"`
	Scopes                   []string                 `json:"scopes"`
	UseDefaultCredential     bool                     `json:"use_default_credential,omitzero"`
}

type ServiceAccountCredential struct {
	ProjectID               string `json:"project_id"`
	PrivateKeyID            string `json:"private_key_id"`
	PrivateKey              string `json:"private_key"`
	ClientEmail             string `json:"client_email"`
	ClientID                string `json:"client_id"`
	AuthURI                 string `json:"auth_uri"`
	TokenURI                string `json:"token_uri"`
	AuthProviderX509CertURL string `json:"auth_provider_x509_cert_url"`
	ClientX509CertURL       string `json:"client_x509_cert_url"`
	UniverseDomain          string `json:"universe_domain"`
}

type Session interface {
	// ID returns the session ID.
	ID() string

	// AppName returns the application name.
	AppName() string

	// UserID returns the user ID.
	UserID() string

	// State is the state of the session.
	State() map[string]any

	// Events returns the events in the session.
	Events() []*Event

	// LastUpdateTime is the last update time of the session.
	LastUpdateTime() time.Time

	// AddEvent adds an event to this session.
	AddEvent(events ...*Event)

	// GetRecentEvents returns the most recent n events.
	SetLastUpdateTime(time.Time)
}

type SessionService interface {
	// CreateSession creates a new session with the given parameters.
	CreateSession(ctx context.Context, appName, userID, sessionID string, state map[string]any) (Session, error)

	// GetSession retrieves a specific session.
	// If maxEvents is > 0, only return the last maxEvents events.
	// If since is not nil, only return events after the given time.
	GetSession(ctx context.Context, appName, userID, sessionID string, config *GetSessionConfig) (Session, error)

	// ListSessions lists all sessions for a user/app.
	ListSessions(ctx context.Context, appName, userID string) ([]Session, error)

	// DeleteSession removes a specific session.
	DeleteSession(ctx context.Context, appName, userID, sessionID string) error

	// // AppendEvent adds an event to a session and updates session state.
	AppendEvent(ctx context.Context, sess Session, event *Event) (*Event, error)

	// ListEvents retrieves events within a session.
	ListEvents(ctx context.Context, appName, userID, sessionID string, maxEvents int, since *time.Time) ([]Event, error)
}

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

type StreamingMode int

type Tool interface {
	// Name returns the name of the tool.
	Name() string

	// Description returns the description of the tool.
	Description() string

	// IsLongRunning whether the tool is a long running operation, which typically returns a
	// resource id first and finishes the operation later.
	IsLongRunning() bool

	// GetDeclaration gets the OpenAPI specification of this tool in the form of a [*genai.FunctionDeclaration].
	GetDeclaration() *genai.FunctionDeclaration

	// Run runs the tool with the given arguments and context.
	Run(ctx context.Context, args map[string]any, toolCtx *ToolContext) (any, error)

	// ProcessLLMRequest processes the outgoing LLM request for this tool.
	ProcessLLMRequest(ctx context.Context, toolCtx *ToolContext, request *LLMRequest) error
}

type ToolCall struct {
	// Name is the name of the tool.
	Name string

	// Input is the input provided to the tool.
	Input map[string]any

	// Output is the result from the tool execution.
	Output map[string]any

	// Error is set if the tool call failed.
	Error error
}

type ToolContext struct {
	*CallbackContext
	// contains filtered or unexported fields
}

type Toolset interface {
	// GetTools returns the all tools in the toolset based on the provided context.
	GetTools(rctx *ReadOnlyContext) []Tool

	// Close performs cleanup and releases resources held by the toolset.
	//
	// NOTE: This method is invoked, for example, at the end of an agent server's
	// lifecycle or when the toolset is no longer needed. Implementations
	// should ensure that any open connections, files, or other managed
	// resources are properly released to prevent leaks.
	Close()
}

type TranscriptionEntry struct {
	// The role that created this data, typically "user" or "model".
	Role string

	// The data that can be used for transcription.
	Data any
}