agentcore

package module
v1.8.6 Latest Latest
Warning

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

Go to latest
Published: Oct 10, 2026 License: Apache-2.0 Imports: 13 Imported by: 11

README

AgentCore

AgentCore is a small Go library for building AI agents: a model that calls tools, turn by turn, until its task is done.

English | 中文

Install

go get github.com/voocel/agentcore

Requires Go 1.26 or newer.

Design

AgentCore sits between a model SDK and an application:

litellm      models: messages, blocks, streams, errors, providers
agentcore    the agent: the loop, tools, events, compaction
your app     policy: which model, which tools, approval, storage, UI
  • Built on litellm, not wrapping it. A message is litellm blocks with a role; streamed events are litellm events; errors are litellm errors. There is no second model layer to learn or to keep in sync.
  • A stateless loop. Run takes a history and returns the history it ended with. The caller owns the history; Agent keeps one for applications that want it kept.
  • Events are facts. Every lifecycle signal reaches one callback, in order. A streamed response arrives as deltas, then once as the final message; nothing in an event changes later.
  • Messages are stored as they happen. Every message entering the history passes Emit as a MessageEnd first. An error from Emit keeps it out and stops the run, so storing there is durable.
  • Policy stays out. Approval, permissions, prompts and rendering belong to the application; the loop offers the hooks.

Packages

agentcore/            the loop (Run), Agent, Tool, Event, Message, Compactor
agentcore/compact/    Summarizer: replaces older history with a summary
agentcore/tools/      coding tools: read, write, edit, bash, glob, grep, ls; tool_search
agentcore/subagent/   the subagent tool: delegation to sub-agents
agentcore/task/       background tasks, and the tools that follow them
agentcore/schema/     a small JSON Schema builder for tool arguments

Quick Start

provider, err := deepseek.New(deepseek.Config{APIKey: os.Getenv("DEEPSEEK_API_KEY")})
if err != nil {
	log.Fatal(err)
}
client, err := litellm.New(provider)
if err != nil {
	log.Fatal(err)
}

workspace := tools.Workspace{Dir: ".", Files: tools.NewFileReadState()}
cfg := agentcore.Config{
	Model:  agentcore.Model{Client: client, Request: litellm.Request{Model: "deepseek-flash"}},
	System: []litellm.Block{litellm.Text("You are a helpful coding assistant.")},
	Tools:  workspace.Tools(),
	Emit: func(ev agentcore.Event) error {
		switch ev := ev.(type) {
		case agentcore.MessageDelta:
			if d, ok := ev.Event.(litellm.TextDelta); ok {
				fmt.Print(d.Text)
			}
		case agentcore.ToolStart:
			fmt.Printf("\n[%s] %s\n", ev.Call.Name, ev.Call.Args)
		}
		return nil
	},
}
history, err := agentcore.Run(ctx, cfg, nil, agentcore.UserText("What does this project do?"))

Model.Request is the template of every call: the model's name and settings such as MaxTokens, Thinking and ProviderOptions. The loop sets its messages and tools. Set Model.Pricing to have each response's usage priced.

Runnable examples: examples/single and examples/multi.

Agent

Agent keeps a history and runs it, one run at a time:

agent := agentcore.NewAgent(cfg, history)
unsubscribe := agent.Subscribe(func(ev agentcore.Event) error {
	switch e := ev.(type) {
	case agentcore.MessageEnd:
		return store.Append(e.Message) // a failure stops the run
	case agentcore.CompactionEnd:
		if e.Compaction != nil {
			return store.Replace(e.Compaction.Messages) // the whole new history
		}
	}
	return nil
})
defer unsubscribe()

ctx, cancel := context.WithCancel(ctx)
go agent.Prompt(ctx, agentcore.UserText("Fix the failing test"))

agent.Steer(agentcore.UserText("Use the table-driven style")) // reaches the next model call
agent.FollowUp(agentcore.UserText("Then update the docs"))   // runs when it would stop
cancel()                                                     // ends the run

A store that appends MessageEnd alone restores the history from before its compactions: Compaction.Messages is the whole new history, and Replaced how many messages of the old one it stands in for. NewAgent replaces Config.Emit, Steering and FollowUp with the subscribers, Steer and FollowUp.

