agentsdk

package
v0.0.73 Latest Latest
Warning

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

 Go to latest Published: Jul 11, 2026 License: GPL-3.0 Imports: 14 Imported by: 0

Documentation

Overview

Package agentsdk exposes the reusable agent runtime.

Host applications wire this package to their own tools, model providers, hooks, persistence, and infrastructure.

Index

Constants

View Source 
const (
	DefaultMaxTurns                = agent.DefaultMaxTurns
	DefaultMaxToolResultBytes      = agent.DefaultMaxToolResultBytes
	DefaultSubAgentMaxTurns        = agent.DefaultSubAgentMaxTurns
	RecommendedHandoffPromptPrefix = agent.RecommendedHandoffPromptPrefix

	ModelStreamDelta    = agent.ModelStreamDelta
	ModelStreamItemDone = agent.ModelStreamItemDone
	ModelStreamComplete = agent.ModelStreamComplete
	ModelStreamError    = agent.ModelStreamError

	ModelStreamReasoningDelta = agent.ModelStreamReasoningDelta

	StreamEventRawResponse  = agent.StreamEventRawResponse
	StreamEventRunItem      = agent.StreamEventRunItem
	StreamEventAgentUpdated = agent.StreamEventAgentUpdated
	StreamEventContent      = agent.StreamEventContent
	StreamEventSubAgent     = agent.StreamEventSubAgent

	RunItemMessage       = agent.RunItemMessage
	RunItemToolCall      = agent.RunItemToolCall
	RunItemToolOutput    = agent.RunItemToolOutput
	RunItemHandoffCall   = agent.RunItemHandoffCall
	RunItemHandoffOutput = agent.RunItemHandoffOutput
	RunItemReasoning     = agent.RunItemReasoning
	RunItemToolApproval  = agent.RunItemToolApproval
	RunItemCompaction    = agent.RunItemCompaction

	RunLLMAgain     = agent.RunLLMAgain
	StopOnFirstTool = agent.StopOnFirstTool

	ToolAccessLevelFull     = agent.ToolAccessLevelFull
	ToolAccessLevelReadOnly = agent.ToolAccessLevelReadOnly

	ErrorActionRetry    = agent.ErrorActionRetry
	ErrorActionAbort    = agent.ErrorActionAbort
	ErrorActionContinue = agent.ErrorActionContinue

	ReasoningNone   = agent.ReasoningNone
	ReasoningLow    = agent.ReasoningLow
	ReasoningMedium = agent.ReasoningMedium
	ReasoningHigh   = agent.ReasoningHigh
	ReasoningXHigh  = agent.ReasoningXHigh
	ReasoningMax    = agent.ReasoningMax

	TextVerbosityLow    = agent.TextVerbosityLow
	TextVerbosityMedium = agent.TextVerbosityMedium
	TextVerbosityHigh   = agent.TextVerbosityHigh

	LogLevelNormal = agent.LogLevelNormal
	LogLevelDebug  = agent.LogLevelDebug

	SubAgentTaskPending   = agent.SubAgentTaskPending
	SubAgentTaskWaiting   = agent.SubAgentTaskWaiting
	SubAgentTaskRunning   = agent.SubAgentTaskRunning
	SubAgentTaskCompleted = agent.SubAgentTaskCompleted
	SubAgentTaskFailed    = agent.SubAgentTaskFailed
	SubAgentTaskCancelled = agent.SubAgentTaskCancelled

	SubAgentDependencyAllSuccess  = agent.SubAgentDependencyAllSuccess
	SubAgentDependencyAllTerminal = agent.SubAgentDependencyAllTerminal
)
View Source 
const (
	DefaultRecentConversationLimit = 8
	DefaultContextMessageCharLimit = 1200
	DefaultContextSummaryCharLimit = 320

	UserMessageModeEnqueue   = "enqueue"
	UserMessageModeImmediate = "immediate"
)
View Source 
const DefaultCriticInstructions = `` /* 865-byte string literal not displayed */

DefaultCriticInstructions is the system prompt used by NewCriticVerifier when the critic agent has no instructions of its own. The critic's job is adversarial: actively try to refute the candidate answer rather than rubber-stamp it.

View Source 
const (
	DefaultMaxAutoLoops = 200
)

Variables

