types

type A2ASkillFilter ¶ added in v0.1.9

type A2ASkillFilter struct {
	// AllowSkills is an allow-list of skill IDs. Only listed skills are registered.
	AllowSkills []string
	// BlockSkills is a block-list of skill IDs. Listed skills are excluded.
	BlockSkills []string
}

A2ASkillFilter restricts which skills from [interfaces.A2AClient.ListSkills] are exposed as tools (exact skill-ID match). Set either AllowSkills or BlockSkills, not both. A2ASkillFilter.Validate checks mutual exclusivity (call from config build, e.g. pkg/a2a/client.BuildConfig). A2ASkillFilter.Apply filters skill specs and assumes Validate already passed for non-empty filters.

func (f A2ASkillFilter) Apply(skills []A2ASkillSpec) []A2ASkillSpec

func (f A2ASkillFilter) Validate() error

type A2ASkillSpec ¶ added in v0.1.9

type A2ASkillSpec struct {
	// ID is the stable machine-readable identifier for the skill (used as tool name).
	ID string `json:"id"`
	// Name is the human-readable display name.
	Name string `json:"name,omitempty"`
	// Description explains when and how to invoke this skill; shown to the LLM.
	Description string `json:"description,omitempty"`
	// Tags are optional categorisation labels.
	Tags []string `json:"tags,omitempty"`
	// InputModes overrides the agent-level default input modes for this skill.
	InputModes []string `json:"inputModes,omitempty"`
	// OutputModes overrides the agent-level default output modes for this skill.
	OutputModes []string `json:"outputModes,omitempty"`
	// Examples are optional illustrative prompt strings shown to the LLM.
	Examples []string `json:"examples,omitempty"`
}

A2ASkillSpec describes one invocable skill advertised by an A2A agent. Used by the agent host to expose the remote skill as a Tool to the LLM. Canonical definition here; aliased in github.com/agenticenv/agent-sdk-go/pkg/interfaces.

type AgentMode ¶ added in v0.1.3

type AgentMode string

AgentMode distinguishes how the agent is driven: human-in-the-loop versus self-directed runs. The string value is stable for configuration and fingerprints (see pkg/agent.WithAgentMode).

const (
	// AgentModeInteractive is the default: the agent expects user turns, approvals, or other
	// interactive signals between steps when the product requires them.
	AgentModeInteractive AgentMode = "interactive"
	// AgentModeAutonomous indicates a run where the agent proceeds without blocking on user input
	// for each step (subject to tool policy and limits).
	AgentModeAutonomous AgentMode = "autonomous"
)

type AgentRunAsyncResult ¶ added in v0.1.6

type AgentRunAsyncResult struct {
	Result *AgentRunResult
	Error  error
}

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

type AgentRunResult ¶ added in v0.1.6

type AgentRunResult struct {
	Content   string         `json:"content"`
	AgentName string         `json:"agent_name"`
	Model     string         `json:"model"`
	Metadata  map[string]any `json:"metadata"`
	// Usage is the sum of token usage across all LLM calls in this run (when reported by the provider).
	Usage *LLMUsage `json:"usage,omitempty"`
}

AgentRunResult is the structured result of a completed run (content, model, metadata).

type AgentToolExecutionMode ¶ added in v0.1.7

type AgentToolExecutionMode string

ToolExecutionMode specifies how tools are executed in parallel or sequentially.

const (
	// AgentToolExecutionModeParallel specifies that tools are executed in parallel.
	AgentToolExecutionModeParallel AgentToolExecutionMode = "parallel"
	// AgentToolExecutionModeSequential specifies that tools are executed sequentially.
	AgentToolExecutionModeSequential AgentToolExecutionMode = "sequential"
)

type ApprovalHandler ¶

type ApprovalHandler func(ctx context.Context, req *ApprovalRequest)

ApprovalHandler is called when a tool needs approval (Run with WithApprovalHandler). req.Respond is always set; call req.Respond(Approved) or Rejected when ready.

type ApprovalRequest ¶

type ApprovalRequest struct {
	Name    ApprovalRequestName `json:"name,omitempty"`
	Value   any                 `json:"value,omitempty"`
	Respond ApprovalSender      `json:"-"`
}

ApprovalRequest is one pending approval callback. Name + Value match CUSTOM semantics; Value is a ToolApprovalRequestValue or SubAgentDelegationApprovalRequestValue. Set Respond before invoking the handler (see PrepareApprovalFromCustomEvent).

func PrepareApprovalFromCustomEvent(ev *events.AgentCustomEvent) (req *ApprovalRequest, approvalToken string, err error)

type ApprovalRequestName ¶ added in v0.1.6

type ApprovalRequestName string

ApprovalRequestName classifies the approval payload.

const (
	ApprovalRequestNameTool     ApprovalRequestName = "tool_approval"
	ApprovalRequestNameSubAgent ApprovalRequestName = "sub_agent_delegation"
)

type ApprovalSender ¶