A run ends when its context is cancelled. Prompt fails with ErrBusy while a run is under way. Without prompts, it answers the history as it stands, such as after a failed run, and fails with ErrNothingToContinue when it ends with a response. Compact compacts it on demand, Messages and SetMessages read and replace it. Every subscriber receives the RunEnd, even after one failed.

Events

Config.Emit (or Agent.Subscribe) receives the events below. Switch on their type.

Event When
MessageStart / MessageDelta a response starts / a litellm stream event of it arrives
MessageEnd a message enters the history: a prompt, a response, a tool result
ToolStart / ToolUpdate / ToolEnd a tool call starts, before the middleware (approval) / reports progress / ends with its result
TurnEnd a response and the results of its tool calls are recorded
Retry a model call failed and will be made again: after a wait, or, on a context overflow, after compacting
CompactionStart / CompactionEnd the history is compacted
RunEnd the run ends, with its reason, error and counts; always the last event

Events are delivered one at a time; Emit must not block for long. Returning an error from it stops the run: the tool calls under way are cancelled and no further event is delivered but the RunEnd, which is always the last. The event refused takes no effect: a refused MessageEnd or CompactionEnd keeps the message or compaction out of the history.

Messages enter the history in the order they were taken, timed as they do; those taken from Steering, FollowUp or OnStop are recorded even when the run then ends before the model answers them. None of these is consulted once the run is cancelled. A response that fails, whether the vendor ended it with an error, the stream broke off or the run was cancelled, is recorded with what streamed of it, Stop set to StopError or StopAborted and its tool calls dropped, so a transcript shows it; it is never sent to the model again.

Tools

A tool is a struct:

type weatherArgs struct {
	City string `json:"city"`
}

weather := agentcore.NewTool("weather", "Current weather of a city",
	schema.Object(schema.Property("city", schema.String("City name")).Required()),
	func(ctx context.Context, args weatherArgs) (agentcore.Result, error) {
		return agentcore.TextResult("Sunny in " + args.City), nil
	},
)
  • Arguments are validated against Schema before a call runs; the model reads what does not fit.
  • Check vets a call before it is approved and may return a preview for people, such as the diff edit and write return, found on ToolCall.Preview.
  • Parallel tools run their calls alongside the other parallel calls of their turn, up to MaxToolConcurrency; any other call runs alone.
  • Deferred tools are offered only once a tool reference in the history names them, as tool_search returns (see tools.Defer). Anthropic receives them all from the first call, marked defer_loading, so the tools of a conversation never change; see litellm.Tool.
  • A Result holds litellm blocks (text, images, tool references); Result.Text is its text. Terminate ends the run once the turn is recorded.
  • A running tool reports progress with agentcore.ReportProgress(ctx, v); it arrives as ToolUpdate. bash reports lines of output as strings, subagent reports subagent.Progress.

Config.Middleware wraps every call that passed its checks, for approval, auditing or rewriting arguments:

approve := func(ctx context.Context, call agentcore.ToolCall, next agentcore.ToolFunc) (agentcore.Result, error) {
	if call.Name == "bash" && !askUser(call) {
		return agentcore.ErrorResult("The user declined this command."), nil
	}
	return next(ctx, call)
}

Built-in Tools

A tools.Workspace makes the coding tools and holds what they share:

workspace := tools.Workspace{
	Dir:   ".",                       // relative paths resolve here; not a sandbox
	FS:    nil,                       // read/write/edit backend; nil is the local filesystem
	Files: tools.NewFileReadState(), // read-before-write checks; nil checks nothing
	Tasks: tasks,                     // bash's background commands; nil offers none
}
cfg.Tools = workspace.Tools() // or workspace.Read(), workspace.Bash(), ...
Tool Arguments Result
read file_path, offset, limit numbered lines (2000 lines / 50KB at most), a directory listing, or an image
write file_path, content a line saying what it wrote; its preview is the diff
edit file_path, old_string, new_string, replace_all the file and the diff; exact, then whitespace- and indentation-tolerant matching
bash command, timeout, workdir, description, run_in_background (with Tasks) the tail of the output (2000 lines / 50KB), then [exit code N], [timed out after …] or where the full output went
glob pattern, path matching paths, newest first
grep pattern, path, glob, ignore_case, literal, context_lines, limit path:line:text matches
ls path, depth, ignore a tree

