agentcore

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

type AgentContext struct {
	SystemPrompt string        // single-string system prompt (legacy)
	SystemBlocks []SystemBlock // multi-block system prompt with cache control (takes precedence)
	Messages     []AgentMessage
	Tools        []Tool
}

type AgentMessage interface {
	GetRole() Role
	GetTimestamp() time.Time
	TextContent() string
	ThinkingContent() string
	HasToolCalls() bool
}

type AgentOption func(*Agent)

type AgentState struct {
	SystemPrompt     string
	Messages         []AgentMessage
	Tools            []Tool
	IsRunning        bool
	StreamMessage    AgentMessage        // partial message being streamed, nil when idle
	PendingToolCalls map[string]struct{} // tool call IDs currently executing
	TotalUsage       Usage               // cumulative token usage across all turns
	Error            string
}

type BackgroundTask struct {
	ID          string
	Agent       string // agent config name
	Description string
	Prompt      string // original task prompt
	Status      string // "running" | "completed" | "failed"
	StartedAt   time.Time
	EndedAt     time.Time
	OutputFile  string // path to output file on disk
	Error       string
	Progress    []string // tool call history: "Tool(args...)"
	TokensIn    int
	TokensOut   int
	ToolCount   int
	// contains filtered or unexported fields
}

type CallConfig struct {
	ThinkingLevel  ThinkingLevel
	ThinkingBudget int    // max thinking tokens, 0 = use provider default
	APIKey         string // per-call API key override, empty = use model default
	SessionID      string // provider session caching identifier
	MaxTokens      int    // per-call max tokens override, 0 = use model default
}

type CallOption func(*CallConfig)

type ChatModel interface {
	Generate(ctx context.Context, messages []Message, tools []ToolSpec, opts ...CallOption) (*LLMResponse, error)
	GenerateStream(ctx context.Context, messages []Message, tools []ToolSpec, opts ...CallOption) (<-chan StreamEvent, error)
	SupportsTools() bool
}

type ContentBlock struct {
	Type     ContentType `json:"type"`
	Text     string      `json:"text,omitempty"`
	Thinking string      `json:"thinking,omitempty"`
	ToolCall *ToolCall   `json:"tool_call,omitempty"`
	Image    *ImageData  `json:"image,omitempty"`
	ToolName string      `json:"tool_name,omitempty"` // tool_reference: referenced tool name
}

type ContentTool interface {
	ExecuteContent(ctx context.Context, args json.RawMessage) ([]ContentBlock, error)
}

type ContentType string

type ContextEstimateFn func(msgs []AgentMessage) (tokens, usageTokens, trailingTokens int)

type ContextUsage struct {
	Tokens         int     `json:"tokens"`          // estimated total tokens in context
	ContextWindow  int     `json:"context_window"`  // model's context window size
	Percent        float64 `json:"percent"`         // tokens / contextWindow * 100
	UsageTokens    int     `json:"usage_tokens"`    // from last LLM-reported Usage
	TrailingTokens int     `json:"trailing_tokens"` // chars/4 estimate for trailing messages
}

type Cost struct {
	Input      float64 `json:"input"`
	Output     float64 `json:"output"`
	CacheRead  float64 `json:"cache_read"`
	CacheWrite float64 `json:"cache_write"`
	Total      float64 `json:"total"`
}

type DeferActivator interface {
	DeferFilter
	Activate(names ...string)
}

type DeferFilter interface {
	// IsDeferred reports whether the tool is deferred and not yet activated.
	// Unactivated deferred tools are excluded from the API request entirely.
	IsDeferred(toolName string) bool
	// WasDeferred reports whether the tool was originally in the deferred set
	// (regardless of activation). Activated deferred tools are sent with
	// defer_loading: true.
	WasDeferred(toolName string) bool
}

type EndReason string

type Event struct {
	Type             EventType
	Message          AgentMessage    // for message_start/update/end, turn_end
	Delta            string          // text delta for message_update
	ToolID           string          // for tool_exec_*
	Tool             string          // tool name for tool_exec_*
	ToolLabel        string          // human-readable tool label (from ToolLabeler)
	Args             json.RawMessage // tool args for tool_exec_start/tool_exec_update
	Result           json.RawMessage // tool result for tool_exec_end and preview updates
	Progress         *ProgressPayload
	UpdateKind       ToolExecUpdateKind
	IsError          bool // tool error flag for tool_exec_end
	ApprovalDecision ToolApprovalDecision
	ApprovalReason   string
	Preview          json.RawMessage
	ToolResults      []ToolResult   // for turn_end: all tool results from this turn
	Err              error          // for error events
	NewMessages      []AgentMessage // for agent_end: messages added during this loop
	RetryInfo        *RetryInfo     // for retry events
	Summary          *RunSummary    // for agent_end: factual run summary
}

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

