agent

package
v0.3.2 Latest Latest
Warning

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

 Go to latest Published: Jul 28, 2026 License: Apache-2.0 Imports: 35 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StatusPending   = types.StatusPending
	StatusRunning   = types.StatusRunning
	StatusCompleted = types.StatusCompleted
	StatusFailed    = types.StatusFailed
	StatusCancelled = types.StatusCancelled
)

Run status constants, mirroring types.RunStatus values for use without a types import.

View Source 
const (
	ApprovalRequestNameTool     = types.ApprovalRequestNameTool
	ApprovalRequestNameSubAgent = types.ApprovalRequestNameSubAgent
)
View Source 
const (
	AgentModeInteractive = types.AgentModeInteractive
	AgentModeAutonomous  = types.AgentModeAutonomous
)
View Source 
const (
	AgentToolExecutionModeParallel   = types.AgentToolExecutionModeParallel
	AgentToolExecutionModeSequential = types.AgentToolExecutionModeSequential
)
View Source 
const (
	RetrieverModeAgentic  = types.RetrieverModeAgentic
	RetrieverModePrefetch = types.RetrieverModePrefetch
	RetrieverModeHybrid   = types.RetrieverModeHybrid
)

Variables

View Source 
var (
	// ErrStreamNotFound is returned when a stream runID is not recognised by the runtime.
	ErrStreamNotFound = types.ErrStreamNotFound

	// ErrStreamOffsetNotSupported is returned when the runtime cannot replay at the requested offset
	// (e.g. LocalRuntime with fromOffset > 0).
	ErrStreamOffsetNotSupported = types.ErrStreamOffsetNotSupported

	// ErrStreamAlreadyConsumed is returned when [AgentStream.Events] is called again on a
	// handle that already handed out its in-process event channel (LocalRuntime).
	ErrStreamAlreadyConsumed = types.ErrStreamAlreadyConsumed

	// ErrRunAlreadyCompleted is returned by [Agent.GetAgentRun], [Agent.GetAgentStream],
	// [AgentStream.Events], or [AgentStream.Get] when the target run has already finished.
	// Callers should read conversation history from the memory store instead of reconnecting.
	ErrRunAlreadyCompleted = types.ErrRunAlreadyCompleted
)

Streaming sentinel errors re-exported from internal/runtime so callers only import pkg/agent.

View Source 
var (
	// ErrRegistryNotFound is returned when Get or Unregister cannot find the name.
	ErrRegistryNotFound = errors.New("agent: registry entry not found")
	// ErrRegistryDuplicate is returned when Register would overwrite an existing name.
	ErrRegistryDuplicate = errors.New("agent: registry entry already exists")
	// ErrRegistryInvalidName is returned when name is empty after trim.
	ErrRegistryInvalidName = errors.New("agent: registry name must not be empty")
	// ErrRegistryNilEntry is returned when Register is called with a nil tool, client, or sub-agent.
	ErrRegistryNilEntry = errors.New("agent: registry entry must not be nil")
)
View Source 
var ErrApprovalAlreadyResolved = types.ErrApprovalAlreadyResolved

ErrApprovalAlreadyResolved is returned by AgentStream.Approve (and the deprecated Agent.OnApproval) when the approval token refers to an activity task that has already been completed (approved or rejected). This can happen when a reconnecting subscriber replays a CUSTOM approval event for an approval that was resolved while the subscriber was disconnected. Treat it as informational — the run is already advancing.

View Source 
var ErrMemoryToolNotExecutable = fmt.Errorf("save_memory must be executed via runtime")

ErrMemoryToolNotExecutable is returned when save_memory runs outside a managed agent runtime.

View Source 
var (
	// ErrRunNotFound is returned when a runID is not recognised by the runtime.
	ErrRunNotFound = types.ErrRunNotFound
)

Sentinel errors re-exported from internal/runtime so callers only import pkg/agent. ErrRunAlreadyCompleted is declared in agent_stream.go (shared by run and stream APIs).

View Source 
var ErrSubAgentNameInvalid = errors.New("sub-agent name invalid for delegation tool")

ErrSubAgentNameInvalid is returned when computing a sub-agent delegation tool name from a display name fails for a delegation tool (empty name, or name contains no letters or digits after normalization).

View Source 
var ErrSubAgentToolNotExecutable = errors.New("sub-agent tool must be delegated via runtime (local: in-process runner, temporal: child workflow)")

ErrSubAgentToolNotExecutable is returned by SubAgentTool.Execute when called outside a managed runtime. Local runtime delegates via SubAgentRunners (in-process); Temporal delegates via child workflows. This error only surfaces if the runtime bypasses the normal SubAgentRunners/workflow delegation path.

Functions

func AllowlistToolApprovalPolicy 

func AllowlistToolApprovalPolicy(c AllowlistToolApprovalConfig) (interfaces.AgentToolApprovalPolicy, error)

AllowlistToolApprovalPolicy builds an allowlist policy from AllowlistToolApprovalConfig. Empty AllowlistToolApprovalConfig.ToolNames and MCP server/tool entries are skipped. Invalid AllowlistToolApprovalConfig.SubAgentNames entries return an error. MCP map iteration order does not affect behavior.

Tool-only allowlisting: AllowlistToolApprovalPolicy(AllowlistToolApprovalConfig{ToolNames: []string{"echo", "calculator"}}).

func AutoToolApprovalPolicy 

func AutoToolApprovalPolicy() interfaces.AgentToolApprovalPolicy

AutoToolApprovalPolicy allows all tools without approval. Use when you trust the agent.

func NewMemoryTool added in v0.2.2 

func NewMemoryTool(store MemoryStoreFunc) interfaces.Tool

NewMemoryTool returns a save_memory tool. Returns nil when store is nil.

func NewRegisteredMemoryTool added in v0.2.2 

func NewRegisteredMemoryTool() interfaces.Tool

NewRegisteredMemoryTool returns save_memory for agent tool registration (memory.StoreModeOnDemand).

func NewRetrieverTool added in v0.1.11 

func NewRetrieverTool(retriever interfaces.Retriever) interfaces.Tool

NewRetrieverTool builds a RetrieverTool. Returns nil when retriever is nil or interfaces.Retriever.Name is empty.

func NewSubAgentTool 

func NewSubAgentTool(sub *Agent) interfaces.Tool

NewSubAgentTool wraps a sub-agent as a tool for the parent LLM. The sub-agent must have a non-empty [Agent.Name] that yields at least one letter or digit after normalization (same normalization as delegation tool names from display names). Returns nil if sub is nil or the name is invalid.

func NoopLogger added in v0.0.10 

func NoopLogger() logger.Logger

NoopLogger returns a logger that discards all SDK log output. Use with WithLogger(NoopLogger()).

func RegisterTools added in v0.2.2 

func RegisterTools(reg ToolRegistry, tools ...interfaces.Tool) error

RegisterTools registers each tool on reg, returning the first error.

Types

type A2AConfig added in v0.1.9 

type A2AConfig struct {
	// URL is the base URL used for card resolution (e.g. "https://agent.example.com").
	URL string
	// Timeout is the per-call HTTP timeout. Zero means the client default (30 s).
	Timeout time.Duration
	// Token is a bearer token injected as "Authorization: Bearer <token>".
	// Ignored (silently) when the value is whitespace-only.
	// Prefer [A2AConfig.Headers] for non-bearer schemes.
	Token string
	// Headers are extra HTTP request headers sent on every call (e.g. "X-Tenant: acme").
	// Header keys are included in the fingerprint; values are not.
	Headers map[string]string
	// SkillFilter restricts which skills from [interfaces.A2AClient.ListSkills] are registered.
	// Set either [types.A2ASkillFilter.AllowSkills] or [types.A2ASkillFilter.BlockSkills], not both.
	// Use [github.com/agenticenv/agent-sdk-go/pkg/a2a.A2ASkillFilter] for the same type in application code.
	SkillFilter types.A2ASkillFilter
	// SkipTLSVerify disables TLS certificate verification for the A2A HTTP client. Use only in development.
	SkipTLSVerify bool
}

A2AConfig describes one A2A agent server: base URL, optional authentication, timeout, and optional skill filter. Zero A2AConfig.Timeout falls back to [defaultA2AToolTimeout] in the fingerprint; the actual client applies its own default from pkg/a2a/client.BuildConfig.

type A2ARegistry added in v0.2.2 

type A2ARegistry interface {
	Register(name string, config A2AConfig) error
	RegisterClient(client interfaces.A2AClient) error
	Get(name string) (interfaces.A2AClient, error)
	List() []interfaces.A2AClient
	Unregister(name string) error
}

A2ARegistry stores A2A clients for an agent.

func NewA2ARegistry added in v0.2.2 

func NewA2ARegistry(l logger.Logger) A2ARegistry

NewA2ARegistry returns an empty A2A client registry for use with WithA2ARegistry. logger is used when [Register] builds a client from A2AConfig.

type A2AServerConfig added in v0.1.9 