type ApprovalSender func(status ApprovalStatus) error

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

type ApprovalStatus ¶

type ApprovalStatus string

const (
	ApprovalStatusNone     ApprovalStatus = "NONE"
	ApprovalStatusPending  ApprovalStatus = "PENDING"
	ApprovalStatusApproved ApprovalStatus = "APPROVED"
	ApprovalStatusRejected ApprovalStatus = "REJECTED"
	// ApprovalStatusUnavailable means the approval request could not be delivered (e.g. event stream down). It is not a user rejection.
	ApprovalStatusUnavailable ApprovalStatus = "UNAVAILABLE"
)

type JSONSchema ¶ added in v0.1.2

type JSONSchema map[string]any

func (s JSONSchema) MarshalJSON() ([]byte, error)

type LLMReasoning ¶ added in v0.1.2

type LLMReasoning struct {
	// Enabled requests reasoning/thinking where the provider supports it.
	// Anthropic: if true and BudgetTokens is 0, uses the minimum extended-thinking budget (1024 tokens).
	// OpenAI: does not infer reasoning_effort from Enabled alone (standard models reject that param).
	// Gemini: contributes to turning on thought output with IncludeThoughts.
	Enabled bool

	// Effort is a generic reasoning intensity: "none", "minimal", "low", "medium", "high", "xhigh".
	// OpenAI: sent as reasoning_effort only when non-empty; use only with reasoning-capable models.
	// Gemini: mapped to ThinkingLevel when recognized (low/medium/high/minimal), unless BudgetTokens > 0.
	// Anthropic: not used (use Enabled and BudgetTokens for extended thinking).
	Effort string

	// BudgetTokens is the token budget for internal reasoning / extended thinking.
	// Anthropic: extended thinking; must be >= 1024 when non-zero (values below are clamped).
	// Gemini: ThinkingBudget. If non-zero, Effort is not mapped to ThinkingLevel (API allows only one).
	// OpenAI: not used.
	BudgetTokens int
}

LLMReasoning configures reasoning/thinking in a provider-agnostic way. Each LLM client maps these fields to its API; fields that do not apply are ignored.

type LLMSampling ¶

type LLMSampling struct {
	Temperature *float64 // 0-2 OpenAI, 0-1 Anthropic; also Gemini
	MaxTokens   int      // 0 = provider default
	TopP        *float64 // 0-1; OpenAI and Gemini (not Anthropic)
	TopK        *int     // Anthropic only
	// Reasoning: optional generic reasoning/thinking; mapped per provider.
	Reasoning *LLMReasoning
}

LLMSampling holds per-agent LLM sampling overrides. nil/0 = provider default. One LLM client can serve multiple agents with different sampling.

type LLMUsage ¶ added in v0.1.2

type LLMUsage struct {
	PromptTokens       int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens   int64 `json:"completion_tokens,omitempty"`
	TotalTokens        int64 `json:"total_tokens,omitempty"`
	CachedPromptTokens int64 `json:"cached_prompt_tokens,omitempty"`
	ReasoningTokens    int64 `json:"reasoning_tokens,omitempty"`
}

LLMUsage reports token counts from the provider for one completion. Values are best-effort: some fields may be zero when the API does not return them.

type MCPLoopback ¶ added in v0.1.2

type MCPLoopback struct {
	Transport any
}

MCPLoopback is test-only wiring: it holds a pre-built protocol transport as a dynamic value. External users should use pkg/mcp transport types (MCPStdio, MCPStreamableHTTP). MCPLoopback is not re-exported from pkg/mcp.

func (MCPLoopback) Kind() MCPTransportType

func (lb MCPLoopback) Validate() error

type MCPStdio ¶ added in v0.1.2

type MCPStdio struct {
	Command string
	Args    []string
	Env     map[string]string
}

MCPStdio runs an MCP server as a subprocess (stdio).

func (MCPStdio) Kind() MCPTransportType

func (s MCPStdio) Validate() error

type MCPStreamableHTTP ¶ added in v0.1.2

type MCPStreamableHTTP struct {
	URL string
	// Token is a static bearer token when OAuthClientCreds is not used for auth.
	Token string
	// OAuthClientCreds configures OAuth2 client-credentials; when any OAuth field is set, Token must be empty and id/secret/token_url are required together.
	OAuthClientCreds *clientcredentials.Config
	Headers          map[string]string
	SkipTLSVerify    bool
}

MCPStreamableHTTP uses the streamable HTTP MCP transport.

Optional static bearer Token, or OAuthClientCreds for OAuth2 client credentials. Token and active OAuth client-credentials must not both be set; omit both for URL-only access (use Headers for custom auth headers such as API keys).

func (MCPStreamableHTTP) Kind() MCPTransportType

func (h MCPStreamableHTTP) Validate() error

type MCPToolFilter ¶ added in v0.1.2

type MCPToolFilter struct {
	AllowTools []string
	BlockTools []string
}

