agent

package
v0.1.2 Latest Latest
Warning

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

 Go to latest Published: Apr 13, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

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) (*AgentResponse, 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 RunAsyncResult, 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 *AgentEvent, error)

Stream starts the run and returns a channel of AgentEvent. Events are streamed until AgentEventComplete from this agent (the root of the run). Complete events from delegated sub-agents are still delivered but do not close the stream. After that root complete, the channel may stay open until the backend finishes the run (e.g. post-delegation work), then closes; exact timing depends on the runtime implementation. For approvals (tool or delegation), receive AgentEventApproval and call Agent.OnApproval as in the streaming examples. When using WithConversation, pass the conversation ID.

type AgentEvent 

type AgentEvent = types.AgentEvent

AgentEvent 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 AgentEventComplete from a sub-agent does not close the root stream. For AgentEventApproval, the requesting agent is also on AgentName (not duplicated on Approval).

type AgentEventType 

type AgentEventType = types.AgentEventType

AgentEventType identifies a streamed event kind from the execution runtime. 

const (
	AgentEventContent       AgentEventType = types.AgentEventContent
	AgentEventContentDelta  AgentEventType = types.AgentEventContentDelta
	AgentEventThinking      AgentEventType = types.AgentEventThinking
	AgentEventThinkingDelta AgentEventType = types.AgentEventThinkingDelta
	AgentEventToolCall      AgentEventType = types.AgentEventToolCall
	AgentEventToolResult    AgentEventType = types.AgentEventToolResult
	AgentEventApproval      AgentEventType = types.AgentEventApproval
	AgentEventError         AgentEventType = types.AgentEventError
	AgentEventComplete      AgentEventType = types.AgentEventComplete
)

type AgentResponse 

type AgentResponse = types.AgentResponse

AgentResponse is the structured result of Agent.Run and Agent.RunAsync ([RunAsyncResult.Response]).

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

type ApprovalEvent = types.ApprovalEvent

ApprovalEvent is the payload for AgentEventApproval. The agent that requested approval is on the enclosing AgentEvent's AgentName field, not repeated here. Use with Agent.OnApproval when the user approves or rejects; see streaming examples.

type ApprovalHandler 

type ApprovalHandler = types.ApprovalHandler

ApprovalHandler is called when a tool needs 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. Respond is always set; call it once with ApprovalStatusApproved or ApprovalStatusRejected. For streaming approvals, use Agent.OnApproval with the approval event payload instead.

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

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 RunAsyncResult 

type RunAsyncResult = types.RunAsyncResult

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

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 ToolApprovalKind 

type ToolApprovalKind = types.ToolApprovalKind

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

const (
	// ToolApprovalKindTool is a normal tool execution (default when Kind is empty for older payloads).
	ToolApprovalKindTool ToolApprovalKind = types.ToolApprovalKindTool
	// ToolApprovalKindDelegation is approval to run a registered sub-agent (delegate).
	ToolApprovalKindDelegation ToolApprovalKind = types.ToolApprovalKindDelegation
)

type ToolCallEvent 

type ToolCallEvent = types.ToolCallEvent

ToolCallEvent carries tool name, arguments, and result in streamed events.

type ToolCallStatus 

type ToolCallStatus = types.ToolCallStatus

ToolCallStatus is the lifecycle state of a tool call in streamed events. 

const (
	ToolCallStatusPending   ToolCallStatus = types.ToolCallStatusPending
	ToolCallStatusRunning   ToolCallStatus = types.ToolCallStatusRunning
	ToolCallStatusCompleted ToolCallStatus = types.ToolCallStatusCompleted
	ToolCallStatusFailed    ToolCallStatus = types.ToolCallStatusFailed
)

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.