type A2AServerConfig struct {
	// Hostname is the network interface the A2A HTTP server binds to.
	// Defaults to "localhost". Set to "0.0.0.0" to accept external connections.
	Hostname string
	// Port is the TCP port the A2A HTTP server listens on. Defaults to 9999.
	Port int
	// BearerTokens is an optional list of accepted static Bearer tokens.
	// When non-empty every inbound JSON-RPC request must carry an
	// "Authorization: Bearer <token>" header whose value matches at least one
	// entry; requests without a valid token are rejected with ErrUnauthenticated.
	// The well-known agent-card endpoint is always public (no auth required).
	// Tokens are compared with constant-time equality to prevent timing attacks.
	// Leave empty to run with no authentication (development / trusted networks only).
	BearerTokens []string
	// AgentCard, when non-nil, supplies optional overrides using [interfaces.A2AAgentCard]
	// (the same shape as [interfaces.A2AClient.ResolveCard]). Non-empty fields replace defaults;
	// omitted fields use agent name/description/version, tool-derived skills, and listen URL.
	// See [Agent.buildSDKAgentCard].
	AgentCard *interfaces.A2AAgentCard
}

A2AServerConfig holds the listen address and optional authentication for the built-in A2A HTTP server.

Use WithA2ADefaultServer to accept the defaults (localhost:9999) or WithA2AServer to supply your own values. Zero-value fields are replaced with their defaults when the option is applied.

type A2AServers added in v0.1.9 

type A2AServers map[string]A2AConfig

A2AServers maps a stable server key (e.g. "planner", "coder") to per-server A2A settings. Registered tool names use prefix a2a_<serverKey>_<skillID> (see A2ATool). nil or empty map means no A2A servers from configuration.

type A2ATool added in v0.1.9 

type A2ATool struct {
	// ServerName is the stable key identifying the A2A server (used in tool name / display name).
	ServerName string
	// Spec carries the skill ID (Spec.Name), human-readable description, and optional parameter schema.
	Spec interfaces.ToolSpec
	// SkillSpec is the original A2A skill spec from the remote agent card.
	// It preserves protocol-level fields (Tags, InputModes, OutputModes, Examples) that are not
	// captured by [interfaces.ToolSpec], and is used when re-advertising delegated skills in the
	// server's own agent card via [Agent.deriveSDKSkills].
	SkillSpec interfaces.A2ASkillSpec
	// Client is the A2A client used to invoke the remote agent.
	Client interfaces.A2AClient
}

A2ATool implements interfaces.Tool for one A2A skill on a remote agent server. Execute packages the LLM-supplied args as a JSON text message, calls interfaces.A2AClient.SendMessage, then extracts the reply text from the returned message (or serialises a task to JSON if the server returns a task handle instead of a synchronous message).

func NewA2ATool added in v0.1.9 

func NewA2ATool(serverName string, spec interfaces.ToolSpec, skillSpec interfaces.A2ASkillSpec, client interfaces.A2AClient) *A2ATool

NewA2ATool builds an A2ATool from a server key, skill spec, and client. The full interfaces.A2ASkillSpec is stored on SkillSpec to preserve protocol-level fields (Tags, InputModes, OutputModes, Examples) for server-side card building. When spec.Parameters is nil, A2ATool.Parameters returns a default {"type":"object"} schema.

func (*A2ATool) Description added in v0.1.9 

func (t *A2ATool) Description() string

Description implements interfaces.Tool.

func (*A2ATool) DisplayName added in v0.1.9 

func (t *A2ATool) DisplayName() string

DisplayName implements interfaces.Tool.

func (*A2ATool) Execute added in v0.1.9 

func (t *A2ATool) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements interfaces.Tool.

The LLM-supplied args map is marshalled to a JSON string and sent as a single "text" part in a user message. The remote agent's reply is handled as follows:

  • Message result: all text parts are collected and joined with newlines.
  • Task result (async): the task is JSON-encoded and returned as a string. Callers that need full task lifecycle management should use interfaces.A2AClient directly.
  • Empty result (neither message nor task): an empty string is returned without error.

func (*A2ATool) Name added in v0.1.9 

func (t *A2ATool) Name() string

Name implements interfaces.Tool.

func (*A2ATool) Parameters added in v0.1.9 

func (t *A2ATool) Parameters() interfaces.JSONSchema

Parameters implements interfaces.Tool. Returns a default object schema when spec parameters are nil.

func (*A2ATool) ToolKind added in v0.2.2 

func (t *A2ATool) ToolKind() types.ToolKind

ToolKind implements types.ToolKindProvider.

type AfterLLMHook added in v0.2.3 

type AfterLLMHook = hooks.AfterLLMHook

type AfterLLMHookInput added in v0.2.3 

type AfterLLMHookInput = hooks.AfterLLMHookInput

type AfterLLMHookOutput added in v0.2.3 

type AfterLLMHookOutput = hooks.AfterLLMHookOutput

type AfterMemoryLoadHook added in v0.2.3 

type AfterMemoryLoadHook = hooks.AfterMemoryLoadHook

type AfterMemoryLoadHookInput added in v0.2.3 

type AfterMemoryLoadHookInput = hooks.AfterMemoryLoadHookInput

type AfterMemoryLoadHookOutput added in v0.2.3 

type AfterMemoryLoadHookOutput = hooks.AfterMemoryLoadHookOutput

type AfterMemoryStoreHook added in v0.2.3 

type AfterMemoryStoreHook = hooks.AfterMemoryStoreHook

type AfterMemoryStoreHookInput added in v0.2.3 

type AfterMemoryStoreHookInput = hooks.AfterMemoryStoreHookInput

type AfterMemoryStoreHookOutput added in v0.2.3 

type AfterMemoryStoreHookOutput = hooks.AfterMemoryStoreHookOutput

type AfterRetrieveHook added in v0.2.3 

type AfterRetrieveHook = hooks.AfterRetrieveHook

type AfterRetrieveHookInput added in v0.2.3 

type AfterRetrieveHookInput = hooks.AfterRetrieveHookInput

type AfterRetrieveHookOutput added in v0.2.3 

type AfterRetrieveHookOutput = hooks.AfterRetrieveHookOutput

type AfterToolHook added in v0.2.3 

type AfterToolHook = hooks.AfterToolHook

type AfterToolHookInput added in v0.2.3 

type AfterToolHookInput = hooks.AfterToolHookInput

type AfterToolHookOutput added in v0.2.3 

type AfterToolHookOutput = hooks.AfterToolHookOutput

type Agent 

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

Agent runs LLM-backed agent execution through the configured execution runtime. It holds configuration, that runtime, and optionally an embedded AgentWorker for in-process polling. Sub-agents share the parent runtime's event bus for delegation and approvals in the same process.

func NewAgent 

func NewAgent(opts ...Option) (*Agent, error)

NewAgent creates an Agent with the given options. Background runtime workers (when used) start lazily when Agent.Stream runs or when approvals need them.

func (*Agent) A2ARegistry added in v0.2.2 

func (a *Agent) A2ARegistry() A2ARegistry

A2ARegistry returns the agent's A2A client registry.

func (*Agent) Close 

func (a *Agent) Close()

Close stops an embedded local worker if present, then closes the runtime (releasing remote resources and closing backend connections owned by the runtime, depending on the implementation). Active Temporal workflows are NOT terminated — they continue running on the Temporal server and any available worker can pick them up after a restart. Only the local worker poll loop and owned client connections are torn down.

func (*Agent) GetAgentRun added in v0.3.0 

func (a *Agent) GetAgentRun(ctx context.Context, runID string) (AgentRun, error)

GetAgentRun returns an AgentRun for runID so callers can await or control a run started in this or a previous process (AgentRun.Get, AgentRun.Done, AgentRun.Status, AgentRun.Cancel).

Same-process: if Agent.Run or a prior GetAgentRun already registered a live handle for runID, that same AgentRun is returned. If that handle's AgentRun.Done is already closed, the registry entry is cleared and ErrRunAlreadyCompleted is returned.

Otherwise reconnects with runtime.Runtime.GetRunHandle and wraps the runtime handle as an AgentRun (registered in the in-process run registry). Cancelling ctx only affects the reconnect lookup (status/describe); it does not cancel the agent run — use AgentRun.Cancel.

Returns ErrRunAlreadyCompleted when the runtime reports the run is already terminal — no handle is returned; load the outcome from conversation/memory instead of calling Get. Returns ErrRunNotFound when runID is unknown or the runtime cannot reconnect (e.g. LocalRuntime after a crash — no durable run tracking). Other GetRunHandle errors are returned as-is.

func (*Agent) GetAgentStream added in v0.3.0 

func (a *Agent) GetAgentStream(ctx context.Context, runID string) (AgentStream, error)

GetAgentStream returns an AgentStream for runID so callers can subscribe or control a stream started in this or a previous process (AgentStream.Events, AgentStream.Status, AgentStream.Cancel). Use WithOffset on Events to resume after a crash.

Same-process: if Agent.Stream or a prior GetAgentStream already registered a live handle for runID, that same AgentStream is returned. If AgentStream.Status reports terminal, the registry entry is cleared and ErrRunAlreadyCompleted is returned.