type EventType string

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

type ImageData struct {
	Data     string `json:"data,omitempty"`
	URL      string `json:"url,omitempty"`
	MimeType string `json:"mime_type,omitempty"`
}

type InjectDisposition string

type InjectResult struct {
	Disposition InjectDisposition
}

type LLMRequest struct {
	Messages []Message
	Tools    []ToolSpec
}

type LLMResponse struct {
	Message Message
}

type LoopConfig struct {
	Model         ChatModel
	StreamFn      StreamFn      // nil = use Model directly
	MaxTurns      int           // safety limit, default 10
	MaxRetries    int           // LLM call retry limit for retryable errors, default 3
	MaxToolErrors int           // consecutive tool failure threshold per tool, 0 = unlimited
	ThinkingLevel ThinkingLevel // reasoning depth

	// Two-stage pipeline: TransformContext -> ConvertToLLM
	TransformContext func(ctx context.Context, msgs []AgentMessage) ([]AgentMessage, error)
	ConvertToLLM     func(msgs []AgentMessage) []Message

	// CheckToolApproval is called after validation/preview and before execution.
	// Returning nil means no approval was required.
	// Returning a non-nil result applies the approval decision immediately.
	CheckToolApproval ToolApprovalFunc

	// GetApiKey resolves the API key before each LLM call.
	// The provider parameter identifies which provider is being called (e.g. "openai", "anthropic").
	// Enables per-provider key resolution, key rotation, OAuth tokens, and multi-tenant scenarios.
	// When nil or returns empty string, the model's default key is used.
	GetApiKey func(provider string) (string, error)

	// ThinkingBudgets maps each ThinkingLevel to a max thinking token count.
	// When set, the resolved budget is passed to the model alongside the level.
	ThinkingBudgets map[ThinkingLevel]int

	// SessionID enables provider-level session caching (e.g. Anthropic prompt cache).
	SessionID string

	// Steering: called after each tool execution to check for user interruptions.
	GetSteeringMessages func() []AgentMessage

	// FollowUp: called when the agent would otherwise stop.
	GetFollowUpMessages func() []AgentMessage

	// MaxRetryDelay caps the wait time between retries (including server-requested Retry-After).
	// Default: 60s. Set to prevent excessively long waits from overloaded providers.
	MaxRetryDelay time.Duration

	// Middlewares are applied around each tool execution (outermost first).
	// Use for logging, timing, argument/result modification, etc.
	Middlewares []ToolMiddleware

	// MaxToolConcurrency limits parallel tool execution.
	// 0 or 1 = sequential (default, backward compatible).
	// >1 = up to N tools execute concurrently within a single turn.
	MaxToolConcurrency int

	// ShouldEmitAbortMarker reports whether an abort marker message should be
	// emitted when the context is cancelled. When nil or returns false, the
	// cancellation is silent (legacy behavior). Set by Agent.Abort().
	ShouldEmitAbortMarker func() bool
}

type Message struct {
	Role       Role           `json:"role"`
	Content    []ContentBlock `json:"content"`
	StopReason StopReason     `json:"stop_reason,omitempty"`
	Usage      *Usage         `json:"usage,omitempty"`
	Metadata   map[string]any `json:"metadata,omitempty"`
	Timestamp  time.Time      `json:"timestamp"`
}

type Previewer interface {
	Preview(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

type ProgressPayload struct {
	Kind       ProgressPayloadKind `json:"kind"`
	Agent      string              `json:"agent,omitempty"`
	Tool       string              `json:"tool,omitempty"`
	Summary    string              `json:"summary,omitempty"`
	Delta      string              `json:"delta,omitempty"`
	Thinking   string              `json:"thinking,omitempty"`
	Message    string              `json:"message,omitempty"`
	Turn       int                 `json:"turn,omitempty"`
	Attempt    int                 `json:"attempt,omitempty"`
	MaxRetries int                 `json:"max_retries,omitempty"`
	IsError    bool                `json:"is_error,omitempty"`
	Args       json.RawMessage     `json:"args,omitempty"`
	Meta       json.RawMessage     `json:"meta,omitempty"`
}

type ProgressPayloadKind string

type ProviderNamer interface {
	ProviderName() string
}

type ProxyEvent struct {
	Type       ProxyEventType `json:"type"`
	Delta      string         `json:"delta,omitempty"`
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name,omitempty"`
	StopReason StopReason     `json:"stop_reason,omitempty"`
	Usage      *Usage         `json:"usage,omitempty"`
	Err        error          `json:"-"`
}

type ProxyEventType string

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

type ProxyStreamFn func(ctx context.Context, req *LLMRequest) (<-chan ProxyEvent, error)

type QueueMode string

type RetryInfo struct {
	Attempt    int
	MaxRetries int
	Delay      time.Duration
	Err        error
}

type Role string

type RunSummary struct {
	TurnCount  int
	ToolCalls  int
	ToolErrors int
	EndReason  EndReason
}

type StopReason string

type StreamEvent struct {
	Type         StreamEventType
	ContentIndex int        // which content block is being updated
	Delta        string     // text/thinking/toolcall argument delta
	Message      Message    // partial (during streaming) or final (done)
	StopReason   StopReason // finish reason (for done events)
	Err          error      // for error events
}

type StreamEventType string

type StreamFn func(ctx context.Context, req *LLMRequest) (*LLMResponse, error)

type SubAgentConfig struct {
	Name        string
	Description string
	// Model is resolved when each sub-agent run starts. Wrappers that swap
	// the underlying model at runtime are supported and take effect on the
	// next sub-agent run.
	Model        ChatModel
	SystemPrompt string
	Tools        []Tool
	StreamFn     StreamFn
	MaxTurns     int

	// Optional two-stage context pipeline (same as Agent-level).
	// When set, enables automatic context compaction for long-running sub-agents.
	TransformContext func(ctx context.Context, msgs []AgentMessage) ([]AgentMessage, error)
	ConvertToLLM     func(msgs []AgentMessage) []Message
}

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

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

type SystemBlock struct {
	Text         string `json:"text"`
	CacheControl string `json:"cache_control,omitempty"` // e.g. "ephemeral"
}

type ThinkingLevel string

type Tool interface {
	Name() string
	Description() string
	Schema() map[string]any
	Execute(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

type ToolApprovalDecision string

type ToolApprovalFunc func(ctx context.Context, req ToolApprovalRequest) (*ToolApprovalResult, error)

type ToolApprovalRequest struct {
	Call      ToolCall
	ToolLabel string
	Summary   string
	Reason    string
	Preview   []byte
}

type ToolApprovalResult struct {
	Approved bool
	Decision ToolApprovalDecision
	Reason   string
}

type ToolCall struct {
	ID   string          `json:"id"`
	Name string          `json:"name"`
	Args json.RawMessage `json:"args"`
}

type ToolExecUpdateKind string

type ToolExecuteFunc func(ctx context.Context, args json.RawMessage) (json.RawMessage, error)

type ToolLabeler interface {
	Label() string
}

type ToolMiddleware func(ctx context.Context, call ToolCall, next ToolExecuteFunc) (json.RawMessage, error)

type ToolProgressFunc func(progress ProgressPayload)

type ToolResult struct {
	ToolCallID    string          `json:"tool_call_id"`
	ToolName      string          `json:"-"` // internal: for toolErrors tracking
	Content       json.RawMessage `json:"content,omitempty"`
	ContentBlocks []ContentBlock  `json:"-"` // rich content (images); not serialized
	IsError       bool            `json:"is_error,omitempty"`
	Details       any             `json:"details,omitempty"` // optional metadata for UI display/logging
}

type ToolSpec struct {
	Name         string `json:"name"`
	Description  string `json:"description"`
	Parameters   any    `json:"parameters"`
	DeferLoading bool   `json:"defer_loading,omitempty"`
}

type Usage struct {
	Input       int   `json:"input"`
	Output      int   `json:"output"`
	CacheRead   int   `json:"cache_read"`
	CacheWrite  int   `json:"cache_write"`
	TotalTokens int   `json:"total_tokens"`
	Cost        *Cost `json:"cost,omitempty"`
}