agent

package
v0.1.7 Latest Latest
Warning

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

 Go to latest Published: Apr 30, 2026 License: Apache-2.0 Imports: 22 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
)

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 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 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) 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 (m *MCPTool) Description() string

Description implements interfaces.Tool.

func (*MCPTool) DisplayName added in v0.1.4 

func (m *MCPTool) DisplayName() string

DisplayName implements interfaces.Tool.

func (*MCPTool) Execute added in v0.1.2 

func (m *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 (m *MCPTool) Name() string

Name implements interfaces.Tool.

func (*MCPTool) Parameters added in v0.1.2 

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

Parameters implements interfaces.Tool.

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

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