View Source 
var (
	BuildLLMRequestSnapshot             = agent.BuildLLMRequestSnapshot
	BuildLLMResponseSnapshot            = agent.BuildLLMResponseSnapshot
	BuildRunBudgetContext               = agent.BuildRunBudgetContext
	BuildSubAgentBudgetContext          = agent.BuildSubAgentBudgetContext
	BuildSubAgentDependencyContext      = agent.BuildSubAgentDependencyContext
	BuildSubAgentMonitorContext         = agent.BuildSubAgentMonitorContext
	BuildSubAgentResultsContext         = agent.BuildSubAgentResultsContext
	BuildWorkspaceContext               = agent.BuildWorkspaceContext
	DefaultCompactionConfig             = agent.DefaultCompactionConfig
	DefaultRetryPolicy                  = agent.DefaultRetryPolicy
	CompactionDefaultsForModel          = agent.CompactionDefaultsForModel
	ExtractAgentMeta                    = agent.ExtractAgentMeta
	ExtractAskUserQuestion              = agent.ExtractAskUserQuestion
	ExtractBashCommand                  = agent.ExtractBashCommand
	ExtractCompactionSummary            = agent.ExtractCompactionSummary
	ExtractFilePath                     = agent.ExtractFilePath
	ExtractGlobPattern                  = agent.ExtractGlobPattern
	ExtractGrepPattern                  = agent.ExtractGrepPattern
	ExtractLSPOperation                 = agent.ExtractLSPOperation
	NestedRunConfigFromContext          = agent.NestedRunConfigFromContext
	NewChildEventStream                 = agent.NewChildEventStream
	NewChildTracker                     = agent.NewChildTracker
	NewAgentLogger                      = agent.NewAgentLogger
	NewEventStream                      = agent.NewEventStream
	NewEventWriter                      = agent.NewEventStream
	NewEventHooks                       = agent.NewPlatformHooks
	NewHandoff                          = agent.NewHandoff
	NewModelStream                      = agent.NewModelStream
	NewMultiProvider                    = agent.NewMultiProvider
	NewOutputSchema                     = agent.NewOutputSchema
	NewPlatformHooks                    = agent.NewPlatformHooks
	NewProgressTracker                  = agent.NewProgressTracker
	NewRunProgress                      = agent.NewProgressTracker
	NewRunnerWithModel                  = agent.NewRunnerWithModel
	NewRunnerWithProvider               = agent.NewRunnerWithProvider
	NewSpan                             = agent.NewSpan
	NewSubAgentActivity                 = agent.NewSubAgentActivity
	NewSubAgentRegistry                 = agent.NewSubAgentRegistry
	NewTrace                            = agent.NewTrace
	NormalizeToolAccessLevel            = agent.NormalizeToolAccessLevel
	NormalizeSubAgentDependencyPolicy   = agent.NormalizeSubAgentDependencyPolicy
	NormalizeModelIdentity              = agent.NormalizeModelIdentity
	ParentCallIDFromContext             = agent.ParentCallIDFromContext
	SubAgentStreamEventFromContentEvent = agent.SubAgentStreamEventFromContentEvent
	ModeReasoningSettings               = agent.ModeReasoningSettings
	ModeRoutingSettings                 = agent.ModeRoutingSettings
	ModeTextVerbositySettings           = agent.ModeTextVerbositySettings
	MaybeCompactHandoffInput            = agent.MaybeCompactHandoffInput
	MaybeCompactRunItems                = agent.MaybeCompactRunItems
	MaybeCompactRunItemsForRequest      = agent.MaybeCompactRunItemsForRequest
	ParseModelPrefix                    = agent.ParseModelPrefix
	ResolveModelForProvider             = agent.ResolveModelForProvider
	ResolveModeRouting                  = agent.ResolveModeRouting
	ResolveRoleModeRouting              = agent.ResolveRoleModeRouting
	SnapshotRunItems                    = agent.SnapshotRunItems
	SnapshotTools                       = agent.SnapshotTools
	SpanParentIDFromContext             = agent.SpanParentIDFromContext
	TaskIDFromContext                   = agent.TaskIDFromContext
	ToolCallIDFromContext               = agent.ToolCallIDFromContext
	TraceFromContext                    = agent.TraceFromContext
	TracingProcessorFromContext         = agent.TracingProcessorFromContext
	Truncate                            = agent.Truncate
	TruncateBytes                       = agent.TruncateBytes
	TruncateMiddle                      = agent.TruncateMiddle
	WrapWithPolicy                      = agent.WrapWithPolicy
	WithDescription                     = agent.WithDescription
	WithHandoffs                        = agent.WithHandoffs
	WithInputFilter                     = agent.WithInputFilter
	WithInputType                       = agent.WithInputType
	WithOnHandoff                       = agent.WithOnHandoff
	WithIsEnabled                       = agent.WithIsEnabled
	WithAsToolName                      = agent.WithAsToolName
	WithAsToolDescription               = agent.WithAsToolDescription
	WithAsToolOutputExtractor           = agent.WithAsToolOutputExtractor
	WithRecommendedHandoffInstructions  = agent.WithRecommendedHandoffInstructions
	RemoveAllToolsHandoffInputFilter    = agent.RemoveAllToolsHandoffInputFilter
	WithInstructions                    = agent.WithInstructions
	WithMaxToolResultBytes              = agent.WithMaxToolResultBytes
	WithModel                           = agent.WithModel
	WithNestedRunConfig                 = agent.WithNestedRunConfig
	WithName                            = agent.WithName
	WithOutputType                      = agent.WithOutputType
	WithParentCallID                    = agent.WithParentCallID
	WithTaskID                          = agent.WithTaskID
	WithToolCallID                      = agent.WithToolCallID
	WithToolName                        = agent.WithToolName
	WithTools                           = agent.WithTools
	WithTraceContext                    = agent.WithTraceContext
	WithTracingProcessor                = agent.WithTracingProcessor
)

Functions