MCPToolFilter restricts which tools from Discover are registered (exact name match). Set either AllowTools (allow-list) or BlockTools (block-list), not both. MCPToolFilter.Validate checks constraints (call from config build, e.g. github.com/agenticenv/agent-sdk-go/pkg/mcp/client.BuildConfig). MCPToolFilter.Apply filters tool specs and assumes Validate already passed for non-empty filters.

func (f MCPToolFilter) Apply(specs []ToolSpec) []ToolSpec

func (f MCPToolFilter) Validate() error

type MCPTransportConfig ¶ added in v0.1.2

type MCPTransportConfig interface {
	// Kind returns a stable transport id ("stdio", "streamable_http") for logging and routing.
	Kind() MCPTransportType
	// Validate checks the transport is usable before connect (the default MCP client calls this from NewClient).
	Validate() error
}

MCPTransportConfig describes how to reach one MCP server. Concrete types are MCPStdio, MCPStreamableHTTP, and MCPLoopback (tests).

type MCPTransportType ¶ added in v0.1.2

type MCPTransportType string

const (
	MCPTransportTypeStdio          MCPTransportType = "stdio"
	MCPTransportTypeStreamableHTTP MCPTransportType = "streamable_http"
)

const MCPTransportTypeLoopback MCPTransportType = "loopback"

type OTLPProtocol ¶ added in v0.1.10

type OTLPProtocol string

OTLPProtocol selects the wire format used by OTLP trace and metrics exporters. The string value is stable and used in fingerprints — do not change existing values.

const (
	// OTLPProtocolGRPC exports telemetry over gRPC. This is the default and is supported
	// by virtually all OpenTelemetry collectors.
	OTLPProtocolGRPC OTLPProtocol = "grpc"

	// OTLPProtocolHTTP exports telemetry over HTTP/protobuf. Use when gRPC is blocked
	// by a firewall or proxy that only passes HTTP/1.1 traffic.
	OTLPProtocolHTTP OTLPProtocol = "http"
)

type RetrieverMode ¶ added in v0.1.11

type RetrieverMode string

RetrieverMode selects how registered retrievers participate in agent runs. String values are stable for configuration (see pkg/agent.WithRetrieverMode).

const (
	// RetrieverModeAgentic is the default: the agent decides when to query retrievers (e.g. via tools).
	RetrieverModeAgentic RetrieverMode = "agentic"
	// RetrieverModePrefetch runs retrievers before the first LLM call and injects context up front.
	RetrieverModePrefetch RetrieverMode = "prefetch"
	// RetrieverModeHybrid combines prefetch with agentic retrieval during the run.
	RetrieverModeHybrid RetrieverMode = "hybrid"
)

type SubAgentDelegationApprovalRequestValue ¶ added in v0.1.6

type SubAgentDelegationApprovalRequestValue struct {
	AgentName     string         `json:"agentName,omitempty"`
	SubAgentName  string         `json:"subAgentName,omitempty"`
	Args          map[string]any `json:"args,omitempty"`
	ApprovalToken string         `json:"approvalToken,omitempty"`
}

SubAgentDelegationApprovalRequestValue is the JSON payload for sub-agent delegation approval.

func DelegationApprovalFromEventValue(ev events.AgentCustomEventDelegationValue) SubAgentDelegationApprovalRequestValue

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

type SubAgentRoute ¶

type SubAgentRoute struct {
	Name             string                   `json:"name"`
	TaskQueue        string                   `json:"task_queue"`
	ChildRoutes      map[string]SubAgentRoute `json:"child_routes,omitempty"`
	AgentFingerprint string                   `json:"agent_fingerprint,omitempty"`
}

SubAgentRoute tells the runtime how to delegate to a sub-agent (child run on TaskQueue), with nested routes for that sub-agent's sub-agents (frozen at parent run start). AgentFingerprint is the agent config digest for that sub-agent (pkg/agent + temporal.ComputeAgentFingerprint) so the child worker can reject runs when its deployed config does not match the caller.

type ToolApprovalRequestValue ¶ added in v0.1.6

type ToolApprovalRequestValue struct {
	AgentName       string         `json:"agentName,omitempty"`
	ToolCallID      string         `json:"toolCallId,omitempty"`
	ToolName        string         `json:"toolName"`
	ToolDisplayName string         `json:"toolDisplayName,omitempty"`
	Args            map[string]any `json:"args,omitempty"`
	ApprovalToken   string         `json:"approvalToken,omitempty"`
}

ToolApprovalRequestValue is the JSON payload for tool approval (same wire shape as CUSTOM approval value).

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

func ToolApprovalFromEventValue(ev events.AgentCustomEventApprovalValue) ToolApprovalRequestValue

type ToolSpec ¶ added in v0.1.2

type ToolSpec struct {
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Parameters  JSONSchema `json:"parameters"`
}

ToolSpec is the schema sent to the LLM for tool selection. Convert from Tool via ToolToSpec.