agent

package
v0.1.11 Latest Latest
Warning

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

 Go to latest Published: May 24, 2026 License: Apache-2.0 Imports: 30 Imported by: 0

Documentation

Index

Constants

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 ErrAgentAlreadyRunning = errors.New("agent already has an active run")

ErrAgentAlreadyRunning is returned when Run, RunAsync, or Stream is called while a run is already in progress.

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 executed via workflow, not Execute()")

ErrSubAgentToolNotExecutable is returned by SubAgentTool.Execute. Normal runs delegate via AgentWorkflow child workflows; Execute() is only for misconfigured or direct activity calls.

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 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()).

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 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.

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) Close 

func (a *Agent) Close()

Close stops an embedded local worker if present, then closes the runtime (which may terminate runs, release remote resources, and close backend connections owned by the runtime, depending on the implementation). Only one run can be active per agent.

func (*Agent) OnApproval 

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

OnApproval completes a tool approval when using Agent.Stream. Pass the token from the approval event and the chosen status (see streaming examples).

func (*Agent) Run 

func (a *Agent) Run(ctx context.Context, input string, conversationID string) (*AgentRunResult, error)

Run starts one execution and returns the result. Use WithApprovalHandler when tools require approval for Run (handler uses req.Respond); [Stream] uses approval events and Agent.OnApproval. Use WithTimeout or a context with deadline to avoid blocking. When using WithConversation, pass the conversation ID; agent and worker must use the same ID.

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) RunAsync 

func (a *Agent) RunAsync(ctx context.Context, input string, conversationID string) (resultCh <-chan AgentRunAsyncResult, approvalCh <-chan *ApprovalRequest, err error)

RunAsync starts the run in a goroutine and returns two channels:

  • resultCh: receives exactly one RunAsyncResult, then closes.
  • approvalCh: receives each pending tool approval; call req.Respond. Channel closes when the run ends.

For each approval, call req.Respond(Approved|Rejected) exactly once.

WithApprovalHandler is temporarily replaced for the duration of the run; restore happens when the run finishes. If tools do not require approval, approvalCh is still closed immediately with no values.

func (*Agent) Stream added in v0.0.10 

func (a *Agent) Stream(ctx context.Context, input string, conversationID string) (<-chan events.AgentEvent, error)

Stream starts the run and returns a channel of AgentEvent. Streaming continues until the root run’s terminal lifecycle event (AgentEventTypeRunFinished / *AgentRunFinishedEvent); sub-agent runs may emit additional AgentEventTypeRunFinished events that are delivered but do not close the root stream (see doc on BaseEvent). After the root completes, the channel may stay open briefly while the backend finishes cleanup, then closes. For approvals (tool or delegation), receive AgentEventTypeCustom (AgentCustomEvent), parse with ParseCustomEventApproval / ParseCustomEventDelegation, then call Agent.OnApproval with the token from Value. When using WithConversation, pass the conversation ID.

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 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 AgentRunAsyncResult added in v0.1.6 

type AgentRunAsyncResult = types.AgentRunAsyncResult

AgentRunAsyncResult is the single outcome from Agent.RunAsync. After the channel closes, Err is non-nil on failure; otherwise Result is non-nil.

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 AgentRunResult added in v0.1.6 

type AgentRunResult = types.AgentRunResult

AgentRunResult is the structured result of Agent.Run and Agent.RunAsync ([RunAsyncResult.Result]).

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 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.

AgentWorkflow chooses delegation vs AgentToolExecuteActivity using SubAgentRoutes keyed by tool name, not by asserting AgentTool in workflow code. AgentTool is still used elsewhere (e.g. toolApprovalMetadata walks toolsList and asserts AgentTool to set delegation fields on approval events).

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.

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 with WithApprovalHandler). 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.

type ApprovalRequest 

type ApprovalRequest = types.ApprovalRequest

ApprovalRequest describes a pending tool approval for Agent.Run and Agent.RunAsync. Name + Value mirror CUSTOM stream events; use ParseToolApproval / ParseDelegationApproval. Respond is always set; call it once with ApprovalStatusApproved or ApprovalStatusRejected. For streaming approvals, use Agent.OnApproval 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
)

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 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 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 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.

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 EnableRemoteWorkers added in v0.0.10 

func EnableRemoteWorkers() Option

EnableRemoteWorkers enables the runtime's remote event path (out-of-process event delivery). Agent only. If unset, streaming and approvals use in-process channels only. Required for some setups with DisableLocalWorker and NewAgentWorker, and for certain approval/streaming configurations.

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 A2A agent servers by stable key (used in tool names and default client naming). Each A2AConfig must set [A2AConfig.URL]; the agent wires a default A2A client internally (no a2aproject/a2a-go/v2 usage in application code). Skills are discovered and merged with WithA2AClients. 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 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 sets the approval callback for Run. Required when tools need approval. The callback receives req with req.Respond set; call req.Respond(Approved|Rejected). Agent only; Stream uses OnApproval on events.

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(conv interfaces.Conversation) Option

WithConversation sets the conversation for message history. Applies to Agent and AgentWorker. The user creates the conversation (inmem or redis) and passes it to the agent. System messages are not stored; agent SystemPrompt is used for LLM calls.

Choose implementation based on deployment:

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

The user owns the conversation lifecycle. Call Clear on the conversation when appropriate (e.g., when ending a session). The agent never calls Clear. Note: Agent and worker must use the same conversation and ID when using remote workers.

func WithConversationSize 

func WithConversationSize(size int) Option

WithConversationSize sets the max messages to fetch for LLM context (default 20).

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 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 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 stable key (used in tool names and default client naming). Each MCPConfig must set [MCPConfig.Transport] using transport types from github.com/agenticenv/agent-sdk-go/pkg/mcp; the agent wires a default MCP client internally (no modelcontextprotocol/go-sdk usage in application code). Tools are discovered and merged with WithMCPClients. 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 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 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 WithStream 

func WithStream(enable bool) Option

WithStream enables partial content streaming. Applies to Agent and AgentWorker.

func WithSubAgents 

func WithSubAgents(subAgents ...*Agent) Option

WithSubAgents registers sub-agents. Each is exposed to the parent LLM as a tool (AgentTool). Delegation runs through the execution runtime (child run), not Tool.Execute. The sub-agent graph is validated at agent build: no cycles, depth <= WithMaxSubAgentDepth (default 2).

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 WithToolRegistry 

func WithToolRegistry(reg interfaces.ToolRegistry) Option

WithToolRegistry sets a tool registry. Applies to Agent and AgentWorker.

func WithTools 

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

WithTools registers tools with the agent. 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 a numbered plain-text summary of matching documents.

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.

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 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).

Source Files

View all Source files

Jump to

Keyboard shortcuts

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