func BuildAssistantTurnSummary 

func BuildAssistantTurnSummary(items []RunItem) string

BuildAssistantTurnSummary creates a compact durable summary from one runner turn's output items.

func BuildAutoTurnCapPrompt 

func BuildAutoTurnCapPrompt(maxTurns int) string

func BuildDelegationGuide 

func BuildDelegationGuide(a *Agent, specialists map[string]*Agent) string

BuildDelegationGuide generates structured delegation instructions describing the specialist sub-agents reachable through the subagent tool and lateral handoffs available to an agent.

func BuildSmartNudge 

func BuildSmartNudge(t *AutoTracker, phase string) string

BuildSmartNudge generates a context-aware autonomous continuation prompt.

func BuildWorkingStateContext 

func BuildWorkingStateContext(state WorkingState) string

BuildWorkingStateContext formats compact, durable loop state for prompt injection.

func CompactContentEvent 

func CompactContentEvent(ev ContentEvent) string

CompactContentEvent returns a short, human-readable rendering of a content event for debug logs.

func CompactContentEventLine 

func CompactContentEventLine(line string) string

CompactContentEventLine parses and compacts a JSONL event line. Non-event lines fall back to their first line.

func ConfigureSubAgentScheduler 

func ConfigureSubAgentScheduler(s *SubAgentScheduler, cfg SubAgentSchedulerConfig)

ConfigureSubAgentScheduler refreshes host/runtime wiring for an existing scheduler while preserving already tracked async tasks.

func DefaultSignalToolNames 

func DefaultSignalToolNames() map[string]bool

DefaultSignalToolNames returns the orchestrator-only tool names stripped from specialists.

func DeriveWorkingStateGoal 

func DeriveWorkingStateGoal(rawReply, effectivePrompt string) string

DeriveWorkingStateGoal preserves the effective prompt for shorthand approval replies such as "approve" or "request changes: ...".

func ExtractAskUserChoices 

func ExtractAskUserChoices(input json.RawMessage) json.RawMessage

func ExtractPresentPlanData 

func ExtractPresentPlanData(input json.RawMessage) (string, json.RawMessage)

func MarshalQuickActions 

func MarshalQuickActions(actions ...QuickAction) json.RawMessage

func NewCriticVerifier added in v0.0.9 

func NewCriticVerifier(runner *Runner, critic *Agent, originalTask string) func(ctx context.Context, finalText string) (string, error)

NewCriticVerifier builds a RunConfig.FinalAnswerVerifier backed by a read-only critic sub-agent that attempts to refute the candidate final answer against the original task (adversarial verification). The critic runs with read-only tool access regardless of the tools on the supplied agent. If the critic approves (or fails to run), no feedback is returned and finalization proceeds.

func SummarizeTurnToolCalls 

func SummarizeTurnToolCalls(items []RunItem, limit int) []string

SummarizeTurnToolCalls counts tool calls in one runner turn.

func TruncateContextText 

func TruncateContextText(s string, max int) string

TruncateContextText normalizes whitespace and trims context snippets.

Types

type Agent 

type Agent = agent.Agent

func BuildSpecialistsFromCatalog 

func BuildSpecialistsFromCatalog(catalog RoleCatalog) []*Agent

BuildSpecialistsFromCatalog builds Agent values from SDK-native role specs.

type AgentError 

type AgentError = agent.AgentError

type AgentHooks 

type AgentHooks = agent.AgentHooks

type AgentLogger 

type AgentLogger = agent.AgentLogger

type AgentMeta 

type AgentMeta = agent.AgentMeta

type AgentOption 

type AgentOption = agent.AgentOption

type AgentSpanData 

type AgentSpanData = agent.AgentSpanData

type ApprovalGate 

type ApprovalGate interface {
	ApproveTool(ctx context.Context, request ToolApprovalRequest) (bool, string, error)
}

ApprovalGate asks the host whether a tool or MCP break-glass request is allowed.

type AsToolOption 

type AsToolOption = agent.AsToolOption

type AutoTracker 

type AutoTracker struct {
	// contains filtered or unexported fields
}

AutoTracker tracks autonomous-loop progress for smart continuation and circuit breakers.

func (*AutoTracker) CheckCircuitBreakers 

func (t *AutoTracker) CheckCircuitBreakers() CircuitBreakerResult

CheckCircuitBreakers reports hard-stop autonomous loop conditions.

func (*AutoTracker) ConsecutiveNoToolTurns 

func (t *AutoTracker) ConsecutiveNoToolTurns() int

func (*AutoTracker) ToolCallCount 

func (t *AutoTracker) ToolCallCount() int

func (*AutoTracker) Update 

func (t *AutoTracker) Update(newItems []RunItem)

Update analyzes the latest runner result items and updates tracker state.

type ChatLoop 

type ChatLoop struct {
	// contains filtered or unexported fields
}

ChatLoop is the SDK-owned high-level orchestration primitive.

func NewChatLoop 

func NewChatLoop(opts ChatLoopOptions) *ChatLoop

func (*ChatLoop) Run 

func (l *ChatLoop) Run(ctx context.Context) (*RunResult, error)