Otherwise reconnects with runtime.Runtime.GetStreamHandle and wraps the runtime handle as an AgentStream (registered in the in-process stream registry). Cancelling ctx only affects the reconnect lookup (status/describe); it does not cancel the agent run — use AgentStream.Cancel. Cancelling AgentStream.Events's ctx stops that subscriber only.

Returns ErrRunAlreadyCompleted when the runtime reports the stream run is already terminal — no handle is returned; load the outcome from conversation/memory instead of calling Events. Returns ErrStreamNotFound when runID is unknown or the runtime cannot reconnect (e.g. LocalRuntime after a crash — no durable stream tracking). Other GetStreamHandle errors are returned as-is.

func (*Agent) MCPRegistry added in v0.2.2 

func (a *Agent) MCPRegistry() MCPRegistry

MCPRegistry returns the agent's MCP client registry.

func (*Agent) OnApproval deprecated 

func (a *Agent) OnApproval(ctx context.Context, approvalToken string, status ApprovalStatus) error

OnApproval completes a pending tool or delegation approval when using Agent.Stream. Pass the approval token from the CUSTOM event Value and ApprovalStatusApproved or ApprovalStatusRejected.

Deprecated: Use AgentStream.Approve on the handle from Agent.Stream or Agent.GetAgentStream instead. This method will be removed in v0.4.0.

func (*Agent) Run 

func (a *Agent) Run(ctx context.Context, input string, opts *AgentRunOptions) (AgentRun, error)

Run starts an agent run and returns an AgentRun immediately after pre-flight validation. It calls runtime.Runtime.Run, wraps the runtime handle with [newAgentRun], and returns. Use AgentRun.Get or AgentRun.Done to wait for the result.

Use WithApprovalHandler when any registered tool requires approval. When using WithConversation, pass the conversation ID in opts.

func (*Agent) RunA2A added in v0.1.9 

func (a *Agent) RunA2A(ctx context.Context) error

RunA2A starts the built-in A2A HTTP server for this agent.

The server mounts two handlers on a single http.Server:

  • a2asrv.WellKnownAgentCardPath — serves the agent card (GET), built once from the agent's name, description, registered tools, and listen address.
  • "/" — JSON-RPC v2 only (a2asrv.NewJSONRPCHandler): methods such as SendMessage, SendStreamingMessage, GetTask, … Use PascalCase names as defined by a2asrv / A2A v2.

The server blocks until ctx is cancelled, then performs a graceful shutdown. Returns a non-nil error if the server was not configured (use WithA2ADefaultServer or WithA2AServer) or if http.Server.ListenAndServe fails with an unexpected error.

func (*Agent) Stream added in v0.0.10 

func (a *Agent) Stream(ctx context.Context, input string, opts *AgentStreamOptions) (AgentStream, error)

Stream starts the agent run and returns an AgentStream immediately after pre-flight validation. It calls runtime.Runtime.Stream, wraps the runtime handle with [newAgentStream], and returns. Call AgentStream.Events to subscribe (optionally WithOffset after reconnect). Persist AgentStream.ID before Events when crash-durability matters.

Cancelling ctx cancels the agent run (same idea as Agent.Run). Cancelling the context passed to AgentStream.Events only stops that subscriber — use a separate Events ctx for reconnect / "subscriber gone". You can also stop the run with AgentStream.Cancel or WithTimeout.

By default, LLM token streaming is enabled (TEXT_MESSAGE_CONTENT events are emitted). Set opts.DisableTokenStreaming = true to receive a single complete message instead.

For approvals (tool or delegation), receive AgentEventTypeCustom events from the Events channel and call AgentStream.Approve with the token extracted from the payload. When using WithConversation, pass the conversation ID in opts.

func (*Agent) SubAgentRegistry added in v0.2.2 

func (a *Agent) SubAgentRegistry() SubAgentRegistry

SubAgentRegistry returns the agent's sub-agent registry.

func (*Agent) ToolRegistry added in v0.2.2 

func (a *Agent) ToolRegistry() ToolRegistry

ToolRegistry returns the agent's tool registry.

type AgentCustomEvent added in v0.1.6 

type AgentCustomEvent = events.AgentCustomEvent

AgentCustomEvent is published to subscribers when the agent sends a custom event.

type AgentCustomEventApprovalValue added in v0.1.6 

type AgentCustomEventApprovalValue = events.AgentCustomEventApprovalValue

AgentCustomEventApprovalValue is the value of the custom event for tool approval.

func ParseCustomEventApproval added in v0.1.6 

func ParseCustomEventApproval(ev *AgentCustomEvent) (AgentCustomEventApprovalValue, error)

ParseCustomEventApproval returns the typed value for CUSTOM events with name AgentCustomEventNameToolApproval. Use this when handling stream events: JSON decode leaves Value as map[string]any.

type AgentCustomEventDelegationValue added in v0.1.6 

type AgentCustomEventDelegationValue = events.AgentCustomEventDelegationValue

AgentCustomEventDelegationValue is the value of the custom event for sub-agent delegation.

func ParseCustomEventDelegation added in v0.1.6 

func ParseCustomEventDelegation(ev *AgentCustomEvent) (AgentCustomEventDelegationValue, error)

ParseCustomEventDelegation returns the typed value for CUSTOM events with name AgentCustomEventNameSubAgentDelegation.

type AgentCustomEventName added in v0.1.6 

type AgentCustomEventName = events.AgentCustomEventName

AgentCustomEventName classifies what the user is approving when using streaming or approval events. 

const (
	// AgentCustomEventNameToolApproval is a normal tool execution (default when Kind is empty for older payloads).
	AgentCustomEventNameToolApproval AgentCustomEventName = events.AgentCustomEventNameToolApproval
	// AgentCustomEventNameSubAgentDelegation is approval to run a registered sub-agent (delegate).
	AgentCustomEventNameSubAgentDelegation AgentCustomEventName = events.AgentCustomEventNameSubAgentDelegation
)

type AgentEvent 

type AgentEvent = events.AgentEvent

AgentEvent is the interface for all agent events.

type AgentEventType 

type AgentEventType = events.AgentEventType

AgentEventType identifies a streamed event kind from the execution runtime. 

const (
	AgentEventTypeRunStarted   AgentEventType = events.AgentEventTypeRunStarted
	AgentEventTypeRunFinished  AgentEventType = events.AgentEventTypeRunFinished
	AgentEventTypeRunError     AgentEventType = events.AgentEventTypeRunError
	AgentEventTypeStepStarted  AgentEventType = events.AgentEventTypeStepStarted
	AgentEventTypeStepFinished AgentEventType = events.AgentEventTypeStepFinished

	AgentEventTypeTextMessageStart   AgentEventType = events.AgentEventTypeTextMessageStart
	AgentEventTypeTextMessageContent AgentEventType = events.AgentEventTypeTextMessageContent
	AgentEventTypeTextMessageEnd     AgentEventType = events.AgentEventTypeTextMessageEnd

	AgentEventTypeToolCallStart  AgentEventType = events.AgentEventTypeToolCallStart
	AgentEventTypeToolCallArgs   AgentEventType = events.AgentEventTypeToolCallArgs
	AgentEventTypeToolCallEnd    AgentEventType = events.AgentEventTypeToolCallEnd
	AgentEventTypeToolCallResult AgentEventType = events.AgentEventTypeToolCallResult

	AgentEventTypeReasoningStart          AgentEventType = events.AgentEventTypeReasoningStart
	AgentEventTypeReasoningMessageStart   AgentEventType = events.AgentEventTypeReasoningMessageStart
	AgentEventTypeReasoningMessageContent AgentEventType = events.AgentEventTypeReasoningMessageContent
	AgentEventTypeReasoningMessageEnd     AgentEventType = events.AgentEventTypeReasoningMessageEnd
	AgentEventTypeReasoningEnd            AgentEventType = events.AgentEventTypeReasoningEnd

	AgentEventTypeRaw    AgentEventType = events.AgentEventTypeRaw
	AgentEventTypeCustom AgentEventType = events.AgentEventTypeCustom
)

type AgentHooks added in v0.2.3 

type AgentHooks = hooks.AgentHooks

Core

type AgentMode added in v0.1.3 

type AgentMode = types.AgentMode

AgentMode selects interactive (default) or autonomous agent behavior. Aliases types.AgentMode.

type AgentRawEvent added in v0.1.6 

type AgentRawEvent = events.AgentRawEvent

AgentRawEvent is published to subscribers when the agent sends a raw event.

type AgentReasoningEndEvent added in v0.1.6 

type AgentReasoningEndEvent = events.AgentReasoningEndEvent

AgentReasoningEndEvent is published to subscribers when the agent ends reasoning.

type AgentReasoningMessageContentEvent added in v0.1.6 

type AgentReasoningMessageContentEvent = events.AgentReasoningMessageContentEvent

AgentReasoningMessageContentEvent is published to subscribers when the agent sends a reasoning message content.

type AgentReasoningMessageEndEvent added in v0.1.6 

type AgentReasoningMessageEndEvent = events.AgentReasoningMessageEndEvent

AgentReasoningMessageEndEvent is published to subscribers when the agent ends a reasoning message.

type AgentReasoningMessageStartEvent added in v0.1.6 