Results are plain text. A failing command is not a failed bash call: its output and exit code are what the model needs. With Files, write refuses an existing file the model has not read whole, and write and edit one that changed since it was read. The working directory of a call's context (tools.WithCwd) overrides Dir, as for a git worktree entered mid-run. bash needs a POSIX shell (bash or sh) on PATH; on Windows that means Git Bash.

tools.Defer(tools) puts tools behind tool_search (query, max_results): the model sees their schemas only once it searched for them. The definition of tool_search does not depend on the tools, so tools deferred later leave earlier requests intact; the application tells the model their names, such as in a message.

Background Tasks

tasks := task.NewRuntime(dir, func(m agentcore.Message) { agent.FollowUp(m) })
cfg.Tools = append(cfg.Tools, tasks.Tools()...) // task_output (task_id, wait, timeout), task_stop (task_id)

bash with run_in_background and the subagent tool's background mode run work as tasks of a task.Runtime: each has an ID, a status and an output file in dir, and runs until it ends or is stopped, with no timeout unless asked. When one ends, the Runtime hands the notify function a message announcing it, of task.KindNotification, to deliver as a follow-up. Runtime.Start runs work of your own as a task.

Compaction

cfg.Compactor = compact.Summarizer{Notes: tools.FileOps} // Notes is optional
cfg.CompactAt = 100_000

The loop compacts before a call whose history is estimated above CompactAt, and once when the provider reports a context overflow, then makes the call again; the first may fail without ending the run, the second may not. The calls a compaction makes are retried as Retry allows, and their usage, on Compaction.Usage, is priced as a response's. The estimate counts from the last response's reported input tokens. CompactAt should sit well above what a compaction keeps, or every call compacts again.

compact.Summarizer replaces the history with a checkpoint the conversation's own model writes, keeping only the prompts at its end the model has yet to answer. Nothing else is replayed: Claude rejects reasoning kept past a rewrite of what came before it, and the deferred tools the history loaded are searched for again. It extends the conversation's call for the history it replaces, which is served from the prompt cache, and asks for the checkpoint in <summary> tags; when that does not fit, or the answer has no tags, it asks a second time with a plain-text transcript. With Notes: tools.FileOps the checkpoint lists the files the replaced part read and changed. Implement agentcore.Compactor for another strategy.

Sub-agents

delegate := subagent.New(tasks, // nil offers no background mode
	subagent.Agent{
		Name:        "scout",
		Description: "Fast codebase reconnaissance",
		Config: func(s subagent.Spawn) (agentcore.Config, error) {
			return agentcore.Config{Model: model, System: scoutPrompt, Tools: readOnlyTools()}, nil
		},
	},
)

The model calls subagent with agent and task to run one agent; with tasks, an array of {agent, task}, to run several in parallel, 8 at a time; with chain to run them in order, {previous} in a task standing for the output of the step before; with background (given a task.Runtime) to run one as a task; model picks another model. Each run gets its own Config, so its tools keep their own state; its events go to that Config.Emit, and to the waiting call as subagent.Progress. A run that fails reports its error with what it said last. Runs nest at most subagent.MaxDepth deep.

Config

Field Description
Model The litellm client, the request template and the pricing
System / Tools The system prompt blocks and the tools on offer
Emit Receives the events; an error stops the run
Steering / FollowUp Messages to deliver before the next call / when the run would stop
OnStop Consulted when the run would stop: go on, stop, or fail
Middleware Wraps every tool call, the first outermost
MaxToolConcurrency Parallel calls running at once (below 2, one by one)
MaxToolErrors Disables a tool failing that many turns in a row (0 never)
Compactor / CompactAt Compaction, see above
Cache Cache breakpoints after each call's last message and after the last message of the call before, which that call wrote
MaxTurns Responses per run (0 means 100)
Retry A retry.Policy pacing the calls made again after a transient failure; the zero value makes none

License

Apache License 2.0

Documentation

Overview

Package agentcore runs AI agents: a model that calls tools, turn by turn, until its task is done. It is built on litellm, whose messages, blocks and events it uses as they are, and leaves policy — which model, which tools, when to stop, how to render — to the application.

Run is the loop: given a Config and a history, it calls the model and the tools it asks for, and returns the history it ended with. It holds no state; the caller owns the history. Every lifecycle signal — streamed content, tool calls, retries, compactions — reaches Config.Emit as an Event, in order, and every message entering the history passes it as a MessageEnd first, so an application stores messages there durably.

