types

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
}

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"`
}

type AgentMode string

type AgentRunOptions struct {
	// ConversationOptions selects a conversation session for this call.
	// Required when the agent was configured with WithConversation; must be nil otherwise.
	ConversationOptions *ConversationOptions `json:"conversation_options,omitempty"`
}

type AgentRunResult struct {
	Content   string         `json:"content"`
	AgentName string         `json:"agent_name"`
	Model     string         `json:"model"`
	Metadata  map[string]any `json:"metadata"`
	// RunID identifies this run for correlation and (on Temporal) GetAgentRun / GetAgentStream.
	// Populated for completed [Agent.Run] results; for live streams prefer the
	// runID returned synchronously from [Agent.Stream] / [AgentRun.ID] / [AgentStream.ID].
	RunID string `json:"run_id,omitempty"`
	// Usage is the sum of token usage across all LLM calls in this run (when reported by the provider).
	// Usage acts as the historical root for aggregated token counters.
	LLMUsage *LLMUsage `json:"llm_usage,omitempty"`

	// Telemetry contains the strongly typed nested metrics domain payload.
	Telemetry *AgentTelemetry `json:"telemetry,omitempty"`
}

type AgentStreamOptions struct {
	// ConversationOptions selects a conversation session for this streaming call.
	// Required when the agent was configured with WithConversation; must be nil otherwise.
	ConversationOptions *ConversationOptions `json:"conversation_options,omitempty"`

	// DisableTokenStreaming, when true, instructs the LLM to produce a single complete
	// response rather than a token-by-token stream. All other AG-UI events (lifecycle,
	// tool calls, CUSTOM events) are still emitted. Default false = stream tokens.
	DisableTokenStreaming bool `json:"disable_token_streaming,omitempty"`
}

type AgentTelemetry struct {
	// Run captures the orchestration lifecycle metrics for the run.
	Run RunTelemetry `json:"run"`

	// Tools tracks tool invocation counts and breakdowns for the run.
	Tools ToolTelemetry `json:"tools"`

	// Storage tracks data storage and retrieval operations for the run.
	Storage StorageTelemetry `json:"storage"`
}

type AgentToolExecutionMode string

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

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

type ApprovalRequestName string

type ApprovalSender func(status ApprovalStatus) error

type ApprovalStatus string

type ConversationOptions struct {
	ID string
}

type FinishReason string

type JSONSchema map[string]any

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
}

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
}

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"`
}

type MCPLoopback struct {
	Transport any
}

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

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
}

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

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
}

type MCPTransportType string

type OTLPProtocol string

type RetrieverMode string

type RunStatus string

type RunTelemetry struct {
	// StartedAt tracks the start time of the agent run.
	StartedAt time.Time `json:"started_at"`

	// CompletedAt tracks the completion time of the agent run.
	CompletedAt time.Time `json:"completed_at"`

	// TotalLLMCalls counts how many LLM calls were made during the run.
	// Each iteration counts as one call regardless of how many Temporal retries it took.
	TotalLLMCalls int64 `json:"total_llm_calls"`

	// LLMRetryCount is the total number of Temporal activity retries across all LLM calls in
	// this run. A value of 0 means every LLM activity succeeded on its first attempt.
	// Temporal also exposes per-activity retry counts natively in its metrics and workflow history.
	LLMRetryCount int64 `json:"llm_retry_count,omitempty"`

	// FinishReason explains how the run concluded. See FinishReason for possible values.
	FinishReason FinishReason `json:"finish_reason"`
}

type StorageTelemetry struct {
	// Retriever — RAG searches (prefetch/agentic/hybrid), zero if not configured.
	TotalRetrieverSearches  int64 `json:"total_retriever_searches"`
	FailedRetrieverSearches int64 `json:"failed_retriever_searches"`

	// Breakdown by mode — zero if mode not used.
	PrefetchSearches int64 `json:"prefetch_searches,omitempty"`
	AgenticSearches  int64 `json:"agentic_searches,omitempty"`

	// Memory — long-term recall/store operations, zero if not configured.
	TotalMemoryRecalls  int64 `json:"total_memory_recalls,omitempty"`
	FailedMemoryRecalls int64 `json:"failed_memory_recalls,omitempty"`
	TotalMemoryStores   int64 `json:"total_memory_stores,omitempty"`
	FailedMemoryStores  int64 `json:"failed_memory_stores,omitempty"`
}

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"`
}

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"`
}

type ToolKind string

type ToolKindProvider interface {
	ToolKind() ToolKind
}

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

type ToolTelemetry struct {
	// TotalCalls is the total number of tool invocations made by the agent.
	TotalCalls int64 `json:"total_calls"`

	// FailedCalls is the number of tool invocations that returned an error.
	// Excludes approval-denied and unauthorized cases.
	FailedCalls int64 `json:"failed_calls"`

	// Breakdown tracks invocation counts per tool name.
	// Key: tool name (e.g. "palo_alto_fw_lookup"), Value: invocation count
	Breakdown map[string]int64 `json:"breakdown,omitempty"`

	// FailedBreakdown tracks failed invocation counts per tool name.
	// Excludes approval-denied and unauthorized cases.
	// Key: tool name (e.g. "palo_alto_fw_lookup"), Value: failed invocation count
	FailedBreakdown map[string]int64 `json:"failed_breakdown,omitempty"`
}