Run executes a host-backed chat loop.

The loop can resume after SDK tool approvals. Hosts still own their platform side effects through SessionStore, ConfigSource, ApprovalGate, RunStatusSink, TraceStore, and PlatformToolFactory.

type ChatLoopOptions 

type ChatLoopOptions struct {
	Runner              *Runner
	Agent               *Agent
	SessionStore        SessionStore
	RunStatusSink       RunStatusSink
	ConfigSource        ConfigSource
	TraceStore          TraceStore
	ApprovalGate        ApprovalGate
	PlatformToolFactory PlatformToolFactory
	RunConfig           RunConfig
	Cursor              Cursor
	MessageLimit        int
	MaxResumes          int
}

ChatLoopOptions configures a ChatLoop.

type ChildToolEvent 

type ChildToolEvent struct {
	ParentCallID string
	CallID       string
	AgentName    string
	Tool         string
	Phase        string
	InputRaw     string
	Output       string
	IsError      bool
	DurationMS   int64
}

ChildToolEvent is the typed SDK view of a child/sub-agent tool event emitted through the session event stream.

func ChildToolEventFromContentEvent 

func ChildToolEventFromContentEvent(ev ContentEvent) (*ChildToolEvent, bool)

ChildToolEventFromContentEvent extracts child tool start/end data from a session event. The event is considered a child tool event when it carries a parent call id.

type CircuitBreakerResult 

type CircuitBreakerResult struct {
	Tripped bool
	Reason  string
}

CircuitBreakerResult reports whether an autonomous loop should pause.

type CompactionConfig 

type CompactionConfig = agent.CompactionConfig

type CompactionData 

type CompactionData = agent.CompactionData

type CompactionModelResolver added in v0.0.24 

type CompactionModelResolver = agent.CompactionModelResolver

type CompactionResult 

type CompactionResult = agent.CompactionResult

type CompactionSpanData 

type CompactionSpanData = agent.CompactionSpanData

type CompositeHooks 

type CompositeHooks struct {
	// contains filtered or unexported fields
}

CompositeHooks fans out RunHooks calls to multiple implementations. This allows hosts to observe lifecycle events with several independent sinks.

func NewCompositeHooks 

func NewCompositeHooks(hooks ...RunHooks) *CompositeHooks

NewCompositeHooks creates a CompositeHooks that delegates to all provided hooks.

func (*CompositeHooks) OnAgentEnd 

func (c *CompositeHooks) OnAgentEnd(ctx *RunContext, a *Agent, output any)

func (*CompositeHooks) OnAgentStart 

func (c *CompositeHooks) OnAgentStart(ctx *RunContext, a *Agent)

func (*CompositeHooks) OnHandoff 

func (c *CompositeHooks) OnHandoff(ctx *RunContext, from *Agent, to *Agent)

func (*CompositeHooks) OnLLMEnd 

func (c *CompositeHooks) OnLLMEnd(ctx *RunContext, a *Agent, response *ModelResponse)

func (*CompositeHooks) OnLLMStart 

func (c *CompositeHooks) OnLLMStart(ctx *RunContext, a *Agent)

func (*CompositeHooks) OnToolEnd 

func (c *CompositeHooks) OnToolEnd(ctx *RunContext, a *Agent, tool Tool, call ToolCallData, result ToolResult)

func (*CompositeHooks) OnToolStart 

func (c *CompositeHooks) OnToolStart(ctx *RunContext, a *Agent, tool Tool, call ToolCallData)

func (*CompositeHooks) Unwrap added in v0.0.38 

func (c *CompositeHooks) Unwrap() []RunHooks

Unwrap exposes the wrapped hooks so runner internals that look for a specific hook implementation (e.g. PlatformHooks for llm_attempt event emission) can find it inside a composite.

type ConfigSource 

type ConfigSource interface {
	PermissionMode(ctx context.Context) (PermissionMode, error)
	ModeSnapshot(ctx context.Context) (*sdkmode.TemplateSpec, error)
	GuardrailRules(ctx context.Context) ([]GuardrailRule, error)
	RoleCatalog(ctx context.Context) (RoleCatalog, error)
	ModeDirective(ctx context.Context) (string, error)
	HandoffHistory(ctx context.Context) ([]RunItem, error)
}

ConfigSource supplies dynamic host configuration without leaking platform types.

type ContentEvent 

type ContentEvent = agent.ContentEvent

func ParseContentEventLine 

func ParseContentEventLine(line string) (ContentEvent, bool)

ParseContentEventLine parses one JSONL content-event line.

type ContextCompactor 

type ContextCompactor = agent.ContextCompactor

type ConversationMessage 

type ConversationMessage struct {
	ID      int64
	Role    string
	Content string
	Images  []ImageAttachment
}

ConversationMessage is the SDK-native message shape used by loop context builders. Hosts can map their durable message rows into this type.

type Cursor 

type Cursor struct {
	MessageID int64  `json:"message_id,omitempty"`
	Token     string `json:"token,omitempty"`
}

Cursor identifies the host's current position in a session stream.

type EventStream 

type EventStream = agent.EventStream