Agent keeps a history for an application and runs it: prompting, steering a run under way, queuing follow-ups, and subscribing to the events. A run, of either, ends when its context is cancelled.

The model is a litellm Client (Model); a tool is a Tool. A long history is compacted by a Compactor, such as the summarizing one in agentcore/compact. Packages tools, subagent and task hold coding tools, sub-agents and background tasks, built on the same few types.

Index

Constants

View Source
const KindResume = "resume"

KindResume marks the prompt the loop adds after a response was cut off at the output token limit, to have the model resume it.

View Source
const KindSummary = "summary"

KindSummary marks the summary a compaction put in place of the history it replaced.

Variables

View Source
var ErrBusy = errors.New("agent is running")

ErrBusy refuses to start a run while an Agent runs one.

View Source
var ErrMaxTurns = errors.New("max turns reached")

ErrMaxTurns ends a run that reached its MaxTurns.

View Source
var ErrNoCompactor = errors.New("agentcore: no compactor configured")

ErrNoCompactor refuses to compact with a Config that has no Compactor.

View Source
var ErrNothingToContinue = errors.New("nothing to continue: the history ends with a response")

ErrNothingToContinue refuses a run without prompts when the model has nothing to answer, as when the history ends with its response.

Functions

func Estimate added in v1.8.5

func Estimate(cfg Config, history []Message) int

Estimate approximates the input tokens of the next call cfg makes for history. It counts from the usage of the last response that measured the history as it now stands, adding estimates for the messages since, and estimates all of it, system prompt and tools included, when no response did, as right after a compaction.

func ReportProgress added in v1.8.5

func ReportProgress(ctx context.Context, progress any)

ReportProgress reports the progress of the tool call ctx runs, such as its output so far; the run emits it as a ToolUpdate. What progress is, each tool documents.

func SummaryText added in v1.8.5

func SummaryText(m Message) string

SummaryText returns the summary a SummaryMessage holds.

func WithProgress added in v1.8.5

func WithProgress(ctx context.Context, fn func(progress any)) context.Context

WithProgress returns ctx with fn receiving the progress the tool calls it runs report.

Types

type Agent

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

Agent is a conversation an application drives: it keeps the history and runs it, one run at a time, taking the messages that arrive meanwhile. It replaces the Emit, Steering and FollowUp of its Config: events go to its subscribers. A run ends when the context it was started with is cancelled. An Agent is safe for concurrent use.

func NewAgent

func NewAgent(cfg Config, history []Message) *Agent

NewAgent returns an Agent that runs history with cfg. Its runs replace cfg's Emit, Steering and FollowUp with the Agent's: subscribers, Steer and FollowUp.

func (*Agent) ClearQueues added in v1.8.5

func (a *Agent) ClearQueues() (steering, followUp []Message)

ClearQueues takes back the messages queued by Steer and FollowUp that no run delivered yet, such as to drop them when the user aborts, or to start a run for those that arrived as one ended.

func (*Agent) Compact added in v1.8.5

func (a *Agent) Compact(ctx context.Context) error

Compact has the Config's Compactor rewrite the history now, as a run does when the history outgrows its CompactAt. Subscribers receive its CompactionStart and CompactionEnd. It fails with ErrBusy while a run is under way, and with ErrNoCompactor when the Config has none.

func (*Agent) Config added in v1.8.5

func (a *Agent) Config() Config

Config returns the Agent's Config.

func (*Agent) FollowUp

func (a *Agent) FollowUp(msgs ...Message)

FollowUp delivers msgs once the run under way, or else the next, would stop.

func (*Agent) Messages

func (a *Agent) Messages() []Message

Messages returns the history, up to the last message recorded.

func (*Agent) Prompt

func (a *Agent) Prompt(ctx context.Context, prompts ...Message) error

Prompt runs the history with prompts added, and returns when the run ends, with its error. Without prompts, it answers the history as it is, such as after a run failed; see Run for when there is nothing to answer. It fails with ErrBusy while a run is under way; use Steer or FollowUp then.

func (*Agent) SetConfig added in v1.8.5

func (a *Agent) SetConfig(cfg Config)

SetConfig replaces the Agent's Config, from the next run on.

func (*Agent) SetMessages

func (a *Agent) SetMessages(history []Message) error

SetMessages replaces the history, such as to start over; it fails with ErrBusy while a run is under way.

