Documentation
¶
Overview ¶
Package api defines the stable public contracts shared by the agentcore runtime and its first-party adapters.
Index ¶
- Constants
- Variables
- func DurationFromSeconds(seconds float64, max time.Duration) (time.Duration, bool)
- func EmptyFinalAttempt(ctx context.Context) bool
- func InjectedTurnTextFrom(ctx context.Context) string
- func PromptCacheScopeFrom(ctx context.Context) string
- func SessionIDFrom(ctx context.Context) string
- func TurnIDFrom(ctx context.Context) string
- func TurnPromptFrom(ctx context.Context) string
- func WithEmptyFinalAttempt(ctx context.Context, enabled bool) context.Context
- func WithInjectedTurnText(ctx context.Context, text string) context.Context
- func WithPromptCacheScope(ctx context.Context, scope string) context.Context
- func WithSessionID(ctx context.Context, id string) context.Context
- func WithTurnID(ctx context.Context, id string) context.Context
- func WithTurnPrompt(ctx context.Context, prompt string) context.Context
- type Artifact
- type ArtifactStorage
- type ContextBuilder
- type ContextEvent
- type Control
- type ErrorDecision
- type ErrorEvent
- type ErrorPolicy
- type FinishReason
- type GenerateRequest
- type GenerateResult
- type History
- type HistoryError
- type Hook
- type HookError
- type ImagePart
- type Message
- type ModelEvent
- type NopHook
- func (NopHook) AfterModel(context.Context, *ModelEvent, *Control) error
- func (NopHook) AfterRun(context.Context, *RunEvent, *Control) error
- func (NopHook) AfterTool(context.Context, *ToolEvent, *Control) error
- func (NopHook) BeforeContextBuild(context.Context, *ContextEvent, *Control) error
- func (NopHook) BeforeModel(context.Context, *ModelEvent, *Control) error
- func (NopHook) BeforePromptBuild(context.Context, *PromptEvent, *Control) error
- func (NopHook) BeforeRun(context.Context, *RunEvent, *Control) error
- func (NopHook) BeforeTool(context.Context, *ToolEvent, *Control) error
- func (NopHook) OnError(context.Context, *ErrorEvent, *Control) error
- type PromptBuilder
- type PromptEvent
- type Provider
- type ProviderError
- type ResumeMode
- type ResumePolicy
- type RunEvent
- type RunInput
- type RunResult
- type RunState
- type RunStatus
- type Storage
- type StorageError
- type StreamEvent
- type StreamEventKind
- type StreamFunc
- type StreamingProvider
- type Tool
- type ToolCall
- type ToolChooser
- type ToolError
- type ToolErrorDecision
- type ToolEvent
- type ToolExecutionPolicy
- type ToolRegistry
- type ToolResult
- type ToolSchema
- type Usage
- type Yield
Constants ¶
const ( EstimatedInputTokensMetaKey = "est_input_tokens" EstimatedOutputTokensMetaKey = "est_output_tokens" )
EstimatedInputTokensMetaKey and EstimatedOutputTokensMetaKey retain the estimator's two values for observers that need to show the estimate beside the normalized Usage fields.
const EmptyFinalMetaKey = "empty_final"
EmptyFinalMetaKey marks a final model result synthesized after repeated empty replies following a successful tool call. It is carried through hooks and observation.
const PromptCacheScopeCompact = "compact"
PromptCacheScopeCompact marks a compaction, summary or idle-consolidation request: system prompt plus the messages to summarize. It becomes a suffix of the prompt cache key so the summary's own prompt does not evict the conversation's cache entry turn after turn.
const ToolBatchMetaKey = "suga.tool_batch"
ToolBatchMetaKey is the Message.Metadata key (string) shared by the assistant tool-call messages of one model reply with several calls. The runtime stores each call with its result right after it; providers use the key to send such a reply back as one assistant message with all its calls followed by the results, so the history shows parallel calls as they were.
const ToolChoiceNone = "none"
ToolChoiceNone is the ToolChoice value that forbids tool calls (OpenAI "none", Anthropic/Responses {"type": "none"}).
const UsageEstimatedMetaKey = "usage_estimated"
UsageEstimatedMetaKey marks GenerateResult usage that was filled or replaced by the personal-layer estimator. The metadata travels with the result so the runtime and observation layers keep the same estimated/real distinction.
Variables ¶
var ( ErrEmptyGenerateResult = errors.New("empty result") ErrMixedGenerateResult = errors.New("content and tool calls are mutually exclusive") ErrInvalidFinishReason = errors.New("invalid finish reason for generate result payload") ErrMissingToolCallID = errors.New("missing tool call id") ErrMissingToolName = errors.New("missing tool name") ErrToolArgumentsInvalid = errors.New("invalid tool call arguments") ErrMissingFinishReason = errors.New("missing finish reason") ErrProviderRequired = errors.New("provider is required") ErrRunNotResumable = errors.New("run cannot be resumed from terminal state") ErrHistoryStateConflict = errors.New("memory state conflicts with transcript") ErrToolCallsNotImplemented = errors.New("tool call loop not implemented yet") // ErrWrapUpIgnored: the reply to a wrap-up request (Control.RequestWrapUp) // called tools instead of answering. The default runtime no longer reports // it, since such a turn ends with a wrap-up answer instead (see // DefaultRuntime.finishIgnoredWrapUp); it stays for hosts that surface the // case themselves. ErrWrapUpIgnored = errors.New("the model called tools after the wrap-up request") )
Functions ¶
func DurationFromSeconds ¶ added in v0.52.0
DurationFromSeconds converts a positive floating-point second count without first overflowing time.Duration. max is the largest permitted duration; a non-positive max means the largest representable duration.
func EmptyFinalAttempt ¶
EmptyFinalAttempt reports whether the current provider request is the candidate whose empty response may complete a run after successful tool execution.
func InjectedTurnTextFrom ¶ added in v0.56.0
InjectedTurnTextFrom returns the text set by WithInjectedTurnText, or "" for a turn the person typed.
func PromptCacheScopeFrom ¶ added in v0.52.0
PromptCacheScopeFrom returns the scope set by WithPromptCacheScope, or "".
func SessionIDFrom ¶
SessionIDFrom returns the session id set by WithSessionID, or "".
func TurnIDFrom ¶ added in v0.52.0
TurnIDFrom returns the turn id set by WithTurnID, or "".
func TurnPromptFrom ¶ added in v0.55.0
TurnPromptFrom returns the prompt set by WithTurnPrompt, or "".
func WithEmptyFinalAttempt ¶
WithEmptyFinalAttempt marks a provider request as the final empty-answer candidate.
func WithInjectedTurnText ¶ added in v0.56.0
WithInjectedTurnText marks ctx with the text of an injected turn (verify output, a task notice, a Stop hook reply, a cross-session message): it was not typed by the person, so layers that judge a call treat it as untrusted material, never as the request (see WithTurnPrompt).
func WithPromptCacheScope ¶ added in v0.52.0
WithPromptCacheScope marks ctx as a request whose prompt is not the conversation's own (a compaction or a handoff package). The providers keep such a request on its own upstream cache key.
func WithSessionID ¶
WithSessionID marks ctx with the agent session the call belongs to. A session id is a runtime concept (who is talking), not a provider one, so it lives in the contract package and the layers on top read it from here:
- llm: the value of llm.SessionIDPlaceholder ("{{session_id}}") in llm.headers and the per-conversation cache key of a request.
- tasks: the default session of a call when tasks.Config.Session is nil.
func WithTurnID ¶ added in v0.52.0
WithTurnID marks ctx with the agent turn the call belongs to. llm.headers expands it as "{{turn_id}}" (a gateway tracing one turn of a long session).
func WithTurnPrompt ¶ added in v0.55.0
WithTurnPrompt marks ctx with the user's request of the turn (for an injected turn, the latest earlier user request). Layers that judge a call against what the person asked read it with TurnPromptFrom.
Types ¶
type ArtifactStorage ¶
type ArtifactStorage interface {
SaveArtifacts(ctx context.Context, runID string, artifacts []Artifact) error
LoadArtifacts(ctx context.Context, runID string) ([]Artifact, error)
}
ArtifactStorage is an optional storage capability for artifact persistence and replay.
type ContextBuilder ¶
type ContextBuilder interface {
BuildMessages(ctx context.Context, state *RunState) ([]Message, error)
}
ContextBuilder assembles model-facing messages from the current public run state.
type ContextEvent ¶
type ContextEvent struct {
RunID string
AgentID string
State *RunState
Messages []Message
Metadata map[string]any
Timestamp time.Time
}
ContextEvent is the concrete lifecycle event for context construction.
type Control ¶
type Control struct {
ShortCircuited bool
Yielded bool
Replacement any
YieldReason string
YieldMetadata map[string]any
// WrapUpReason and WrapUpInstruction are set by RequestWrapUp.
WrapUpReason string
WrapUpInstruction string
}
Control allows hooks to short-circuit or yield a run, or ask it to wrap up.
func (*Control) RequestWrapUp ¶
RequestWrapUp asks the run to end with an answer from what it knows: the next model request carries instruction as a last user message (tools stay declared) and its reply ends the run, as at the max steps limit. reason names why ("max_tokens", "timeout"; RunResult.WrapUp reports it). Only the run's control counts (the model hooks get it; a tool hook's does not); the first request wins.
func (*Control) ShortCircuit ¶
ShortCircuit stops normal processing and supplies a replacement value.
func (*Control) ShouldShortCircuit ¶
ShouldShortCircuit reports whether a hook replaced the normal flow.
func (*Control) ShouldYield ¶
ShouldYield reports whether a hook requested a cooperative yield.
type ErrorDecision ¶
ErrorDecision describes whether a recoverable runtime error should be turned into a replacement result or remain terminal.
type ErrorEvent ¶
type ErrorEvent struct {
RunID string
AgentID string
Stage string
Err error
Metadata map[string]any
Timestamp time.Time
}
ErrorEvent is the concrete lifecycle event for surfaced runtime errors.
type ErrorPolicy ¶
type ErrorPolicy interface {
HandleRecoverable(ctx context.Context, state *RunState, event *ErrorEvent) ErrorDecision
}
ErrorPolicy controls how the runtime reacts to recoverable execution errors.
The default implementation preserves the current v0 runtime behavior: it does not override the classified error, leaving hooks or callers to decide whether to recover, yield, or fail.
type FinishReason ¶
type FinishReason string
FinishReason explains whether a model response completed the step or requested tools.
const ( FinishFinal FinishReason = "final" FinishToolCalls FinishReason = "tool_calls" )
type GenerateRequest ¶
type GenerateRequest struct {
Model string
System string
Messages []Message
Tools []ToolSchema
MaxTokens int
Temperature float32
Metadata map[string]any
// ToolChoice asks the provider how freely the model may use the declared
// tools; empty leaves the provider's default. ToolChoiceNone forbids tool
// calls, which the runtime uses when a wrap-up step keeps asking for tools.
// Only providers implementing ToolChooser honour it.
ToolChoice string
}
GenerateRequest is the portable model request contract for agentcore runtimes.
type GenerateResult ¶
type GenerateResult struct {
Content string
ToolCalls []ToolCall
FinishReason FinishReason
Usage Usage
Artifacts []Artifact
Metadata map[string]any
// Reasoning is the model's reasoning text returned with this result; the
// runtime stores it on the assistant message it persists.
Reasoning string
// Truncated is true when the reply was cut off at the output token limit of
// the request (OpenAI finish_reason "length", Claude stop_reason
// "max_tokens", a Responses result with incomplete reason
// "max_output_tokens"): the answer may be incomplete.
Truncated bool
// OutputLimit is how many output tokens the request allowed (the provider's
// own default included); 0 when neither the request nor the protocol set
// one, so the server's default applied. It names the limit in the
// truncation notice.
OutputLimit int
}
GenerateResult is the portable model response contract for agentcore runtimes.
func (*GenerateResult) Validate ¶
func (r *GenerateResult) Validate() error
Validate checks that the result is representable by the public runtime contract.
type History ¶
type History interface {
Hydrate(ctx context.Context, state *RunState) error
ObserveMessages(ctx context.Context, state *RunState, messages ...Message) error
BuildContext(ctx context.Context, state *RunState) ([]Message, error)
}
History is the optional context-engineering layer for agentcore runtimes.
Storage remains the authority for resumable run state and full transcripts. History is a derived layer that can maintain summaries, windows, retrieval indexes, or other context-oriented views over committed transcript messages.
type HistoryError ¶
type HistoryError struct {
Err error
}
HistoryError classifies memory-layer runtime failures while preserving the wrapped cause.
func (*HistoryError) Error ¶
func (e *HistoryError) Error() string
func (*HistoryError) Unwrap ¶
func (e *HistoryError) Unwrap() error
type Hook ¶
type Hook interface {
BeforeRun(ctx context.Context, event *RunEvent, ctrl *Control) error
BeforePromptBuild(ctx context.Context, event *PromptEvent, ctrl *Control) error
BeforeContextBuild(ctx context.Context, event *ContextEvent, ctrl *Control) error
BeforeModel(ctx context.Context, event *ModelEvent, ctrl *Control) error
AfterModel(ctx context.Context, event *ModelEvent, ctrl *Control) error
BeforeTool(ctx context.Context, event *ToolEvent, ctrl *Control) error
AfterTool(ctx context.Context, event *ToolEvent, ctrl *Control) error
AfterRun(ctx context.Context, event *RunEvent, ctrl *Control) error
OnError(ctx context.Context, event *ErrorEvent, ctrl *Control) error
}
Hook defines the public lifecycle extension points for agentcore.
type HookError ¶
type HookError struct {
Err error
}
HookError classifies hook lifecycle failures while preserving the wrapped cause.
type ImagePart ¶
type ImagePart struct {
MediaType string `json:",omitempty"`
Ref string `json:",omitempty"`
SHA256 string `json:",omitempty"`
Width int `json:",omitempty"`
Height int `json:",omitempty"`
Data []byte `json:"-"`
}
ImagePart is one image of a message. The bytes are never stored: Data is filled in memory by the host before a request (read back from Ref) and cleared after the image is written to disk, so a stored message carries only the reference and metadata.
Ref is the path of the stored file relative to the session directory (images/<sha256>.<ext>). SHA256 is the hex digest of the sent bytes; a read back that does not match it is treated as a missing image.
MediaType is the mime type of the sent bytes, Data (json:"-") holds those bytes for the provider call only; Width and Height are their pixel size (0 when unknown), used for the text stand-in of an omitted image and for the image token estimate.
type Message ¶
type Message struct {
Role string
Content string
ToolCall *ToolCall
ToolResult *ToolResult
Metadata map[string]any
// Reasoning is the model's reasoning text for an assistant message (e.g.
// OpenAI-compatible reasoning_content). It is persisted with the message so
// providers whose APIs require it can send it back on later requests.
Reasoning string `json:",omitempty"`
// ResultSameAsContent is a storage marker, never set in memory: the store
// writes it when it keeps ToolResult.Content once (it equals Content), and
// UnmarshalJSON restores the result and clears the flag. It is omitted from
// every encoding that does not set it.
ResultSameAsContent bool `json:",omitempty"`
// Images are the pictures of this message: pictures the user attached to a
// user message, or the images a tool result returned (view_image). It is
// omitted when empty, so a plain text message encodes exactly as before.
Images []ImagePart `json:",omitempty"`
}
Message is the public conversation unit exchanged with prompt, context, and model layers.
func (*Message) UnmarshalJSON ¶
UnmarshalJSON decodes a message and restores a tool result the store kept only once. The store writes a tool message whose ToolResult.Content equals Content once, with a top-level ResultSameAsContent marker (see internal/personal/store.EncodeMessage); the decoded message is then exactly the one that was stored, marker cleared. Messages without the marker decode as before, and Message has no MarshalJSON: the encoding that the prefix hash and the exported JSON use is unchanged.
type ModelEvent ¶
type ModelEvent struct {
RunID string
AgentID string
Request *GenerateRequest
Result *GenerateResult
Metadata map[string]any
Timestamp time.Time
}
ModelEvent is the concrete lifecycle event for model calls and responses.
type NopHook ¶
type NopHook struct{}
NopHook provides a no-op implementation for all public hook lifecycle methods.
func (NopHook) AfterModel ¶
func (NopHook) BeforeContextBuild ¶
func (NopHook) BeforeModel ¶
func (NopHook) BeforePromptBuild ¶
type PromptBuilder ¶
type PromptBuilder interface {
BuildSystemPrompt(ctx context.Context, state *RunState) (string, error)
}
PromptBuilder builds the provider system prompt from the current public run state.
type PromptEvent ¶
type PromptEvent struct {
RunID string
AgentID string
State *RunState
System string
Metadata map[string]any
Timestamp time.Time
}
PromptEvent is the concrete lifecycle event for prompt construction.
type Provider ¶
type Provider interface {
Name() string
Generate(ctx context.Context, req *GenerateRequest) (*GenerateResult, error)
}
Provider generates the next model result from a prepared request.
type ProviderError ¶
type ProviderError struct {
Err error
}
ProviderError classifies provider-layer runtime failures while preserving the wrapped cause.
func (*ProviderError) Error ¶
func (e *ProviderError) Error() string
func (*ProviderError) Unwrap ¶
func (e *ProviderError) Unwrap() error
type ResumeMode ¶
type ResumeMode string
ResumeMode describes how a runtime should source state when continuing a run.
const ( ResumeAuto ResumeMode = "auto" ResumeFromState ResumeMode = "from_state" ResumeWithInput ResumeMode = "with_input" )
type ResumePolicy ¶
type ResumePolicy interface {
AllowResume(ctx context.Context, input RunInput, state *RunState) error
ShouldAppendInstruction(input RunInput, state *RunState) bool
MergeMetadata(stateMetadata, inputMetadata map[string]any) map[string]any
}
ResumePolicy controls how a runtime continues an existing run from persisted state.
The default implementation preserves the current v0 resume semantics: terminal runs cannot be resumed, ResumeMode controls whether a new user input is appended, and input metadata overlays persisted metadata.
type RunEvent ¶
type RunEvent struct {
RunID string
AgentID string
Input *RunInput
Result *RunResult
Metadata map[string]any
Timestamp time.Time
}
RunEvent is the concrete lifecycle event for run boundaries using the public runtime model.
type RunInput ¶
type RunInput struct {
RunID string
AgentID string
Instruction string
// Images are pictures that go with the instruction (the user message of this
// run carries them); an input may be images alone, without an instruction.
Images []ImagePart
Metadata map[string]any
Stream StreamFunc
MaxSteps int
ResumeMode ResumeMode
}
RunInput captures the public input contract for a single agent run.
type RunResult ¶
type RunResult struct {
RunID string
Status RunStatus
Output string
Steps int
Usage Usage
Yield *Yield
// WrapUp is why the run ended with a wrap-up answer ("max_steps", or the
// reason a hook gave Control.RequestWrapUp); empty for a normal answer.
WrapUp string
// Truncated is true when the answer was cut off at the output token limit
// (the model's stop reason), so it may be incomplete; OutputLimit names how
// many tokens that limit allowed (0 = the provider's or server's own
// default, i.e. no limit was configured).
Truncated bool
OutputLimit int
// EmptyFinal marks a normal completion whose final model answer was empty
// after repeated empty replies following a successful tool call.
EmptyFinal bool
}
RunResult is the public outcome contract returned by a runtime execution.
type RunState ¶
type RunState struct {
RunID string
AgentID string
Status RunStatus
Step int
Messages []Message
Artifacts []Artifact
Metadata map[string]any
Scratch map[string]any
Usage Usage
LastError string
// WrappingUp tells the ContextBuilder that the step it is building for asks
// the model for a final answer instead of more work ("" = an ordinary step);
// the value is why ("max_steps" or a hook's Control.RequestWrapUp reason).
// The runtime sets it before every BuildMessages call. It is transient: it is
// never persisted and never marshalled (RunResult.WrapUp is the persisted,
// caller-facing reason a run ended with a wrap-up answer).
WrappingUp string `json:"-"`
}
RunState is the primary public runtime state contract shared across storage and builders.
type Storage ¶
type Storage interface {
LoadRun(ctx context.Context, runID string) (*RunState, error)
LoadMessages(ctx context.Context, runID string) ([]Message, error)
SaveRun(ctx context.Context, state *RunState) error
AppendMessages(ctx context.Context, runID string, msgs ...Message) error
}
Storage persists and reloads public run state snapshots.
type StorageError ¶
type StorageError struct {
Err error
}
StorageError classifies storage-layer runtime failures while preserving the wrapped cause.
func (*StorageError) Error ¶
func (e *StorageError) Error() string
func (*StorageError) Unwrap ¶
func (e *StorageError) Unwrap() error
type StreamEvent ¶
type StreamEvent struct {
Kind StreamEventKind
Delta string
Metadata map[string]any
}
StreamEvent is the minimal host-facing streaming event contract.
type StreamEventKind ¶
type StreamEventKind string
StreamEventKind identifies the public streaming event shape emitted by a provider.
const ( StreamEventTextDelta StreamEventKind = "text_delta" StreamEventMessageStop StreamEventKind = "message_stop" // StreamEventRetry announces that the request failed for a transient // reason and is retried after a wait: Delta is the reason, Metadata has // "attempt", "wait_ms" and "restart" (true when text of the failed // attempt was already emitted; the message streams again from its start). StreamEventRetry StreamEventKind = "retry" )
type StreamFunc ¶
type StreamFunc func(ctx context.Context, event StreamEvent) error
StreamFunc consumes a model streaming event.
type StreamingProvider ¶
type StreamingProvider interface {
Provider
Stream(ctx context.Context, req *GenerateRequest, emit StreamFunc) (*GenerateResult, error)
}
StreamingProvider is an optional provider capability for incremental output delivery.
type Tool ¶
type Tool interface {
Name() string
Description() string
Schema() ToolSchema
Execute(ctx context.Context, call ToolCall) (*ToolResult, error)
}
Tool exposes a concrete executable tool.
type ToolCall ¶
type ToolCall struct {
CallID string
Name string
Arguments map[string]any
// ArgumentsError is set when the provider could not decode the arguments
// the model sent (Arguments is then empty). The runtime does not run such
// a call: it answers it with an error result so the model can resend it.
ArgumentsError string
}
ToolCall is a model-requested invocation of a named tool.
type ToolChooser ¶
type ToolChooser interface {
// SupportsToolChoice reports whether requests may carry a tool_choice.
SupportsToolChoice() bool
}
ToolChooser is an optional provider capability: the provider honours GenerateRequest.ToolChoice. A provider without it is never asked for a reply with tool_choice (the runtime skips the tool-less wrap-up retry instead of risking a request the API rejects).
type ToolError ¶
type ToolError struct {
Err error
}
ToolError classifies tool execution failures while preserving the wrapped cause.
type ToolErrorDecision ¶
type ToolErrorDecision struct {
Result *ToolResult
Fail error
}
ToolErrorDecision describes how the runtime should react to a tool execution failure.
type ToolEvent ¶
type ToolEvent struct {
RunID string
AgentID string
Call *ToolCall
Result *ToolResult
Metadata map[string]any
Timestamp time.Time
}
ToolEvent is the concrete lifecycle event for tool execution.
type ToolExecutionPolicy ¶
type ToolExecutionPolicy interface {
ValidateToolCalls(ctx context.Context, state *RunState, calls []ToolCall) error
HandleToolError(ctx context.Context, state *RunState, call ToolCall, err error) ToolErrorDecision
}
ToolExecutionPolicy controls validation and error handling around tool execution.
The default implementation preserves the current v0 runtime behavior: tool-call batches can be limited per step, and tool execution failures are converted into tool-result transcript messages so the run can continue.
type ToolRegistry ¶
type ToolRegistry interface {
ListTools(ctx context.Context) ([]ToolSchema, error)
ExecuteTool(ctx context.Context, call ToolCall) (*ToolResult, error)
}
ToolRegistry exposes lookup and execution contracts for tools.
type ToolResult ¶
type ToolResult struct {
CallID string
Name string
Content string
Artifacts []Artifact
// IsError marks a failed or refused tool call; providers forward it to
// the model (e.g. Claude tool_result is_error).
IsError bool
Metadata map[string]any
// Images are the pictures this result returns (e.g. view_image); providers
// that cannot carry them in a tool result send them in a following user
// message (see the llm package).
Images []ImagePart `json:",omitempty"`
}
ToolResult is the public result returned after executing a tool call.
type ToolSchema ¶
ToolSchema describes a callable tool in a provider-neutral way.
type Usage ¶
type Usage struct {
InputTokens int `json:"input_tokens"`
OutputTokens int `json:"output_tokens"`
TotalTokens int `json:"total_tokens"`
CacheReadTokens int `json:"cache_read_tokens,omitempty"`
CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
CostUSD float64 `json:"cost_usd,omitempty"`
}
Usage tracks model token consumption.