func NewSessionEventStream 

func NewSessionEventStream(w io.Writer, opts SessionEventStreamOptions) *EventStream

NewSessionEventStream creates an EventStream with common session metadata already wired and optionally emits system_init.

type EventWriter 

type EventWriter = agent.EventStream

type FunctionSpanData 

type FunctionSpanData = agent.FunctionSpanData

type FunctionTool 

type FunctionTool = agent.FunctionTool

type GenerationSpanData 

type GenerationSpanData = agent.GenerationSpanData

type GuardrailResult 

type GuardrailResult = agent.GuardrailResult

type GuardrailRule 

type GuardrailRule struct {
	Name        string
	Type        string
	Regex       string
	ToolPattern string
	Action      string
	Message     string
}

GuardrailRule is the SDK-native representation of a tool guardrail rule. Host adapters can map CRDs, config files, or database rows into this shape.

type GuardrailSpanData 

type GuardrailSpanData = agent.GuardrailSpanData

type Handoff 

type Handoff = agent.Handoff

type HandoffCallData 

type HandoffCallData = agent.HandoffCallData

type HandoffHistoryConfig 

type HandoffHistoryConfig = agent.HandoffHistoryConfig

type HandoffOption 

type HandoffOption = agent.HandoffOption

type HandoffOutputData 

type HandoffOutputData = agent.HandoffOutputData

type HandoffSpanData 

type HandoffSpanData = agent.HandoffSpanData

type ImageAttachment 

type ImageAttachment = agent.ImageAttachment

type ImmediateInputPoller 

type ImmediateInputPoller = agent.ImmediateInputPoller

type InputGuardrail 

type InputGuardrail = agent.InputGuardrail

type InputGuardrailResult 

type InputGuardrailResult = agent.InputGuardrailResult

type InputGuardrailTripwireTriggered 

type InputGuardrailTripwireTriggered = agent.InputGuardrailTripwireTriggered

type Interruption 

type Interruption = agent.Interruption

type LLMCompaction 

type LLMCompaction = agent.LLMCompaction

type LLMOutputSchema 

type LLMOutputSchema = agent.LLMOutputSchema

type LLMReasoning 

type LLMReasoning = agent.LLMReasoning

type LLMRequestSnapshot 

type LLMRequestSnapshot = agent.LLMRequestSnapshot

type LLMResponseSnapshot 

type LLMResponseSnapshot = agent.LLMResponseSnapshot

type LLMRunItemSnapshot 

type LLMRunItemSnapshot = agent.LLMRunItemSnapshot

type LLMToolApproval 

type LLMToolApproval = agent.LLMToolApproval

type LLMToolCall 

type LLMToolCall = agent.LLMToolCall

type LLMToolSnapshot 

type LLMToolSnapshot = agent.LLMToolSnapshot

type LogLevel 

type LogLevel = agent.LogLevel

type MCPServerConfig 

type MCPServerConfig struct {
	Type    string            `json:"type,omitempty"`
	Command string            `json:"command,omitempty"`
	Args    []string          `json:"args,omitempty"`
	Env     map[string]string `json:"env,omitempty"`
}

MCPServerConfig is the SDK-native shape for one MCP server entry.

type MaxTurnsExceeded 

type MaxTurnsExceeded = agent.MaxTurnsExceeded

type MessageOutput 

type MessageOutput = agent.MessageOutput

type ModeModelRouting 

type ModeModelRouting = agent.ModeModelRouting

func ModeRoutingFromTemplateSpec 

func ModeRoutingFromTemplateSpec(spec *sdkmode.TemplateSpec) *ModeModelRouting

ModeRoutingFromTemplateSpec converts SDK mode routing config into runner routing config.

type ModeReasoningLevel 

type ModeReasoningLevel = agent.ModeReasoningLevel

type ModeRoleModelRouting 

type ModeRoleModelRouting = agent.ModeRoleModelRouting

type ModeRoutingResolution 

type ModeRoutingResolution = agent.ModeRoutingResolution

type ModeTextVerbosity 

type ModeTextVerbosity = agent.ModeTextVerbosity

type Model 

type Model = agent.Model

type ModelBehaviorError 

type ModelBehaviorError = agent.ModelBehaviorError

type ModelIdentity 

type ModelIdentity = agent.ModelIdentity

type ModelProvider 

type ModelProvider = agent.ModelProvider

type ModelRequest 

type ModelRequest = agent.ModelRequest

type ModelResponse 

type ModelResponse = agent.ModelResponse

type ModelRetryAdvice 

type ModelRetryAdvice = agent.ModelRetryAdvice

type ModelSettings 

type ModelSettings = agent.ModelSettings

type ModelStream 

type ModelStream = agent.ModelStream

type ModelStreamEvent 

type ModelStreamEvent = agent.ModelStreamEvent

type ModelStreamEventType 

type ModelStreamEventType = agent.ModelStreamEventType

type ModelUsageEntry 

type ModelUsageEntry = agent.ModelUsageEntry

type MultiProvider 

type MultiProvider = agent.MultiProvider

type MultiTracingProcessor 