func (*Agent) Steer

func (a *Agent) Steer(msgs ...Message)

Steer delivers msgs before the next model call of the run under way, or of the next run.

func (*Agent) Subscribe

func (a *Agent) Subscribe(fn func(Event) error) (unsubscribe func())

Subscribe has fn receive the events of the Agent's runs, after those of earlier subscribers, until unsubscribe is called. An error fn returns stops the run, as one Emit returns does, and later subscribers do not receive the event: storing messages on MessageEnd keeps them out of the history when that fails. Every subscriber receives the RunEnd.

An event takes effect on the history only once every subscriber took it, so Messages, called by a subscriber, does not yet include the message of the MessageEnd it is handling.

type Call added in v1.8.5

type Call struct {
	Client  *litellm.Client
	Request litellm.Request
}

Call is a model call exactly as the loop makes it. A side call that extends its request, such as for a summary, reads the loop's prompt cache.

func BuildCall added in v1.8.5

func BuildCall(cfg Config, history []Message) Call

BuildCall builds the call the loop makes next for history: the system prompt, the history as the model reads it, with the cache breakpoint, and the tools on offer.

type Compaction added in v1.8.5

type Compaction struct {
	// Messages is the history that replaces it.
	Messages []Message
	// Replaced is how many messages of the history the rewrite stands in for.
	Replaced int
	// Usage is what the model calls of the rewrite used, if any; a run
	// prices it as it does responses.
	Usage *Usage
}

Compaction is a rewrite of a history.

type CompactionEnd added in v1.8.5

type CompactionEnd struct {
	Compaction *Compaction
	Err        error
}

CompactionEnd ends a compaction: with the Compaction that replaces the history, nil when there was nothing to compact, or with Err. Returning an error from Emit for a Compaction keeps the history as it was and stops the run, so an application stores compactions here durably.

type CompactionStart added in v1.8.5

type CompactionStart struct{}

CompactionStart begins a compaction of the history.

type Compactor added in v1.8.5

type Compactor interface {
	// Compact rewrites history. call builds the call the loop would make for
	// a history, as BuildCall does with the run's Config: a compactor that
	// summarizes with the conversation's model can extend the call for the
	// part of the history it replaces, which earlier calls sent, and read it
	// from the prompt cache. A nil Compaction means there is nothing to
	// compact.
	Compact(ctx context.Context, history []Message, call func([]Message) Call) (*Compaction, error)
}

Compactor rewrites a history into a shorter one that carries the same work forward. The loop decides when to call it (Config.CompactAt, and a context overflow) and records the result; an application may also call it itself, such as for a manual compaction.

The deferred tools a history loaded stay offered only while a tool reference in it names them (see Tool.Deferred): once a compaction replaced the results holding the references, the model searches for them again.

type Config added in v1.8.5

type Config struct {
	Model Model
	// System is the system prompt: text blocks, which may carry cache
	// breakpoints.
	System []litellm.Block
	Tools  []Tool

	// Emit receives the run's events, one at a time, in order. An error it
	// returns stops the run: the tool calls under way are cancelled, no
	// further event is delivered but the RunEnd carrying the error, and the
	// event refused takes no effect; see MessageEnd and CompactionEnd. Nil
	// drops the events.
	Emit func(Event) error

	// Steering returns the messages to deliver before the next model call,
	// such as what a user typed while the run worked. It is called at the
	// start, after each turn, and after each compaction in the run, which
	// can take long.
	Steering func() []Message
	// FollowUp returns the messages to go on with when the run would stop.
	FollowUp func() []Message
	// OnStop is consulted when the run would stop and neither Steering nor
	// FollowUp has messages: after a response that calls no tool, or a turn
	// a tool Terminated. It returns messages to go on with, none to stop, or
	// an error to end the run with.
	//
	// Messages Steering, FollowUp and OnStop return are recorded at once,
	// even when the run then ends, cancelled or at MaxTurns, before the
	// model answers them. None is consulted once the run is cancelled.
	OnStop func(ctx context.Context, s StopInfo) ([]Message, error)

	// Middleware wraps every tool call, the first outermost.
	Middleware []ToolMiddleware
	// MaxToolConcurrency bounds the parallel tool calls running at once;
	// below 2, calls run one by one.
	MaxToolConcurrency int
	// MaxToolErrors disables a tool, for the rest of the run, once its calls
	// failed that many turns in a row; 0 never does. A refused call, or one
	// of an unknown tool, does not count.
	MaxToolErrors int

	// Compactor rewrites the history when it grows past CompactAt estimated
	// tokens, before the call that would send it, and when the provider
	// reports a context overflow, after which the call is made again. A
	// compaction at CompactAt that fails is reported and the call made
	// anyway; one on overflow must succeed. Zero CompactAt compacts on
	// overflow only. CompactAt should sit well above what a compaction
	// keeps, or every call compacts again.
	Compactor Compactor
	CompactAt int
	// Cache, if set, places two cache breakpoints: after each call's last
	// message, and after the last message of the call before, so a call
	// reads the history that call sent from the prompt cache however many
	// blocks the turn between them added. With the system prompt's, they
	// must stay within the provider's limit, 4 on Anthropic; breakpoints of
	// a longer TTL must come before those of a shorter one.
	Cache *litellm.CacheControl

	// MaxTurns bounds the responses of a run; 0 means 100.
	MaxTurns int
	// Retry paces the model calls made again after failing for a while,
	// such as on a rate limit or a dropped connection: a response, or a
	// compaction, makes at most Retry.MaxAttempts calls. The zero Policy
	// makes none again.
	Retry retry.Policy
}