type AgentReasoningMessageStartEvent = events.AgentReasoningMessageStartEvent

AgentReasoningMessageStartEvent is published to subscribers when the agent starts a reasoning message.

type AgentReasoningStartEvent added in v0.1.6 

type AgentReasoningStartEvent = events.AgentReasoningStartEvent

AgentReasoningStartEvent is published to subscribers when the agent starts reasoning.

type AgentRun added in v0.3.0 

type AgentRun interface {
	// ID returns the unique run identifier, stable across process restarts.
	ID() string

	// Status returns the current lifecycle status of the run.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Status(ctx context.Context) (RunStatus, error)

	// Cancel requests cancellation of the run.
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Cancel(ctx context.Context) error

	// Get blocks until the run finishes and returns the result pointer.
	// Cancelling ctx unblocks Get but does NOT cancel the agent run itself —
	// use [AgentRun.Cancel] for that.
	Get(ctx context.Context) (*AgentRunResult, error)

	// Done returns a channel that is closed when the run finishes (success or failure).
	// Safe to call multiple times; always returns the same channel.
	Done() <-chan struct{}
}

AgentRun is the handle returned by Agent.Run and Agent.GetAgentRun.

Blocking pattern — call Get directly; it blocks until the run finishes: 

agentRun, err := agent.Run(ctx, input, opts)
result, err := agentRun.Get(ctx)

Non-blocking pattern — wait on Done, then call Get: 

agentRun, err := agent.Run(ctx, input, opts)
<-agentRun.Done()
result, err := agentRun.Get(ctx)

Reconnect pattern — resume a still-running run from a previous process: 

agentRun, err := agent.GetAgentRun(ctx, savedRunID)
// err is ErrRunAlreadyCompleted if the run already finished — use conversation/memory instead.
result, err := agentRun.Get(ctx)

type AgentRunErrorEvent added in v0.1.6 

type AgentRunErrorEvent = events.AgentRunErrorEvent

AgentRunErrorEvent is published to subscribers when the agent encounters an error.

type AgentRunFinishedEvent added in v0.1.6 

type AgentRunFinishedEvent = events.AgentRunFinishedEvent

AgentRunFinishedEvent is published to subscribers when the agent finishes a run.

type AgentRunOptions added in v0.2.0 

type AgentRunOptions = types.AgentRunOptions

AgentRunOptions holds per-call options for Agent.Run. A nil pointer is valid and means "no options" (no conversation, default behaviour).

type AgentRunResult added in v0.1.6 

type AgentRunResult = types.AgentRunResult

AgentRunResult is the structured result returned by AgentRun.Get after a run completes.

type AgentRunStartedEvent added in v0.1.6 

type AgentRunStartedEvent = events.AgentRunStartedEvent

AgentRunStartedEvent is published to subscribers when the agent starts a run.

type AgentStepFinishedEvent added in v0.1.6 

type AgentStepFinishedEvent = events.AgentStepFinishedEvent

AgentStepFinishedEvent is published when that step ends. For sub-agent runs, emitted after the child workflow returns, success or failure (the tool result may still contain an error string).

type AgentStepStartedEvent added in v0.1.6 

type AgentStepStartedEvent = events.AgentStepStartedEvent

AgentStepStartedEvent is published when a step begins. It is emitted when a sub-agent child workflow is about to run; StepName is the sub-agent route name (WithSubAgents / SubAgentRoute.Name).

type AgentStream added in v0.3.0 

type AgentStream interface {
	// ID returns the unique run identifier for this stream, stable across process restarts.
	ID() string

	// Status returns the current lifecycle status of the underlying run.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Status(ctx context.Context) (RunStatus, error)

	// Cancel requests cancellation of the underlying agent run.
	// Returns [ErrRunAlreadyCompleted] when the run has already finished.
	// Returns [ErrRunNotFound] when the underlying run is no longer known.
	Cancel(ctx context.Context) error

	// Get blocks until the stream run finishes and returns the result pointer.
	// Cancelling ctx unblocks Get but does NOT cancel the agent run itself —
	// use [AgentStream.Cancel] for that.
	Get(ctx context.Context) (*AgentRunResult, error)

	// Done returns a channel that is closed when the stream run finishes (success or failure).
	// Safe to call multiple times; always returns the same channel.
	Done() <-chan struct{}

	// Approve completes a tool or delegation approval using the token from the CUSTOM approval
	// event and the chosen status ([ApprovalStatusApproved] or [ApprovalStatusRejected]).
	// Returns [ErrApprovalAlreadyResolved] when the token was already completed.
	Approve(ctx context.Context, approvalToken string, status ApprovalStatus) error

	// Events subscribes to the agent event stream and returns a receive-only channel.
	// The channel is closed after the terminal lifecycle event (RUN_FINISHED / RUN_ERROR),
	// or when ctx is cancelled (Temporal: stops this subscriber only; the agent run continues).
	// Cancelling [Agent.Stream]'s ctx cancels the run — use a separate Events ctx for reconnect.
	//
	// opts may include [WithOffset] to resume from a saved position after a crash.
	// Omitting WithOffset (or passing offset 0) starts from the beginning of the run.
	//
	// Returns [ErrRunAlreadyCompleted] if the run has already finished.
	// Returns [ErrStreamOffsetNotSupported] when the runtime does not support the requested offset.
	Events(ctx context.Context, opts ...AgentStreamOption) (<-chan AgentEvent, error)
}

AgentStream is the handle returned by Agent.Stream and Agent.GetAgentStream.

First-time subscriber pattern: 

agentStream, err := agent.Stream(ctx, input, opts) // cancel ctx → cancel run
ch, err := agentStream.Events(eventsCtx)           // cancel eventsCtx → subscriber only
for event := range ch { ... }

Wait for final result (same as AgentRun, without consuming Events): 

agentStream, err := agent.Stream(ctx, input, opts)
result, err := agentStream.Get(ctx)

Non-blocking wait, then Get: 

<-agentStream.Done()
result, err := agentStream.Get(ctx)

Reconnect pattern (resume after crash while the run is still live): 

agentStream, err := agent.GetAgentStream(ctx, savedRunID)
// err is ErrRunAlreadyCompleted if the run already finished — use conversation/memory instead.
ch, err := agentStream.Events(ctx, agent.WithOffset(savedOffset))
for event := range ch { ... }

type AgentStreamOption added in v0.3.0 

type AgentStreamOption func(*agentStreamConfig)

AgentStreamOption is a functional option applied to an AgentStream.Events call. Use WithOffset to resume a stream after a crash or reconnect.

func WithOffset added in v0.3.0 

func WithOffset(offset int64) AgentStreamOption

WithOffset instructs AgentStream.Events to resume the event stream starting at the given durable log offset. Use the last successfully processed offset saved before a crash. Offset 0 means "from the beginning" (first-time subscriber). Non-zero offsets are only supported by Temporal-backed agents; LocalRuntime returns ErrStreamOffsetNotSupported for offset > 0.

type AgentStreamOptions added in v0.3.0 

type AgentStreamOptions = types.AgentStreamOptions

AgentStreamOptions holds per-call options for Agent.Stream. A nil pointer is valid and means "no options" (LLM token streaming on, no conversation).

type AgentTelemetry added in v0.2.2 

type AgentTelemetry = types.AgentTelemetry

AgentTelemetry is the unified container for operational insights across a single agent run, covering run lifecycle, tool calls, and storage operations. Token usage is reported separately on AgentRunResult.LLMUsage.

type AgentTextMessageContentEvent added in v0.1.6 

type AgentTextMessageContentEvent = events.AgentTextMessageContentEvent

AgentTextMessageContentEvent is published to subscribers when the agent sends a text message content.

type AgentTextMessageEndEvent added in v0.1.6 

type AgentTextMessageEndEvent = events.AgentTextMessageEndEvent

AgentTextMessageEndEvent is published to subscribers when the agent ends a text message.

type AgentTextMessageStartEvent added in v0.1.6 

type AgentTextMessageStartEvent = events.AgentTextMessageStartEvent

AgentTextMessageStartEvent is published to subscribers when the agent starts a text message.

type AgentTool 

type AgentTool interface {
	interfaces.Tool
	// SubAgent returns the sub-agent this tool delegates to.
	SubAgent() *Agent
}

AgentTool marks a tool that represents sub-agent delegation (child AgentWorkflow), not normal Tool.Execute.

The runtime routes tool calls to sub-agents using sub-agent routes keyed by tool name. AgentTool is also used when building approval metadata for delegation tools.

type AgentToolCallArgsEvent added in v0.1.6 

type AgentToolCallArgsEvent = events.AgentToolCallArgsEvent

AgentToolCallArgsEvent is published to subscribers when the agent sends a tool call args.

type AgentToolCallEndEvent added in v0.1.6 

type AgentToolCallEndEvent = events.AgentToolCallEndEvent

AgentToolCallEndEvent is published to subscribers when the agent ends a tool call.

type AgentToolCallResultEvent added in v0.1.6 

type AgentToolCallResultEvent = events.AgentToolCallResultEvent

AgentToolCallResultEvent is published to subscribers when the agent sends a tool call result.

type AgentToolCallStartEvent added in v0.1.6 

type AgentToolCallStartEvent = events.AgentToolCallStartEvent

AgentToolCallStartEvent is published to subscribers when the agent starts a tool call.

type AgentToolExecutionMode added in v0.1.7 

type AgentToolExecutionMode = types.AgentToolExecutionMode

AgentToolExecutionMode selects parallel (default) or sequential tool execution. Aliases types.AgentToolExecutionMode.

type AgentWorker 

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

AgentWorker runs the execution runtime's worker for an agent (polls the task queue and executes runs).

func NewAgentWorker 

func NewAgentWorker(opts ...Option) (*AgentWorker, error)

NewAgentWorker creates an AgentWorker that polls and executes runs for the configured backend. Same options as NewAgent. Use when the agent is created with DisableLocalWorker. AgentWorker requires a Temporal backend (WithTemporalConfig or WithTemporalClient).

func (*AgentWorker) Start 

func (aw *AgentWorker) Start(ctx context.Context) error

Start starts the worker (blocks until Stop is called). Returns an error if [Runtime] does not implement runtime.WorkerRuntime (in-process polling not supported).

func (*AgentWorker) Stop added in v0.0.10 

func (aw *AgentWorker) Stop()

Stop stops the worker if [Runtime] implements runtime.WorkerRuntime.

type AllowlistToolApprovalConfig added in v0.1.2 

type AllowlistToolApprovalConfig struct {
	// ToolNames are plain registry / [WithTools] names (e.g. "echo", "calculator").
	ToolNames []string
	// SubAgentNames are trimmed sub-agent display names ([WithName]) for agents registered with [WithSubAgents].
	// Each entry is expanded with the same rules as sub-agent delegation tool names (see [NewSubAgentTool]). Invalid names make
	// [AllowlistToolApprovalPolicy] return an error.
	SubAgentNames []string
	// MCPTools maps MCP server key (same as [MCPTool.ServerName] / MCP config) to server tool ids
	// ([interfaces.ToolSpec.Name] as returned by the server). Each pair expands to mcp_<server>_<toolId>.
	MCPTools map[string][]string
}

AllowlistToolApprovalConfig selects tools and capabilities that may run without user approval. Entries are expanded to registered interfaces.Tool names (what interfaces.Tool.Name returns); [allowlistToolApprovalPolicy.RequiresApproval] compares against those names.

type ApprovalHandler 

type ApprovalHandler = types.ApprovalHandler

ApprovalHandler is called for pending tool approval during Agent.Run. Register once at NewAgent via WithApprovalHandler (construction-time, not per-call). req.Respond is always set: call req.Respond(ApprovalStatusApproved) or Rejected when ready. The handler may return immediately after starting async work. Multiple invocations may run concurrently when tools are invoked in parallel. For streaming approvals use AgentStream.Approve.

type ApprovalRequest 

type ApprovalRequest = types.ApprovalRequest

ApprovalRequest describes a pending tool approval for Agent.Run. Name + Value mirror CUSTOM stream events; use ParseToolApproval / ParseDelegationApproval. Respond is always set; call it once with ApprovalStatusApproved or ApprovalStatusRejected. For streaming approvals, use AgentStream.Approve with the approval token from the CUSTOM event Value.

type ApprovalRequestName added in v0.1.6 

type ApprovalRequestName = types.ApprovalRequestName

ApprovalRequestName classifies approval callbacks (aligned with CUSTOM event roles).

type ApprovalSender 

type ApprovalSender = types.ApprovalSender

ApprovalSender sends an approval result for the current run. Call once per request. Safe for concurrent use— multiple approvals may be pending when tools run in parallel.

type ApprovalStatus 

type ApprovalStatus = types.ApprovalStatus
const (
	ApprovalStatusNone        ApprovalStatus = types.ApprovalStatusNone
	ApprovalStatusPending     ApprovalStatus = types.ApprovalStatusPending
	ApprovalStatusApproved    ApprovalStatus = types.ApprovalStatusApproved
	ApprovalStatusRejected    ApprovalStatus = types.ApprovalStatusRejected
	ApprovalStatusUnavailable ApprovalStatus = types.ApprovalStatusUnavailable
	ApprovalStatusTimedOut    ApprovalStatus = types.ApprovalStatusTimedOut
)

type BaseEvent added in v0.1.6 

type BaseEvent = events.BaseEvent

BaseEvent is published to subscribers when the agent produces output or errors during a run. AgentName identifies which agent in a delegation tree emitted the event (main or sub-agent). Agent.Stream uses it so AgentEventTypeRunFinished from a sub-agent does not close the root stream. For AgentEventTypeCustom, the requesting agent is also on AgentName (not duplicated on Approval).

type BeforeLLMHook added in v0.2.3 

type BeforeLLMHook = hooks.BeforeLLMHook

type BeforeLLMHookInput added in v0.2.3 

type BeforeLLMHookInput = hooks.BeforeLLMHookInput

LLM

type BeforeLLMHookOutput added in v0.2.3 

type BeforeLLMHookOutput = hooks.BeforeLLMHookOutput

type BeforeMemoryLoadHook added in v0.2.3 

type BeforeMemoryLoadHook = hooks.BeforeMemoryLoadHook

type BeforeMemoryLoadHookInput added in v0.2.3 

type BeforeMemoryLoadHookInput = hooks.BeforeMemoryLoadHookInput

Memory

type BeforeMemoryLoadHookOutput added in v0.2.3 

type BeforeMemoryLoadHookOutput = hooks.BeforeMemoryLoadHookOutput

type BeforeMemoryStoreHook added in v0.2.3 

type BeforeMemoryStoreHook = hooks.BeforeMemoryStoreHook

type BeforeMemoryStoreHookInput added in v0.2.3 

type BeforeMemoryStoreHookInput = hooks.BeforeMemoryStoreHookInput

type BeforeMemoryStoreHookOutput added in v0.2.3 

type BeforeMemoryStoreHookOutput = hooks.BeforeMemoryStoreHookOutput

type BeforeRetrieveHook added in v0.2.3 

type BeforeRetrieveHook = hooks.BeforeRetrieveHook

type BeforeRetrieveHookInput added in v0.2.3 

type BeforeRetrieveHookInput = hooks.BeforeRetrieveHookInput

Retriever

type BeforeRetrieveHookOutput added in v0.2.3 

type BeforeRetrieveHookOutput = hooks.BeforeRetrieveHookOutput

type BeforeToolHook added in v0.2.3 

type BeforeToolHook = hooks.BeforeToolHook

type BeforeToolHookInput added in v0.2.3 

type BeforeToolHookInput = hooks.BeforeToolHookInput

Tools

type BeforeToolHookOutput added in v0.2.3 

type BeforeToolHookOutput = hooks.BeforeToolHookOutput

type ConversationOptions added in v0.2.0 

type ConversationOptions = types.ConversationOptions

ConversationOptions identifies a conversation session for one call. ID must be stable across all turns of the same session (e.g. a user or chat ID).

type ExecutionConfig added in v0.2.5 

type ExecutionConfig = runtime.ExecutionConfig

ExecutionConfig controls timeout and max attempts for one agent loop operation. Aliases runtime.ExecutionConfig.

type HookGroup added in v0.2.3 

type HookGroup = hooks.HookGroup

type LLMSampling 

type LLMSampling = types.LLMSampling

LLMSampling holds per-agent LLM sampling overrides. nil or zero values mean provider defaults. One LLM client can serve multiple agents with different sampling settings.

type LLMUsage added in v0.2.2 

type LLMUsage = types.LLMUsage

LLMUsage is the token usage for a single LLM call.

type MCPConfig added in v0.1.2 

type MCPConfig struct {
	Transport     types.MCPTransportConfig
	ToolFilter    types.MCPToolFilter
	Timeout       time.Duration
	RetryAttempts int
}

MCPConfig describes one MCP server: transport, optional tool filter, and client timeouts/retries. Set MCPConfig.Transport and MCPConfig.ToolFilter using types from github.com/agenticenv/agent-sdk-go/pkg/mcp (MCPStdio, MCPStreamableHTTP, MCPToolFilter). Zero MCPConfig.Timeout and MCPConfig.RetryAttempts are applied in mcpclient.BuildConfig when the default MCP client is created (mcpclient.NewClient).

type MCPRegistry added in v0.2.2 

type MCPRegistry interface {
	Register(name string, config MCPConfig) error
	RegisterClient(client interfaces.MCPClient) error
	Get(name string) (interfaces.MCPClient, error)
	List() []interfaces.MCPClient
	Unregister(name string) error
}

MCPRegistry stores MCP clients for an agent.

func NewMCPRegistry added in v0.2.2 

func NewMCPRegistry(l logger.Logger) MCPRegistry

NewMCPRegistry returns an empty MCP client registry for use with WithMCPRegistry. logger is used when [Register] builds a client from MCPConfig.

type MCPServers added in v0.1.2 

type MCPServers map[string]MCPConfig

MCPServers maps a stable server key (e.g. "github", "slack") to per-server MCP settings. Registered tool names use prefix mcp_<serverKey>_<toolName> (see MCPTool). nil or empty map means no MCP servers from configuration.

type MCPTool added in v0.1.2 

type MCPTool struct {
	ServerName string
	Spec       interfaces.ToolSpec
	Client     interfaces.MCPClient
}

MCPTool implements interfaces.Tool for one MCP tool on a server. Execute delegates to MCPClient.CallTool using Spec.Name as the server tool name.

func NewMCPTool added in v0.1.2 

func NewMCPTool(serverName string, spec interfaces.ToolSpec, client interfaces.MCPClient) *MCPTool

NewMCPTool builds an MCPTool. When spec.Parameters is nil, MCPTool.Parameters returns a default object schema.

func (*MCPTool) Description added in v0.1.2 

func (t *MCPTool) Description() string

Description implements interfaces.Tool.

func (*MCPTool) DisplayName added in v0.1.4 

func (t *MCPTool) DisplayName() string

DisplayName implements interfaces.Tool.

func (*MCPTool) Execute added in v0.1.2 

func (t *MCPTool) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements interfaces.Tool: marshal args, CallTool, return decoded JSON or raw string.

func (*MCPTool) Name added in v0.1.2 

func (t *MCPTool) Name() string

Name implements interfaces.Tool.

func (*MCPTool) Parameters added in v0.1.2 

func (t *MCPTool) Parameters() interfaces.JSONSchema

Parameters implements interfaces.Tool.

func (*MCPTool) ToolKind added in v0.2.2 

func (t *MCPTool) ToolKind() types.ToolKind

ToolKind implements types.ToolKindProvider.

type MemoryStoreFunc added in v0.2.2 

type MemoryStoreFunc func(ctx context.Context, records []interfaces.MemoryRecord) error

MemoryStoreFunc persists extracted memory records for the current run scope.

type MemoryTool added in v0.2.2 

type MemoryTool struct {
	Store MemoryStoreFunc
}

MemoryTool implements interfaces.Tool for on-demand long-term memory store (memory.StoreModeOnDemand).

func (*MemoryTool) Description added in v0.2.2 

func (t *MemoryTool) Description() string

Description implements interfaces.Tool.

func (*MemoryTool) DisplayName added in v0.2.2 

func (t *MemoryTool) DisplayName() string

DisplayName implements interfaces.Tool.

func (*MemoryTool) Execute added in v0.2.2 

func (t *MemoryTool) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements interfaces.Tool.

func (*MemoryTool) Name added in v0.2.2 

func (t *MemoryTool) Name() string

Name implements interfaces.Tool.

func (*MemoryTool) Parameters added in v0.2.2 

func (t *MemoryTool) Parameters() interfaces.JSONSchema

Parameters implements interfaces.Tool.

func (*MemoryTool) ToolKind added in v0.2.2 

func (t *MemoryTool) ToolKind() types.ToolKind

ToolKind implements types.ToolKindProvider.

type OTLPProtocol added in v0.1.10 

type OTLPProtocol = types.OTLPProtocol

OTLPProtocol is an alias for types.OTLPProtocol re-exported from pkg/agent so callers do not need to import internal/types when constructing an ObservabilityConfig. 

const (
	// OTLPProtocolGRPC selects gRPC transport for OTLP export (default).
	OTLPProtocolGRPC OTLPProtocol = types.OTLPProtocolGRPC
	// OTLPProtocolHTTP selects HTTP/protobuf transport for OTLP export.
	OTLPProtocolHTTP OTLPProtocol = types.OTLPProtocolHTTP
)

type ObservabilityConfig added in v0.1.10 

type ObservabilityConfig struct {
	// Endpoint is the OTLP collector URL, e.g. "collector:4317" (gRPC) or
	// "http://collector:4318" (HTTP). Required when ObservabilityConfig is non-nil.
	Endpoint string

	// Protocol selects the OTLP wire transport. Defaults to [OTLPProtocolGRPC].
	// Must match on both the agent caller process and the worker process.
	Protocol OTLPProtocol

	// Insecure disables TLS for the OTLP connection. Use only in development or
	// on networks where the collector sits on the same trusted host.
	Insecure bool

	// DisableTraces when true skips constructing a [interfaces.Tracer] from this config during build.
	DisableTraces bool
	// DisableMetrics when true skips constructing [interfaces.Metrics] from this config during build.
	DisableMetrics bool
	// DisableLogs when true skips constructing [*observability.Logs] from this config and skips
	// OTLP log wiring tied to this config. A prior [WithLogs] injection is preserved; if it is
	// [*observability.Logs] and the default SDK logger is used, the logger is still bridged to that client.
	DisableLogs bool
}

ObservabilityConfig selects OTLP export for traces, metrics, and logs on both the client Agent and AgentWorker when merged at [buildAgentConfig]. It is included in [agentConfigFingerprint] so caller and worker processes agree on collector wiring (see [observabilityConfigFingerprint]).

Use WithObservabilityConfig together with identical values on the process that runs workflows and the process that hosts activities.

Timing fields (export timeout, batch timeout, metrics interval) are intentionally omitted here; the SDK uses [types.DefaultOTLP*] constants automatically. Use the pkg/observability package directly with observability.BuildConfig if you need per-field control.

type Option 

type Option func(*agentConfig)

Option configures an agent. See agentConfig for which options apply to Agent vs AgentWorker.

func DisableLocalWorker added in v0.0.10 

func DisableLocalWorker() Option

DisableLocalWorker marks to skip local worker creation. Agent only. Use with NewAgentWorker.

func WithA2AClients added in v0.1.9 

func WithA2AClients(clients ...interfaces.A2AClient) Option

WithA2AClients adds caller-supplied A2A clients (e.g. for custom transports or pre-built agents). Each client's interfaces.A2AClient.Name must be non-empty and unique among all A2A clients, including those created from WithA2AConfig. Applies to Agent and AgentWorker.

func WithA2AConfig added in v0.1.9 

func WithA2AConfig(servers A2AServers) Option

WithA2AConfig registers remote A2A agents by key. See WithA2ARegistry to change clients later. Applies to Agent and AgentWorker.

func WithA2ADefaultServer added in v0.1.9 

func WithA2ADefaultServer() Option

WithA2ADefaultServer enables the built-in A2A HTTP server with default settings (hostname "localhost", port 9999). Use this when you want to expose the agent as an A2A server without customising the listen address.

func WithA2AExecutionConfig added in v0.2.5 

func WithA2AExecutionConfig(cfg ExecutionConfig) Option