type MultiTracingProcessor = agent.MultiTracingProcessor

type NestedRunConfig 

type NestedRunConfig = agent.NestedRunConfig

type NoOpAgentHooks 

type NoOpAgentHooks = agent.NoOpAgentHooks

type NoOpRunHooks 

type NoOpRunHooks = agent.NoOpRunHooks

type NoOpTracingProcessor 

type NoOpTracingProcessor = agent.NoOpTracingProcessor

type OutputGuardrail 

type OutputGuardrail = agent.OutputGuardrail

type OutputGuardrailResult 

type OutputGuardrailResult = agent.OutputGuardrailResult

type OutputGuardrailTripwireTriggered 

type OutputGuardrailTripwireTriggered = agent.OutputGuardrailTripwireTriggered

type OutputSchema 

type OutputSchema = agent.OutputSchema

type PermissionMode 

type PermissionMode string

PermissionMode is the host-level permission mode understood by ChatLoop. 

const (
	PermissionModeReadOnly         PermissionMode = "read-only"
	PermissionModeWorkspaceWrite   PermissionMode = "workspace-write"
	PermissionModeDangerFullAccess PermissionMode = "danger-full-access"
)

type PlatformHooks 

type PlatformHooks = agent.PlatformHooks

type PlatformToolFactory 

type PlatformToolFactory interface {
	BuildTools(ctx context.Context, base []Tool) ([]Tool, error)
}

PlatformToolFactory injects host/platform-specific tools into the SDK runner.

type ProgressEvent 

type ProgressEvent = agent.ProgressEvent

type ProgressSnapshot 

type ProgressSnapshot = agent.ProgressSnapshot

type ProgressTracker 

type ProgressTracker = agent.ProgressTracker

type QuickAction 

type QuickAction struct {
	ID    string `json:"id"`
	Label string `json:"label"`
	Mode  string `json:"mode,omitempty"`
	Style string `json:"style,omitempty"`
}

type ReasoningData 

type ReasoningData = agent.ReasoningData

type RetryBackoffSettings 

type RetryBackoffSettings = agent.RetryBackoffSettings

type RetryPolicy 

type RetryPolicy = agent.RetryPolicy

type RetrySpanData 

type RetrySpanData = agent.RetrySpanData

type RoleCatalog 

type RoleCatalog []RoleSpec

type RoleSpec 

type RoleSpec struct {
	Name           string
	Description    string
	Instructions   string
	ToolAccess     string
	ModelOverride  string
	FallbackModels []string
}

RoleSpec is the SDK-native shape for a specialist role.

type RunConfig 

type RunConfig = agent.RunConfig

type RunContext 

type RunContext = agent.RunContext

type RunErrorAction 

type RunErrorAction = agent.RunErrorAction

type RunErrorData 

type RunErrorData = agent.RunErrorData

type RunErrorDetails 

type RunErrorDetails = agent.RunErrorDetails

type RunErrorHandler 

type RunErrorHandler = agent.RunErrorHandler

type RunErrorHandlerResult 

type RunErrorHandlerResult = agent.RunErrorHandlerResult

type RunHooks 

type RunHooks = agent.RunHooks

type RunItem 

type RunItem = agent.RunItem

func BuildConversationTail 

func BuildConversationTail(messages []ConversationMessage, state WorkingState, excludeMessageID int64, limit int) []RunItem

BuildConversationTail selects recent durable conversation context while respecting a history floor and excluding the current user message.

func CollectImmediateRunItems 

func CollectImmediateRunItems(messages []UserMessage, consumedImmediate map[int64]struct{}) ([]RunItem, int64)

CollectImmediateRunItems converts unconsumed immediate user messages to run items and marks them consumed.

type RunItemType 

type RunItemType = agent.RunItemType

type RunProgress 

type RunProgress = agent.ProgressTracker

type RunResult 

type RunResult = agent.RunResult

type RunState 

type RunState = agent.RunState

type RunStatusSink 

type RunStatusSink interface {
	PublishProgress(ctx context.Context, snapshot ProgressSnapshot) error
	PublishTraceID(ctx context.Context, traceID string) error
	PublishFinalResult(ctx context.Context, result *RunResult) error
}

RunStatusSink publishes loop progress to the host platform.

type Runner 

type Runner = agent.Runner

type SessionEventStreamOptions 

type SessionEventStreamOptions struct {
	Logger       *AgentLogger
	EnableLogger bool
	LogLevel     LogLevel
	Session      int32
	Phase        string

	SystemInit *SessionSystemInit
}

SessionEventStreamOptions configures NewSessionEventStream.

type SessionSpanData 

type SessionSpanData = agent.SessionSpanData

type SessionStore 

type SessionStore interface {
	LoadMessages(ctx context.Context, cursor Cursor, limit int) ([]UserMessage, Cursor, error)
	AppendRunItems(ctx context.Context, items []RunItem) error
	WorkingState(ctx context.Context) (WorkingState, error)
}

SessionStore loads user inputs and persists new run items.

type SessionSystemInit 

type SessionSystemInit struct {
	Model          string
	PermissionMode string
	Cwd            string
	MaxTurns       int
	Tools          []string
	MCPServers     []string
}