Config configures a run.

func (Config) Validate added in v1.8.5

func (cfg Config) Validate() error

Validate reports a Config a run cannot use: a Pricing that does not fit, a Model.Request already holding Messages or Tools, which a run sets, or a tool without a name, with another's name, or with a schema that is not JSON. Run and the runs of an Agent validate it themselves.

type EndReason added in v1.5.7

type EndReason string

EndReason is why a run ended.

const (
	EndDone     EndReason = "done"
	EndMaxTurns EndReason = "max_turns"
	EndAborted  EndReason = "aborted"
	EndError    EndReason = "error"
)

type Event

type Event interface {
	// contains filtered or unexported methods
}

Event is something that happened in a run, delivered to Config.Emit. The events are the types below; switch on them by type.

A run streams each response as MessageStart, then MessageDelta events, and records it with MessageEnd, which every message entering the history passes through. Events hold no state that changes later: a MessageEnd's message is final, and the streamed content is in the deltas only.

type Message

type Message struct {
	Role   litellm.Role    `json:"role"`
	Blocks []litellm.Block `json:"blocks"`
	// Kind marks a message the loop or the application added for its own
	// purposes, such as KindSummary. Models see it as any message of its
	// role.
	Kind string `json:"kind,omitempty"`
	// Stop, Usage, Provider and Model describe an assistant message: why the
	// response ended, what it used, and what produced it.
	Stop     StopReason `json:"stop,omitempty"`
	Usage    *Usage     `json:"usage,omitempty"`
	Provider string     `json:"provider,omitempty"`
	Model    string     `json:"model,omitempty"`
	// Time is when the message entered the history.
	Time time.Time `json:"time"`
}

Message is one entry of a conversation: a model message, in litellm's roles and blocks, with what the loop knows of it. A tool result is a message of role litellm.RoleTool holding one litellm.ToolResultBlock. Messages encode as JSON, so a history is stored as it is.

func LastResponse added in v1.8.5

func LastResponse(history []Message) Message

LastResponse returns the last response in history, the zero Message when there is none.

func Run added in v1.8.5

func Run(ctx context.Context, cfg Config, history []Message, prompts ...Message) ([]Message, error)

Run runs cfg's agent on history: it records prompts, then calls the model and the tools it asks for, turn by turn, until the model stops, ctx is cancelled or an error ends the run. It returns the history the run ended with, compactions included, and the error that ended it: ctx's error when cancelled. Every message entering the history passes Emit as a MessageEnd first, and the last event is always a RunEnd.

Without prompts, Run answers the history as it stands; it fails with ErrNothingToContinue when the model has nothing to answer, as when the history ends with a response.

func SummaryMessage added in v1.8.5

func SummaryMessage(summary string) Message

SummaryMessage returns the message that stands in for history a compaction replaced with summary, telling the model to carry on from it. Models read it as a user message.

func ToolResult

func ToolResult(id string, result Result) Message

ToolResult returns the message that answers the tool call id with result.

func User added in v1.8.5

func User(blocks ...litellm.Block) Message

