Documentation
¶
Overview ¶
Package agentcore provides a minimal but extensible agent runtime core.
The package is intentionally small in scope. It focuses on the execution path that every agent needs:
- prepare or resume run state
- build prompt and context
- call a model provider
- execute requested tools
- persist transcript and run state
- surface lifecycle hooks and stable error categories
The public contracts are provider-neutral and storage-neutral so the runtime can be embedded into different products, CLIs, servers, or higher-level multi-agent systems.
The package should be thought of as a runtime kernel, not a complete agent platform. It intentionally keeps planner, orchestration, channel integration, governance, and product-level memory policy out of core.
Core extension points:
- Provider: connect any LLM backend
- Storage: persist snapshots and append-only transcripts
- History: maintain summaries, recall context, and other derived memory views
- ToolRegistry: expose tool schemas and execute tool calls
- PromptBuilder: produce the system prompt
- ContextBuilder: assemble model-facing messages
- Hook: observe or modify key lifecycle stages
Package shape:
- agentcore: current public runtime entrypoint and root facade
- api: stable contracts and shared runtime data types
Without Config.Storage the runtime keeps runs in an in-process MemoryStorage; pass a persistent storage to resume runs across processes.
Built-in companion packages:
- storage/files: filesystem-backed storage
- mock: test provider and tool implementations
Transcript semantics are explicit. When the provider returns tool calls, the runtime persists both the assistant tool-call message and the tool result message so runs can be resumed, replayed, and bridged across providers through a single Message contract.
Resume semantics are also explicit. A stable RunID identifies the run being continued, and ResumeMode controls whether a new user input is appended or the runtime should continue strictly from persisted state.
Repository-specific first-party implementations can live in repository-private packages while agentcore itself stays independent from internal runtime layers.
Index ¶
- Constants
- Variables
- func PrepareToolCalls(schemas []ToolSchema, calls []ToolCall)
- type Artifact
- type ArtifactStorage
- type AuthorityBundle
- type CallExpander
- type Config
- type ContextBuilder
- type ContextEvent
- type Control
- type DefaultErrorPolicy
- type DefaultResumePolicy
- type DefaultRuntime
- type DefaultToolExecutionPolicy
- type ErrorDecision
- type ErrorEvent
- type ErrorPolicy
- type FinishReason
- type GenerateRequest
- type GenerateResult
- type History
- type HistoryError
- type Hook
- type HookError
- type ImagePart
- type MemoryStorage
- func (s *MemoryStorage) AppendMessages(_ context.Context, runID string, msgs ...Message) error
- func (s *MemoryStorage) LoadArtifacts(_ context.Context, runID string) ([]Artifact, error)
- func (s *MemoryStorage) LoadMessages(_ context.Context, runID string) ([]Message, error)
- func (s *MemoryStorage) LoadRun(_ context.Context, runID string) (*RunState, error)
- func (s *MemoryStorage) SaveArtifacts(_ context.Context, runID string, artifacts []Artifact) error
- func (s *MemoryStorage) SaveRun(_ context.Context, state *RunState) error
- type Message
- type ModelEvent
- type NopHook
- type PromptBuilder
- type PromptEvent
- type Provider
- type ProviderError
- type ResumeMode
- type ResumePolicy
- type RunEvent
- type RunInput
- type RunResult
- type RunState
- type RunStatus
- type Runtime
- 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 ( RunIdle = api.RunIdle RunRunning = api.RunRunning RunYielded = api.RunYielded RunCompleted = api.RunCompleted RunFailed = api.RunFailed )
const ( ResumeAuto = api.ResumeAuto ResumeFromState = api.ResumeFromState ResumeWithInput = api.ResumeWithInput )
const ( StreamEventTextDelta = api.StreamEventTextDelta StreamEventMessageStop = api.StreamEventMessageStop StreamEventRetry = api.StreamEventRetry )
const ( UsageEstimatedMetaKey = api.UsageEstimatedMetaKey EstimatedInputTokensMetaKey = api.EstimatedInputTokensMetaKey EstimatedOutputTokensMetaKey = api.EstimatedOutputTokensMetaKey EmptyFinalMetaKey = api.EmptyFinalMetaKey )
Usage metadata keys are re-exported for callers using the root agentcore API.
const ( FinishFinal = api.FinishFinal FinishToolCalls = api.FinishToolCalls )
const ToolBatchMetaKey = api.ToolBatchMetaKey
ToolBatchMetaKey marks the tool calls of one reply, see api.ToolBatchMetaKey.
const ToolChoiceNone = api.ToolChoiceNone
ToolChoiceNone forbids tool calls (GenerateRequest.ToolChoice), see api.ToolChoiceNone.
Variables ¶
var ( ErrEmptyGenerateResult = api.ErrEmptyGenerateResult ErrMixedGenerateResult = api.ErrMixedGenerateResult ErrInvalidFinishReason = api.ErrInvalidFinishReason ErrMissingToolCallID = api.ErrMissingToolCallID ErrMissingToolName = api.ErrMissingToolName ErrToolArgumentsInvalid = api.ErrToolArgumentsInvalid ErrMissingFinishReason = api.ErrMissingFinishReason ErrProviderRequired = api.ErrProviderRequired ErrRunNotResumable = api.ErrRunNotResumable ErrHistoryStateConflict = api.ErrHistoryStateConflict ErrToolCallsNotImplemented = api.ErrToolCallsNotImplemented ErrWrapUpIgnored = api.ErrWrapUpIgnored )
Functions ¶
func PrepareToolCalls ¶
func PrepareToolCalls(schemas []ToolSchema, calls []ToolCall)
PrepareToolCalls is prepareToolCalls for hosts that own a tool catalog outside this package (and their tests): it coerces each call's arguments and sets ArgumentsError when they do not fit the tool's schema.
Types ¶
type ArtifactStorage ¶
type ArtifactStorage = api.ArtifactStorage
type AuthorityBundle ¶
AuthorityBundle exposes the authoritative storage view as explicit parts.
func LoadAuthorityBundle ¶
func LoadAuthorityBundle(ctx context.Context, storage Storage, runID string) (*AuthorityBundle, error)
LoadAuthorityBundle rebuilds the explicit authoritative run bundle from snapshot, transcript, and any optional artifact storage capability exposed by the storage backend.
func (*AuthorityBundle) FindArtifactByURI ¶
func (b *AuthorityBundle) FindArtifactByURI(uri string) (Artifact, bool)
FindArtifactByURI returns the first artifact with the given URI.
func (*AuthorityBundle) HydratedState ¶
func (b *AuthorityBundle) HydratedState() *RunState
HydratedState returns a run state rebuilt from the explicit authority parts.
func (*AuthorityBundle) LastAssistantMessage ¶
func (b *AuthorityBundle) LastAssistantMessage() (Message, bool)
LastAssistantMessage returns the latest assistant message from the authority transcript.
func (*AuthorityBundle) ToolMessages ¶
func (b *AuthorityBundle) ToolMessages() []Message
ToolMessages returns all authority transcript messages emitted by tools.
type CallExpander ¶
type CallExpander interface {
ExpandCall(ctx context.Context, call api.ToolCall) (api.ToolCall, bool)
}
CallExpander is implemented by a tool registry that expands a proxy tool call (tool_call, the segment apply mode of deferred tools) into the real tool call before execution. The runtime expands at its outermost point, so the runtime hooks, the approval layer, the PreToolUse hook, taint handling and the trace all see the real tool name: a proxied call behaves exactly like a direct one.
type Config ¶
type Config struct {
Provider Provider
Storage Storage
History History
Tools ToolRegistry
PromptBuilder PromptBuilder
ContextBuilder ContextBuilder
ResumePolicy ResumePolicy
ToolExecutionPolicy ToolExecutionPolicy
ErrorPolicy ErrorPolicy
Hooks []Hook
MaxSteps int
MaxToolCallsPerStep int
// MaxOutputTokens is the output token limit of every request this runtime
// makes (GenerateRequest.MaxTokens); 0 leaves the limit to the provider,
// which applies its own default then (e.g. Claude's 32000). The
// application resolves it from its configuration.
MaxOutputTokens int
// MaxStepsWrapUp, when set, makes reaching MaxSteps ask the model for one
// more answer instead of failing at once: the text is appended to that
// request only (not persisted) as a user message. A model that keeps
// requesting tools anyway still ends the run with an answer (see
// finishIgnoredWrapUp), never with the max-steps error.
MaxStepsWrapUp string
// PrefetchTools, when set, gets every reply with more than one tool call
// before the calls run one by one. It may start the side-effect-free ones
// concurrently, as long as each call still runs through the registry in
// order (see tools.Registry.Prefetch).
PrefetchTools func(ctx context.Context, calls []ToolCall)
}
Config configures the default runtime implementation.
type ContextBuilder ¶
type ContextBuilder = api.ContextBuilder
type ContextEvent ¶
type ContextEvent = api.ContextEvent
type DefaultErrorPolicy ¶
type DefaultErrorPolicy struct{}
DefaultErrorPolicy preserves the built-in v0 recoverable error semantics.
func (DefaultErrorPolicy) HandleRecoverable ¶
func (DefaultErrorPolicy) HandleRecoverable(_ context.Context, _ *RunState, _ *ErrorEvent) ErrorDecision
type DefaultResumePolicy ¶
type DefaultResumePolicy struct{}
DefaultResumePolicy preserves the built-in v0 resume semantics.
func (DefaultResumePolicy) AllowResume ¶
func (DefaultResumePolicy) MergeMetadata ¶
func (DefaultResumePolicy) MergeMetadata(stateMetadata, inputMetadata map[string]any) map[string]any
func (DefaultResumePolicy) ShouldAppendInstruction ¶
func (DefaultResumePolicy) ShouldAppendInstruction(input RunInput, _ *RunState) bool
type DefaultRuntime ¶
type DefaultRuntime struct {
// contains filtered or unexported fields
}
DefaultRuntime provides the minimal public runtime orchestration.
func New ¶
func New(cfg Config) *DefaultRuntime
New constructs a runnable runtime, filling in built-in defaults when possible.
type DefaultToolExecutionPolicy ¶
type DefaultToolExecutionPolicy struct {
MaxCallsPerStep int
}
DefaultToolExecutionPolicy preserves the built-in v0 tool execution semantics.
func (DefaultToolExecutionPolicy) HandleToolError ¶
func (DefaultToolExecutionPolicy) HandleToolError(_ context.Context, _ *RunState, call ToolCall, err error) ToolErrorDecision
func (DefaultToolExecutionPolicy) ValidateToolCalls ¶
type ErrorDecision ¶
type ErrorDecision = api.ErrorDecision
type ErrorEvent ¶
type ErrorEvent = api.ErrorEvent
type ErrorPolicy ¶
type ErrorPolicy = api.ErrorPolicy
type FinishReason ¶
type FinishReason = api.FinishReason
type GenerateRequest ¶
type GenerateRequest = api.GenerateRequest
type GenerateResult ¶
type GenerateResult = api.GenerateResult
type HistoryError ¶
type HistoryError = api.HistoryError
type ImagePart ¶
ImagePart is one image part of a message (see api.ImagePart): the bytes live in memory only and the store keeps the reference.
type MemoryStorage ¶
type MemoryStorage struct {
// contains filtered or unexported fields
}
MemoryStorage is the in-process Storage and ArtifactStorage used when Config.Storage is nil. Nothing survives the process, so resuming a run from another Runtime instance needs a persistent storage such as storage/files.
Values are copied through JSON on save and load, giving callers the same isolation and value shapes as the file storage.
func NewMemoryStorage ¶
func NewMemoryStorage() *MemoryStorage
NewMemoryStorage creates an empty in-memory storage.
func (*MemoryStorage) AppendMessages ¶
AppendMessages appends messages to the run's authoritative log.
func (*MemoryStorage) LoadArtifacts ¶
LoadArtifacts returns the run's artifact index; an unknown run is a storage miss, a known run without saved artifacts returns an empty slice.
func (*MemoryStorage) LoadMessages ¶
LoadMessages returns the appended messages in order; an unknown run is a storage miss, a known run without messages returns an empty slice.
func (*MemoryStorage) LoadRun ¶
LoadRun returns the saved run snapshot; a missing one is a storage miss.
func (*MemoryStorage) SaveArtifacts ¶
SaveArtifacts replaces the run's artifact index.
type ModelEvent ¶
type ModelEvent = api.ModelEvent
type PromptBuilder ¶
type PromptBuilder = api.PromptBuilder
type PromptEvent ¶
type PromptEvent = api.PromptEvent
type ProviderError ¶
type ProviderError = api.ProviderError
type ResumeMode ¶
type ResumeMode = api.ResumeMode
type ResumePolicy ¶
type ResumePolicy = api.ResumePolicy
type StorageError ¶
type StorageError = api.StorageError
type StreamEvent ¶
type StreamEvent = api.StreamEvent
type StreamEventKind ¶
type StreamEventKind = api.StreamEventKind
type StreamFunc ¶
type StreamFunc = api.StreamFunc
type StreamingProvider ¶
type StreamingProvider = api.StreamingProvider
type ToolChooser ¶
type ToolChooser = api.ToolChooser
type ToolErrorDecision ¶
type ToolErrorDecision = api.ToolErrorDecision
type ToolExecutionPolicy ¶
type ToolExecutionPolicy = api.ToolExecutionPolicy
type ToolRegistry ¶
type ToolRegistry = api.ToolRegistry
type ToolResult ¶
type ToolResult = api.ToolResult
type ToolSchema ¶
type ToolSchema = api.ToolSchema
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package api defines the stable public contracts shared by the agentcore runtime and its first-party adapters.
|
Package api defines the stable public contracts shared by the agentcore runtime and its first-party adapters. |
|
examples
|
|
|
authority
command
|
|
|
custom
command
|
|
|
host
command
|
|
|
minimal
command
|
|
|
policies
command
|
|
|
policyhost
command
|
|
|
recommended
command
Command recommended assembles a read-only agent from the agentcore layers: an llm provider, the tools registry with the read-only native tools, workspace skills, an optional MCP server and an approval policy.
|
Command recommended assembles a read-only agent from the agentcore layers: an llm provider, the tools registry with the read-only native tools, workspace skills, an optional MCP server and an approval policy. |
|
resume
command
|
|
|
stream
command
|
|
|
Package extproc runs external helper processes (exec backends) over the suga exec protocol v1 and provides the credential-stripped environment shared with MCP subprocesses.
|
Package extproc runs external helper processes (exec backends) over the suga exec protocol v1 and provides the credential-stripped environment shared with MCP subprocesses. |
|
internal
|
|
|
proctree
Package proctree kills a command's whole process tree: a process group on Unix, a job object (KILL_ON_JOB_CLOSE) on Windows, where the shell starts suspended and is resumed only after joining the job.
|
Package proctree kills a command's whole process tree: a process group on Unix, a job object (KILL_ON_JOB_CLOSE) on Windows, where the shell starts suspended and is resumed only after joining the job. |
|
runid
Package runid validates run identifiers shared by agentcore storages.
|
Package runid validates run identifiers shared by agentcore storages. |
|
Package llm implements first-party model providers for Suga.
|
Package llm implements first-party model providers for Suga. |
|
Package memory defines long-term memory for agents: entry types, the Store interface every backend implements, the Governed wrapper that applies the write policy (taint gate, sanitizing, tombstones, budget, events) and the Router that dispatches scopes to backends.
|
Package memory defines long-term memory for agents: entry types, the Store interface every backend implements, the Governed wrapper that applies the write policy (taint gate, sanitizing, tombstones, budget, events) and the Router that dispatches scopes to backends. |
|
execstore
Package execstore is a memory.Store backed by an external command that speaks the suga exec protocol v1 (see package extproc): every operation runs the command once, writes one JSON request line to its stdin and reads one JSON response line from its stdout.
|
Package execstore is a memory.Store backed by an external command that speaks the suga exec protocol v1 (see package extproc): every operation runs the command once, writes one JSON request line to its stdin and reads one JSON response line from its stdout. |
|
files
Package files is the built-in memory backend: per scope one MEMORY.md index plus one Markdown file per entry.
|
Package files is the built-in memory backend: per scope one MEMORY.md index plus one Markdown file per entry. |
|
Package netproxy selects, per request, whether the global proxy configured under network.proxy receives the request or the request connects directly.
|
Package netproxy selects, per request, whether the global proxy configured under network.proxy receives the request or the request connects directly. |
|
Package redact scrubs text before it leaves the runtime or is fed back to the model: Secrets masks credential-like values, Clean additionally strips content that can be used to smuggle instructions (invisible characters, HTML comments, forged system tags).
|
Package redact scrubs text before it leaves the runtime or is fed back to the model: Secrets masks credential-like values, Clean additionally strips content that can be used to smuggle instructions (invisible characters, HTML comments, forged system tags). |
|
Package schedule provides in-process delayed, periodic, and idle triggers for agent hosts, such as chat-idle context cleanup and future self-triggering.
|
Package schedule provides in-process delayed, periodic, and idle triggers for agent hosts, such as chat-idle context cleanup and future self-triggering. |
|
Package skills loads SKILL.md files: YAML frontmatter (name, description, optional allowed-tools) followed by Markdown instructions.
|
Package skills loads SKILL.md files: YAML frontmatter (name, description, optional allowed-tools) followed by Markdown instructions. |
|
storage
|
|
|
Package tasks runs work in the background for an agent session: start a command (or a function: a watch loop, a hook, later a sub-agent) and get an id at once, read its output while it runs, wait for it with a timeout, kill it.
|
Package tasks runs work in the background for an agent session: start a command (or a function: a watch loop, a hook, later a sub-agent) and get an id at once, read its output while it runs, wait for it with a timeout, kill it. |
|
Package agentcoretesting provides package-local conformance helpers for validating public agentcore implementations against the expected contracts.
|
Package agentcoretesting provides package-local conformance helpers for validating public agentcore implementations against the expected contracts. |
|
Package testutil holds small helpers shared by the tests of this module.
|
Package testutil holds small helpers shared by the tests of this module. |
|
Package tools provides the tool registry and execution framework.
|
Package tools provides the tool registry and execution framework. |
|
mcp
Package mcp implements a JSON-RPC 2.0 client for MCP (Model Context Protocol) servers.
|
Package mcp implements a JSON-RPC 2.0 client for MCP (Model Context Protocol) servers. |
|
native
Package native provides built-in tool implementations.
|
Package native provides built-in tool implementations. |
|
rules
Package rules contains the approval-rule model and matcher.
|
Package rules contains the approval-rule model and matcher. |