type Span 

type Span = agent.Span

type SpanData 

type SpanData = agent.SpanData

type SpecialistBuildOptions 

type SpecialistBuildOptions struct {
	Runner            *Runner
	Tools             []Tool
	BaseModel         string
	FallbackModels    []string
	Provider          string
	BaseModelSettings ModelSettings
	ModeSnapshot      *sdkmode.TemplateSpec

	// OutputExtractor, when set, post-processes each specialist sub-agent's
	// RunResult before its text is returned to the parent agent.
	OutputExtractor func(*RunResult) string
}

SpecialistBuildOptions controls conversion from role specs to runnable sub-agent tools.

type SpecialistBuildResult 

type SpecialistBuildResult struct {
	Tools  []Tool
	Agents map[string]*Agent
}

SpecialistBuildResult holds both sub-agent tools and the raw agents.

func BuildSpecialistToolsFromCatalog 

func BuildSpecialistToolsFromCatalog(catalog RoleCatalog, opts SpecialistBuildOptions) SpecialistBuildResult

BuildSpecialistToolsFromCatalog builds sub-agent tools from SDK-native role specs, applying tool access, signal stripping, and mode model routing.

type StopAtTools 

type StopAtTools = agent.StopAtTools

type StreamEvent 

type StreamEvent = agent.StreamEvent

type StreamEventType 

type StreamEventType = agent.StreamEventType

type StreamedRunResult 

type StreamedRunResult = agent.StreamedRunResult

type SubAgentActivity 

type SubAgentActivity = agent.SubAgentActivity

type SubAgentActivityEntry 

type SubAgentActivityEntry = agent.SubAgentActivityEntry

type SubAgentActivityLedger 

type SubAgentActivityLedger = agent.SubAgentActivity

type SubAgentActivitySnapshot 

type SubAgentActivitySnapshot = agent.SubAgentActivitySnapshot

type SubAgentDependencyPolicy 

type SubAgentDependencyPolicy = agent.SubAgentDependencyPolicy

type SubAgentRegistry 

type SubAgentRegistry = agent.SubAgentRegistry

type SubAgentRegistryConfig 

type SubAgentRegistryConfig = agent.SubAgentRegistryConfig

type SubAgentScheduler 

type SubAgentScheduler = agent.SubAgentRegistry

func NewSubAgentScheduler 

func NewSubAgentScheduler(cfg SubAgentSchedulerConfig) *SubAgentScheduler

NewSubAgentScheduler creates a scheduler for async sub-agent tasks.

type SubAgentSchedulerConfig 

type SubAgentSchedulerConfig struct {
	MaxConcurrent           int
	Runner                  *Runner
	Agents                  map[string]*Agent
	Tracker                 *RunProgress
	EventStream             *EventStream
	EventWriter             *EventStream
	WorkDir                 string
	ToolAccessLevel         ToolAccessLevel
	ToolPolicy              *ToolPolicy
	CompactionConfig        CompactionConfig
	CompactionModelResolver CompactionModelResolver
	MaxTurns                int
}

SubAgentSchedulerConfig configures the SDK async sub-agent scheduler.

type SubAgentSpawnOptions 

type SubAgentSpawnOptions = agent.SubAgentSpawnOptions

type SubAgentStreamEvent 

type SubAgentStreamEvent = agent.SubAgentStreamEvent

type SubAgentTask 

type SubAgentTask = agent.SubAgentTask

type SubAgentTaskStatus 

type SubAgentTaskStatus = agent.SubAgentTaskStatus

type SubagentSpanData 

type SubagentSpanData = agent.SubagentSpanData

type Tool 

type Tool = agent.Tool

func BuildSubAgentTaskTools 

func BuildSubAgentTaskTools(reg *SubAgentScheduler, defaultAgent string) []Tool

BuildSubAgentTaskTools returns the model-facing sub-agent tool surface:

  • subagent: spawn one task or a keyed DAG of tasks, sync or background
  • subagent_status: progress, activity, and dependency-graph introspection
  • subagent_wait: block until background tasks finish (no sleep-polling)
  • subagent_control: steer (message) or cancel a running task

All spawned tasks are managed by the scheduler: results are injected into the parent as soon as each task finishes, and the runner blocks final answers while tasks are still active.

func FilterToolsByAccess 

func FilterToolsByAccess(allTools []Tool, accessLevel string) []Tool

FilterToolsByAccess returns the subset of tools matching the given access level. Tools that implement ToolAccessAdapter may substitute a safer implementation for read-only access before filtering.

func StripNamedSignalTools 

func StripNamedSignalTools(tools []Tool, signalToolNames map[string]bool) []Tool

func StripSignalTools 

func StripSignalTools(tools []Tool) []Tool

StripSignalTools removes orchestrator-only signal tools from a tool list.

type ToolAccessAdapter 

type ToolAccessAdapter = agent.ToolAccessAdapter

type ToolAccessLevel 

type ToolAccessLevel = agent.ToolAccessLevel

func ToolAccessLevelFromRole 

func ToolAccessLevelFromRole(value string) ToolAccessLevel

ToolAccessLevelFromRole normalizes role/catalog tool access strings.

type ToolApprovalData 

type ToolApprovalData = agent.ToolApprovalData

type ToolApprovalRequest 

type ToolApprovalRequest struct {
	ToolName string
	Input    []byte
	Reason   string
}

ToolApprovalRequest is a host-native approval question.

type ToolCallData 

type ToolCallData = agent.ToolCallData

type ToolGuardrailResult 

type ToolGuardrailResult = agent.ToolGuardrailResult

type ToolInputGuardrail 

type ToolInputGuardrail = agent.ToolInputGuardrail

type ToolInputGuardrailTripwireTriggered 

type ToolInputGuardrailTripwireTriggered = agent.ToolInputGuardrailTripwireTriggered

type ToolOutputData 

type ToolOutputData = agent.ToolOutputData

type ToolOutputGuardrail 

type ToolOutputGuardrail = agent.ToolOutputGuardrail

type ToolOutputGuardrailTripwireTriggered 

type ToolOutputGuardrailTripwireTriggered = agent.ToolOutputGuardrailTripwireTriggered

type ToolPolicy 

type ToolPolicy = agent.ToolPolicy

type ToolResult 

type ToolResult = agent.ToolResult

type ToolTimeoutError 

type ToolTimeoutError = agent.ToolTimeoutError

type ToolUseBehavior 

type ToolUseBehavior = agent.ToolUseBehavior

type ToolsToFinalOutputResult 

type ToolsToFinalOutputResult = agent.ToolsToFinalOutputResult

type Trace 

type Trace = agent.Trace

type TraceStore 

type TraceStore interface {
	RunDir(ctx context.Context) (string, error)
	AppendCategory(ctx context.Context, category, text string) error
	WriteFile(ctx context.Context, name string, data []byte) error
	Finalize(ctx context.Context, result *RunResult) error
}

TraceStore is the trace persistence surface consumed by ChatLoop.

type TracingProcessor 

type TracingProcessor = agent.TracingProcessor

type TrackerOption 

type TrackerOption = agent.TrackerOption

type Usage 

type Usage = agent.Usage

type UsageCacheSemantics added in v0.0.62 

type UsageCacheSemantics = agent.UsageCacheSemantics

type UserError 

type UserError = agent.UserError

type UserInputPause 

type UserInputPause struct {
	Requested bool
	Question  string
	Actions   json.RawMessage
}

func DetectUserInputPause 

func DetectUserInputPause(items []RunItem, finalText string) UserInputPause

type UserMessage 

type UserMessage struct {
	ID        int64
	Content   string
	Mode      string
	CreatedAt time.Time
	Images    []ImageAttachment
}

UserMessage is an SDK-native user input loaded from a host session store.

func SelectNextUserMessage 

func SelectNextUserMessage(messages []UserMessage, consumedImmediate map[int64]struct{}) (UserMessage, bool, int64, bool)

SelectNextUserMessage picks the next message to handle, prioritizing unconsumed immediate messages while preserving queued messages.

type WorkingState 

type WorkingState struct {
	Goal                  string
	CurrentMode           string
	CurrentStep           string
	LastUserMessage       string
	LastAssistantSummary  string
	RecentTurnSummaries   []string
	HistoryFloorMessageID int64
	LastResponseID        string
	Data                  map[string]any
}

WorkingState is durable host-maintained context injected into the loop.

Source Files

View all Source files

Directories

Path Synopsis
Package host exposes the SDK host-boundary interfaces used by ChatLoop.
 Package host exposes the SDK host-boundary interfaces used by ChatLoop.
fileconfig
Package fileconfig provides file-backed SDK host configuration.
 Package fileconfig provides file-backed SDK host configuration.
Package mode defines the SDK-native mode template shape.
 Package mode defines the SDK-native mode template shape.
Package modelsdev resolves per-model context-window limits from the models.dev open catalog (https://models.dev/api.json).
 Package modelsdev resolves per-model context-window limits from the models.dev open catalog (https://models.dev/api.json).
Package projectstate implements durable, event-sourced project state for agents: typed tasks, typed long-term memories, session summaries, and a prime-context builder.
 Package projectstate implements durable, event-sourced project state for agents: typed tasks, typed long-term memories, session summaries, and a prime-context builder.
Package providers contains SDK provider wiring for common model backends.
 Package providers contains SDK provider wiring for common model backends.
anthropic
Package anthropic exposes the Anthropic provider and client helpers as part of the public agent SDK surface.
 Package anthropic exposes the Anthropic provider and client helpers as part of the public agent SDK surface.
oauth
Package oauth exposes provider OAuth material parsing and refresh helpers.
 Package oauth exposes provider OAuth material parsing and refresh helpers.
openai
Package openai exposes the OpenAI-compatible provider, client, and auth helpers as part of the public agent SDK surface.
 Package openai exposes the OpenAI-compatible provider, client, and auth helpers as part of the public agent SDK surface.
browser
fs
git
internal/pathutil
lsp
memory
projectstate
search
shell
signal
skills
vision
web

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.