User returns a user message of blocks.

func UserText added in v1.8.5

func UserText(text string) Message

UserText returns a user message of text.

func (Message) Reasoning added in v1.8.5

func (m Message) Reasoning() string

Reasoning returns the text of m's reasoning blocks.

func (Message) Text added in v1.8.5

func (m Message) Text() string

Text returns the text of m's text blocks, or of the tool result it holds.

func (Message) ToolCalls

func (m Message) ToolCalls() []litellm.ToolUseBlock

ToolCalls returns the tool calls m makes.

func (Message) ToolResult added in v1.8.5

func (m Message) ToolResult() (litellm.ToolResultBlock, bool)

ToolResult returns the tool result m holds.

func (*Message) UnmarshalJSON added in v1.8.5

func (m *Message) UnmarshalJSON(data []byte) error

type MessageDelta added in v1.8.5

type MessageDelta struct{ Event litellm.Event }

MessageDelta is a streamed event of the response under way: a block started, text or arguments added, a block ended, usage. A Retry discards the response so far.

type MessageEnd added in v1.8.5

type MessageEnd struct{ Message Message }

MessageEnd records a message entering the history: a prompt, a response, a tool result. Returning an error from Emit for it keeps it out and stops the run, so an application stores messages here durably.

type MessageStart added in v1.8.5

type MessageStart struct{}

MessageStart begins a response; MessageDelta events stream its content.

type Model added in v1.8.5

type Model struct {
	Client *litellm.Client
	// Request is the template of every call: the model's name and settings,
	// such as MaxTokens, Thinking and ProviderOptions. The loop sets its
	// Messages and Tools.
	Request litellm.Request
	// Pricing, if set, prices each response's usage.
	Pricing *catalog.Pricing
}

Model is the model a run calls.

type Result added in v1.8.5

type Result struct {
	// Content is what the model reads: text, images and tool references.
	Content []litellm.Block
	IsError bool
	// Terminate ends the run once the turn's results are recorded, as a tool
	// that completes the task does. The run's OnStop may keep it going.
	Terminate bool
}

Result is what a tool call returns to the model.

func ErrorResult added in v1.8.5

func ErrorResult(text string) Result

ErrorResult returns text as a failed result.

func JSONResult added in v1.8.5

func JSONResult(v any) (Result, error)

JSONResult returns v, as JSON text, as a result. Characters such as < and & stay as they are, as the model reads them.

func TextResult added in v1.8.5

func TextResult(text string) Result

TextResult returns text as a result.

func (Result) Text added in v1.8.5

func (r Result) Text() string

Text returns the text of r's text blocks.

type Retry added in v1.8.5

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

Retry reports a model call that failed with Err, which the run makes again after Delay; one that overflowed the context, after compacting. Attempt numbers the call to come, the first made again being 2.

type RunEnd added in v1.8.5

type RunEnd struct {
	Reason EndReason
	Err    error
	// Turns, ToolCalls and FailedCalls count the run's responses, the tool
	// calls they made and the calls whose result is an error, refused calls
	// included, which Config.MaxToolErrors does not count.
	Turns, ToolCalls, FailedCalls int
}

RunEnd ends a run, with the error that ended it. It is always the run's last event, delivered even after Emit failed.

type StopInfo added in v1.6.4

type StopInfo struct {
	// Message is the last response.
	Message Message
	// Terminated reports that a tool of the last turn terminated the run.
	Terminated bool
	// Turns is how many responses the run had.
	Turns int
}

StopInfo is what OnStop decides on.

type StopReason

type StopReason string

StopReason is why a response ended.

const (
	// StopEnd is a response the model ended.
	StopEnd StopReason = "end"
	// StopToolUse is a response that calls tools.
	StopToolUse StopReason = "tool_use"
	// StopLength is a response cut off at the output token limit.
	StopLength StopReason = "length"
	// StopSafety is a response the vendor's safety system ended or refused.
	StopSafety StopReason = "safety"
	// StopError is a response the vendor ended with an error.
	StopError StopReason = "error"
	// StopAborted is a response the run was cancelled during; it holds what
	// streamed before.
	StopAborted StopReason = "aborted"
	// StopOther is a reason the vendor gave that has no equivalent here.
	StopOther StopReason = "other"
)

type Tool