WithA2AExecutionConfig overrides timeout and/or max attempts for A2A calls. Zero fields keep the SDK default (Timeout: 30m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithA2ARegistry added in v0.2.2 

func WithA2ARegistry(reg A2ARegistry) Option

WithA2ARegistry sets the A2A client registry. Use Register, RegisterClient, and Unregister before Run or Stream. Applies to Agent and AgentWorker.

func WithA2AServer added in v0.1.9 

func WithA2AServer(config *A2AServerConfig) Option

WithA2AServer enables the built-in A2A HTTP server with the provided A2AServerConfig. A nil config or zero-value fields fall back to the same defaults as WithA2ADefaultServer (localhost:9999).

func WithAgentMode added in v0.1.3 

func WithAgentMode(mode AgentMode) Option

WithAgentMode sets interactive vs autonomous mode. Applies to Agent and AgentWorker. Default is AgentModeInteractive. Included in the Temporal agent fingerprint so caller and worker must agree.

func WithAgentToolExecutionMode added in v0.1.7 

func WithAgentToolExecutionMode(mode AgentToolExecutionMode) Option

WithAgentToolExecutionMode sets the tool execution mode. Applies to Agent and AgentWorker. When this option is omitted, the agent uses AgentToolExecutionModeParallel.

func WithApprovalHandler 

func WithApprovalHandler(fn types.ApprovalHandler) Option

WithApprovalHandler registers the approval callback once at NewAgent construction time for Agent.Run. Required when tools need approval. The callback receives req with req.Respond set; call req.Respond(Approved|Rejected). Agent only; Agent.Stream uses AgentStream.Approve on CUSTOM events instead.

func WithApprovalTimeout 

func WithApprovalTimeout(d time.Duration) Option

WithApprovalTimeout sets max wait per tool approval. Must be less than agent timeout. Agent only. When tools require approval, used for the approval activity; defaults to timeout-30s if unset. Capped at maxApprovalTimeout (31 days). Validation at build: approvalTimeout < timeout.

func WithConversation 

func WithConversation(cfg conversation.Config) Option

WithConversation sets conversation history for the agent. Applies to Agent and AgentWorker. Pass conversation.DefaultConfig for SDK defaults or a custom conversation.Config.

Choose implementation based on deployment:

  • Single process: use inmem.NewConversation
  • Remote workers: use redis.NewConversation (in-memory cannot be used across processes)

The application owns Clear on the conversation when required; the agent runtime does not call Clear. Agent and worker must use the same conversation config and ID when using remote workers.

func WithConversationExecutionConfig added in v0.2.5 

func WithConversationExecutionConfig(cfg ExecutionConfig) Option

WithConversationExecutionConfig overrides timeout and/or max attempts for conversation persist calls. Zero fields keep the SDK default (Timeout: 30s, MaxAttempts: 1). Applies to Agent and AgentWorker.

func WithDescription 

func WithDescription(desc string) Option

WithDescription sets the agent description. Applies to Agent and AgentWorker.

func WithDisableFingerprintCheck added in v0.1.6 

func WithDisableFingerprintCheck(disable bool) Option

WithDisableFingerprintCheck disables caller-vs-worker fingerprint verification at activity entry. This option is applicable to the Temporal runtime only (WithTemporalConfig / WithTemporalClient). Break-glass only: keep false by default to avoid config drift across pods/workers. Not allowed for NewAgentWorker (remote worker process).

func WithHooks added in v0.2.3 

func WithHooks(name string, agentHooks AgentHooks) Option

WithHooks registers a named group of middleware hooks on the agent. name should be unique across all WithHooks calls; it is used for Temporal fingerprinting and run correlation (see RunMeta). Can be called multiple times; each call appends a new group that runs independently with its own RunMeta.HooksGroup value, preserving declaration order.

Use hooks to intercept and modify agent behavior at runtime — for example guardrails and PII scrubbing on BeforeLLMHook/AfterLLMHook, tool input scrubbing on BeforeToolHook/AfterToolHook, retrieval filtering on AfterRetrieveHook, and memory tenant isolation on BeforeMemoryLoadHook/BeforeMemoryStoreHook. See AgentHooks for the full list of hook points and common use cases.

func WithInstanceId 

func WithInstanceId(id string) Option

WithInstanceId sets the instance identifier. Applies to Agent and AgentWorker.

func WithLLMClient 

func WithLLMClient(client interfaces.LLMClient) Option

WithLLMClient sets the LLM client. Applies to Agent and AgentWorker.

func WithLLMExecutionConfig added in v0.2.5 

func WithLLMExecutionConfig(cfg ExecutionConfig) Option

WithLLMExecutionConfig overrides timeout and/or max attempts for LLM generate and stream calls. Zero fields keep the SDK default (Timeout: 30m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithLLMSampling 

func WithLLMSampling(s *LLMSampling) Option

WithLLMSampling sets per-agent LLM sampling overrides. Applies to Agent and AgentWorker. When not set, LLM clients use their provider defaults. nil fields / 0 = provider default. Use Reasoning (see types.LLMReasoning) for generic reasoning/thinking; each provider maps it.

func WithLogLevel 

func WithLogLevel(level string) Option

WithLogLevel sets the log level. Applies to Agent and AgentWorker.

func WithLogger 

func WithLogger(l logger.Logger) Option

WithLogger sets the SDK logger (structured logging with log/slog-style attributes). If unset, DefaultLogger is used at WithLogLevel (default "error"), writing to stderr. Use NoopLogger() to disable SDK logging entirely.

func WithLogs added in v0.1.10 

func WithLogs(l interfaces.Logs) Option

WithLogs supplies an interfaces.Logs for OTel log export lifecycle management (flush on Agent.Close / AgentWorker.Stop).

When WithObservabilityConfig is nil and the default SDK logger is used (no WithLogger), if this value is a concrete *observability.Logs from observability.NewLogs, [buildAgentConfig] wires logger.DefaultLoggerWithOtelProvider to the same OpenTelemetry LoggerProvider so SDK log lines reach OTLP without an extra WithLogger call.

When WithObservabilityConfig is non-nil and ObservabilityConfig.DisableLogs is false, any WithLogs value is ineffective: [buildAgentConfig] always replaces it with *observability.Logs built from the observability config (same precedence as WithTracer / WithMetrics). A warning is logged if WithLogs had been set.

func WithMCPClients added in v0.1.2 

func WithMCPClients(clients ...interfaces.MCPClient) Option

WithMCPClients adds caller-supplied MCP clients (e.g. custom transport). Each client's interfaces.MCPClient.Name must be non-empty and unique among all MCP clients, including those created from WithMCPConfig. Use mcpclient.NewClient with mcpclient.WithToolFilter for the same allow/block filtering as MCPConfig.ToolFilter (mcpclient.BuildConfig validates the filter; github.com/agenticenv/agent-sdk-go/pkg/mcp.MCPToolFilter.Apply runs in mcpclient.Client.ListTools). Applies to Agent and AgentWorker.

func WithMCPConfig added in v0.1.2 

func WithMCPConfig(servers MCPServers) Option

WithMCPConfig registers MCP servers by key. See WithMCPRegistry to change clients later. Applies to Agent and AgentWorker.

func WithMCPExecutionConfig added in v0.2.5 

func WithMCPExecutionConfig(cfg ExecutionConfig) Option

WithMCPExecutionConfig overrides timeout and/or max attempts for MCP calls. Zero fields keep the SDK default (Timeout: 30m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithMCPRegistry added in v0.2.2 

func WithMCPRegistry(reg MCPRegistry) Option

WithMCPRegistry sets the MCP client registry. Use Register, RegisterClient, and Unregister before Run or Stream. Applies to Agent and AgentWorker.

func WithMaxIterations 

func WithMaxIterations(n int) Option

WithMaxIterations sets the max number of LLM rounds. Applies to Agent and AgentWorker.

func WithMaxSubAgentDepth 

func WithMaxSubAgentDepth(depth int) Option

WithMaxSubAgentDepth sets the maximum sub-agent nesting depth from this agent (direct children = 1). Default is 2 when unset or <= 0. Applies to Agent and AgentWorker.

func WithMemory added in v0.2.2 

func WithMemory(cfg memory.Config) Option

WithMemory enables long-term memory for the agent. Applies to Agent and AgentWorker. Pass memory.DefaultConfig for SDK defaults or a custom memory.Config. Use a shipped backend (pkg/memory/weaviate or pkg/memory/pgvector) or your own interfaces.Memory. The application owns Clear on the store when required; the agent runtime does not call Clear.

func WithMemoryExecutionConfig added in v0.2.5 

func WithMemoryExecutionConfig(cfg ExecutionConfig) Option

WithMemoryExecutionConfig overrides timeout and/or max attempts for memory recall and store calls. Zero fields keep the SDK default (Timeout: 5m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithMetrics added in v0.1.10 

func WithMetrics(metrics interfaces.Metrics) Option

WithMetrics supplies a interfaces.Metrics for use without WithObservabilityConfig, or when ObservabilityConfig.DisableMetrics is true (no OTLP metrics client is built from config).

When WithObservabilityConfig is non-nil and ObservabilityConfig.DisableMetrics is false, any WithMetrics value is ineffective: [buildAgentConfig] always replaces it with the OTLP metrics client built from the observability config (same precedence as WithTracer / WithLogs). A warning is logged if WithMetrics had been set.

func WithName 

func WithName(name string) Option

WithName sets the human-readable agent name (any characters; leading/trailing space trimmed on build). It appears in responses and streaming events as-is. Temporal workflow ID segments derived from the name are sanitized separately (spaces and unsafe characters become hyphens); task queue names are not derived from Name.

func WithObservabilityConfig added in v0.1.10 

func WithObservabilityConfig(config *ObservabilityConfig) Option

WithObservabilityConfig sets OTLP export settings shared by the interactive/autonomous client and the worker. The digest of this struct participates in [agentConfigFingerprint] so Temporal caller and worker agree before executing activities.

When non-nil, [buildAgentConfig] builds OTLP interfaces.Tracer, interfaces.Metrics, and (unless ObservabilityConfig.DisableLogs is true) *observability.Logs from this config whenever the corresponding Disable* flag is false. Those built clients always replace any values from WithTracer, WithMetrics, or WithLogs for the same signal; warnings are logged if an injection would be discarded. Use either observability-driven OTLP from this struct or manual injection — not both for the same signal.

func WithResponseFormat 

func WithResponseFormat(rf *interfaces.ResponseFormat) Option

WithResponseFormat sets the LLM response format (e.g. JSON with schema). Applies to Agent and AgentWorker. When not set, the agent uses text-only output (no response_format override).

func WithRetrieverExecutionConfig added in v0.2.5 

func WithRetrieverExecutionConfig(cfg ExecutionConfig) Option

WithRetrieverExecutionConfig overrides timeout and/or max attempts for retriever prefetch calls. Zero fields keep the SDK default (Timeout: 5m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithRetrieverMode added in v0.1.11 

func WithRetrieverMode(mode RetrieverMode) Option

WithRetrieverMode sets how retrievers participate in runs. Applies to Agent and AgentWorker. When omitted, RetrieverModeAgentic is used: retrievers are exposed as tools and the LLM decides when to call them. RetrieverModeHybrid combines pre-fetched context with agentic tool access. RetrieverModePrefetch injects context before the first LLM call without exposing retriever tools.

func WithRetrievers added in v0.1.11 

func WithRetrievers(retrievers ...interfaces.Retriever) Option

WithRetrievers registers vector/document retrievers (e.g. pkg/retriever/weaviate). Each entry must be non-nil. Applies to Agent and AgentWorker.

func WithSubAgentExecutionConfig added in v0.2.5 

func WithSubAgentExecutionConfig(cfg ExecutionConfig) Option

WithSubAgentExecutionConfig overrides timeout and/or max attempts for sub-agent delegation calls. Zero fields keep the SDK default (MaxAttempts: 1). Zero Timeout falls back to the agent run timeout set via WithTimeout rather than a fixed default. Applies to Agent and AgentWorker.

func WithSubAgentRegistry added in v0.2.2 

func WithSubAgentRegistry(reg SubAgentRegistry) Option

WithSubAgentRegistry sets the sub-agent registry. Use Register and Unregister before Run or Stream. Applies to Agent and AgentWorker.

func WithSubAgents 

func WithSubAgents(subAgents ...*Agent) Option

WithSubAgents sets sub-agents at agent creation. See WithSubAgentRegistry to change them later. Applies to Agent and AgentWorker.

func WithSystemPrompt 

func WithSystemPrompt(prompt string) Option

WithSystemPrompt sets the system prompt. Applies to Agent and AgentWorker.

func WithTemporalClient 

func WithTemporalClient(tc client.Client, taskQueue string) Option

WithTemporalClient sets a pre-configured client for the Temporal execution runtime. Use when you need TLS, API keys, cloud endpoints, or other options not covered by TemporalConfig. Task queue must still be set (via this option's taskQueue argument). Use either WithTemporalConfig or WithTemporalClient, not both. The agent does not close the client when Close() is called; the caller owns the lifecycle.

func WithTemporalConfig 

func WithTemporalConfig(cfg *TemporalConfig) Option

WithTemporalConfig sets connection options for the Temporal execution runtime. Applies to Agent and AgentWorker. Use either WithTemporalConfig or WithTemporalClient, not both.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets a maximum wait for Run and Stream. Agent only. Ignored by AgentWorker. When unset, the default is 5m for AgentModeInteractive and 60m for AgentModeAutonomous.

func WithToolApprovalPolicy 

func WithToolApprovalPolicy(policy interfaces.AgentToolApprovalPolicy) Option

WithToolApprovalPolicy sets when tools can run without approval. Applies to Agent and AgentWorker.

func WithToolAuthExecutionConfig added in v0.2.5 

func WithToolAuthExecutionConfig(cfg ExecutionConfig) Option

WithToolAuthExecutionConfig overrides timeout and/or max attempts for tool authorization calls. Zero fields keep the SDK default (Timeout: 30m, MaxAttempts: 1). Applies to Agent and AgentWorker.

func WithToolExecutionConfig added in v0.2.5 

func WithToolExecutionConfig(cfg ExecutionConfig) Option

WithToolExecutionConfig overrides timeout and/or max attempts for tool execution calls. Zero fields keep the SDK default (Timeout: 30m, MaxAttempts: 3). Applies to Agent and AgentWorker.

func WithToolRegistry 

func WithToolRegistry(reg ToolRegistry) Option

WithToolRegistry sets the tool registry. Use Register and Unregister before Run or Stream. Applies to Agent and AgentWorker.

func WithTools 

func WithTools(tools ...interfaces.Tool) Option

WithTools sets tools at agent creation. See WithToolRegistry to change tools later. Applies to Agent and AgentWorker.

func WithTracer added in v0.1.10 

func WithTracer(tracer interfaces.Tracer) Option

WithTracer supplies a interfaces.Tracer for use without WithObservabilityConfig, or when ObservabilityConfig.DisableTraces is true (no OTLP tracer is built from config).

When WithObservabilityConfig is non-nil and ObservabilityConfig.DisableTraces is false, any WithTracer value is ineffective: [buildAgentConfig] always replaces it with the OTLP tracer built from the observability config (same precedence as WithMetrics / WithLogs). A warning is logged if WithTracer had been set.

type RequireAllToolApprovalPolicy 

type RequireAllToolApprovalPolicy struct{}

RequireAllToolApprovalPolicy requires approval for every tool. Default when no policy is set.

func (RequireAllToolApprovalPolicy) RequiresApproval 

func (RequireAllToolApprovalPolicy) RequiresApproval(interfaces.Tool) bool

type RetrieverMode added in v0.1.11 

type RetrieverMode = types.RetrieverMode

RetrieverMode selects how retrievers are used in a run. Aliases types.RetrieverMode.

type RetrieverTool added in v0.1.11 

type RetrieverTool struct {
	// RetrieverName is the stable key from [interfaces.Retriever.Name] (used in tool name / display name).
	RetrieverName string
	Retriever     interfaces.Retriever
}

RetrieverTool implements interfaces.Tool for RetrieverModeAgentic and RetrieverModeHybrid.

func (*RetrieverTool) Description added in v0.1.11 

func (t *RetrieverTool) Description() string

Description implements interfaces.Tool.

func (*RetrieverTool) DisplayName added in v0.1.11 

func (t *RetrieverTool) DisplayName() string

DisplayName implements interfaces.Tool.

func (*RetrieverTool) Execute added in v0.1.11 

func (t *RetrieverTool) Execute(ctx context.Context, args map[string]any) (any, error)

Execute implements interfaces.Tool: reads the query argument, calls interfaces.Retriever.Search, and returns matching documents. Formatting for the LLM is done by the runtime.

func (*RetrieverTool) Name added in v0.1.11 

func (t *RetrieverTool) Name() string

Name implements interfaces.Tool.

func (*RetrieverTool) Parameters added in v0.1.11 

func (t *RetrieverTool) Parameters() interfaces.JSONSchema

Parameters implements interfaces.Tool. Requires types.RetrieverToolParamQuery.

func (*RetrieverTool) ToolKind added in v0.2.2 

func (t *RetrieverTool) ToolKind() types.ToolKind

ToolKind implements types.ToolKindProvider.

type RunMeta added in v0.2.3 

type RunMeta = hooks.RunMeta

type RunStatus added in v0.3.0 

type RunStatus = types.RunStatus

RunStatus is the lifecycle status of an agent run. Re-exported from internal/types so callers only import pkg/agent.

type RunTelemetry added in v0.2.2 

type RunTelemetry = types.RunTelemetry

RunTelemetry captures the orchestration lifecycle metrics for a single agent run.

type StorageTelemetry added in v0.2.2 

type StorageTelemetry = types.StorageTelemetry

StorageTelemetry tracks RAG retrieval operations (prefetch, agentic, and hybrid searches).

type SubAgentDelegationApprovalRequestValue added in v0.1.6 

type SubAgentDelegationApprovalRequestValue = types.SubAgentDelegationApprovalRequestValue

SubAgentDelegationApprovalRequestValue is the decoded Value for delegation approvals.

func ParseDelegationApproval added in v0.1.6 

func ParseDelegationApproval(req *ApprovalRequest) (SubAgentDelegationApprovalRequestValue, error)

ParseDelegationApproval decodes Value when Name is ApprovalRequestNameSubAgent.

type SubAgentRegistry added in v0.2.2 

type SubAgentRegistry interface {
	Register(sub *Agent) error
	Get(name string) (*Agent, error)
	List() []*Agent
	Unregister(name string) error
}

SubAgentRegistry stores sub-agents for a parent agent.

func NewSubAgentRegistry added in v0.2.2 

func NewSubAgentRegistry() SubAgentRegistry

NewSubAgentRegistry returns an empty sub-agent registry for use with WithSubAgentRegistry.

type TemporalConfig 

type TemporalConfig = temporal.TemporalConfig

TemporalConfig holds connection settings for the Temporal-based execution runtime (host, namespace, task queue).

TaskQueue is required and must be unique per agent. Use different task queues when running multiple agents in the same process (e.g. "my-agent-math", "my-agent-creative"). For multiple instances of the same agent (e.g. scaled pods), use WithInstanceId() so each instance gets a unique queue derived as {TaskQueue}-{InstanceId}.

When using DisableLocalWorker, the agent and NewAgentWorker must use the same TaskQueue (and same InstanceId if set) so client and worker runtimes pair correctly.

type ToolApprovalRequestValue added in v0.1.6 

type ToolApprovalRequestValue = types.ToolApprovalRequestValue

ToolApprovalRequestValue is the decoded Value for tool approvals (matches CUSTOM approval payload).

func ParseToolApproval added in v0.1.6 

func ParseToolApproval(req *ApprovalRequest) (ToolApprovalRequestValue, error)

ParseToolApproval decodes Value when Name is ApprovalRequestNameTool (handles map[string]any from JSON).

type ToolRegistry added in v0.2.2 

type ToolRegistry interface {
	Register(tool interfaces.Tool) error
	Get(name string) (interfaces.Tool, error)
	List() []interfaces.Tool
	Unregister(name string) error
}

ToolRegistry stores tools for an agent.

func NewToolRegistry added in v0.2.2 

func NewToolRegistry() ToolRegistry

NewToolRegistry returns an empty in-process tool registry for use with WithToolRegistry.

type ToolTelemetry added in v0.2.2 

type ToolTelemetry = types.ToolTelemetry

ToolTelemetry tracks tool invocation counts and per-tool breakdowns across a single agent run.

Source Files

View all Source files

Directories

Path Synopsis
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.

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.