type Tool struct {
	Name        string
	Description string
	// Schema is the JSON Schema of the arguments. Calls are validated
	// against it before they run, and the model sees what does not fit.
	Schema map[string]any
	// Label names the tool for people, such as "Edit File".
	Label string
	// Deferred tools are offered to the model only once a
	// litellm.ToolReferenceBlock in the history names them, as a tool search
	// returns; until then they cost no context. See litellm.Tool.
	Deferred bool
	// Parallel lets the tool's calls run alongside the other parallel calls
	// of their turn; any other call runs alone.
	Parallel bool
	// Check, if set, vets a call before it is approved and run, such as that
	// a file was read before it is edited, and may preview for people what
	// the call will do, such as a diff to approve. An error fails the call.
	Check func(ctx context.Context, args json.RawMessage) (preview string, err error)
	// Run makes a call. An error fails it, and the model reads the error.
	Run func(ctx context.Context, args json.RawMessage) (Result, error)
}

Tool is a function the model may call.

func NewTool added in v1.8.5

func NewTool[P any](name, description string, schema map[string]any, run func(ctx context.Context, args P) (Result, error)) Tool

NewTool returns a tool whose calls run with their arguments decoded into P, once they fit schema.

type ToolCall

type ToolCall struct {
	ID   string
	Name string
	Args json.RawMessage
	// Tool is the tool called; nil when the model called an unknown one.
	Tool *Tool
	// Preview is what the tool's Check previewed.
	Preview string
}

ToolCall is a call of a tool, as the loop runs it.

type ToolEnd added in v1.8.5

type ToolEnd struct {
	Call   ToolCall
	Result Result
}

ToolEnd ends a tool call with its result.

type ToolFunc added in v1.8.5

type ToolFunc func(ctx context.Context, call ToolCall) (Result, error)

ToolFunc runs a tool call.

type ToolMiddleware added in v1.5.1

type ToolMiddleware func(ctx context.Context, call ToolCall, next ToolFunc) (Result, error)

ToolMiddleware wraps the running of each tool call, once its arguments are valid and its tool's Check passed: for approval, auditing or rewriting the arguments. It calls next to go on; returning without calling next, such as with an ErrorResult, refuses the call.

type ToolStart added in v1.8.5

type ToolStart struct{ Call ToolCall }

ToolStart begins a tool call, once its arguments were checked and before the middleware, such as an approval, runs it.

type ToolUpdate added in v1.8.5

type ToolUpdate struct {
	Call     ToolCall
	Progress any
}

ToolUpdate is the progress a running tool reported, see ReportProgress; it comes between the call's ToolStart and ToolEnd.

type TurnEnd added in v1.8.5

type TurnEnd struct {
	Message Message
	Results []Message
}

TurnEnd ends a turn: a response and the results of the tools it called, all recorded.

type Usage

type Usage struct {
	litellm.Usage
	Cost *catalog.Cost `json:"cost,omitempty"`
}

Usage is what a response used, and what that cost when the model's pricing is known.

func (*Usage) Add

func (u *Usage) Add(o *Usage)

Add adds o, if any, to u: a running total, such as a session's. The total costs what the priced usage cost.

Directories

Path Synopsis
Package compact holds Summarizer, the agentcore.Compactor that replaces older history with a structured checkpoint summary.
Package compact holds Summarizer, the agentcore.Compactor that replaces older history with a structured checkpoint summary.
examples
multi command
Multi runs an agent that delegates to sub-agents, a scout and a reviewer:
Multi runs an agent that delegates to sub-agents, a scout and a reviewer:
single command
Single runs one agent with the coding tools on a task:
Single runs one agent with the coding tools on a task:
Package schema builds the JSON Schema of a tool's arguments, as the map[string]any agentcore's Tool.Schema holds.
Package schema builds the JSON Schema of a tool's arguments, as the map[string]any agentcore's Tool.Schema holds.
Package subagent lets a model delegate tasks to sub-agents, which work on them in contexts of their own and report back.
Package subagent lets a model delegate tasks to sub-agents, which work on them in contexts of their own and report back.
Package task runs work in the background as tasks the model can follow: each has an ID, a status and an output file, and a message announces it when it ends.
Package task runs work in the background as tasks the model can follow: each has an ID, a status and an output file, and a message announces it when it ends.
Package tools holds the coding tools of an agent.
Package tools holds the coding tools of an agent.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL