agent

type APIError ¶

type APIError struct {
	StatusCode int
	Body       string
	Message    string // the provider's error message
	Type       string // the provider's error type (OpenAI, Anthropic) or status (Gemini)
	Code       string // the provider's error code (OpenAI)
	Err        error
}

APIError is returned by a provider adapter for a non-2xx HTTP response that is not a rate limit (which uses RateLimited), and for an exhausted quota whatever its status (wrapping ErrQuotaExhausted). It carries the StatusCode so a retry classifier can tell a transient failure (5xx, 408) from a terminal one (most 4xx: auth, validation), the provider's error fields when the body held its error object, and the Body (cut to 8KB) for diagnostics. It wraps Err (typically ErrModel) so errors.Is(err, ErrModel) holds. StatusCode is 0 for an error the provider sent partway through a stream without one.

func (e *APIError) Error() string

func (e *APIError) Unwrap() error

type Agent ¶

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

Agent binds a model, a tool set, a durable store, and a middleware chain.

The WithX/Use/SetX builder methods MUTATE the receiver in place and return it for chaining; they do not copy. This is deliberate: it lets configuration be applied after construction and after the value has been shared, e.g. a.Use(trace.Model(...)) or a.Use(agent.WithRetrieval(...)) wiring a cross-cutting concern onto an agent other code already holds. The consequence is that two variables assigned from the same New(...) are aliases: reconfiguring one reconfigures both. When you need an independently configured variant, construct a fresh Agent rather than expecting a builder to fork. (The internal clone/cloneWith, used by RunTyped, do copy; they are not exported.)

An Agent is safe for concurrent Run/Stream/Session calls once configured; the builder methods are not safe to call concurrently with a run or with each other. Configure first, then run.

func New(model Model, store Durable, tools ...Tool) *Agent

func (a *Agent) Run(ctx context.Context, runID, input string) (Message, error)

func (a *Agent) RunResult(ctx context.Context, runID, input string) (*Result, error)

func (a *Agent) RunSaga(ctx context.Context, runID, input string) (Message, error)

func (a *Agent) RunSagaResult(ctx context.Context, runID, input string) (*Result, error)

func (a *Agent) Session(ctx context.Context, id string) (*Session, error)

func (a *Agent) SetMaxConcurrency(n int) *Agent

func (a *Agent) Stream(ctx context.Context, runID, input string) *AgentStream

// A model that answers directly (a real adapter streams token deltas the same way).
m := &scriptModel{turns: [][]Emit{textTurn("hello world")}}
a := New(m, NewMemStore())

stream := a.Stream(context.Background(), "run-1", "hi")
for ev := range stream.Events() {
	switch e := ev.(type) {
	case TurnStarted:
		fmt.Println("turn started")
	case ModelEvent:
		if d, ok := e.Event.(TextDelta); ok {
			fmt.Printf("delta: %q\n", d.Text)
		}
	case Finished:
		fmt.Println("finished")
	}
}
answer, err := stream.Final()
if err != nil {
	fmt.Println("error:", err)
	return
}
fmt.Println("answer:", textOf(answer))

Output:
turn started
delta: "hello world"
finished
answer: hello world

func (a *Agent) StreamSaga(ctx context.Context, runID, input string) *AgentStream

func (a *Agent) Use(mw ...Middleware) *Agent

func (a *Agent) UseTool(mw ...ToolMiddleware) *Agent

func (a *Agent) WithApproverVerifiers(fn ApproverVerifierFor) *Agent

func (a *Agent) WithMaxTurns(n int) *Agent

func (a *Agent) WithSampling(opts ...SamplingOption) *Agent

func (a *Agent) WithSystemPrompt(s string) *Agent

func (a *Agent) WithSystemPromptFunc(fn func(context.Context) string) *Agent

func (a *Agent) WithTokenBudget(max int) *Agent

func (a *Agent) WithToolChoice(tc ToolChoice) *Agent

func (a *Agent) WithToolErrorRedactor(fn func(tool string, err error) string) *Agent

type AgentEvent ¶

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

AgentEvent is a lifecycle event emitted by Agent.Stream as the run loop advances: turn boundaries, live model token deltas, and tool start/finish. It is the SEMANTIC-layer companion to the model's byte-level Event — a UI ranges over these to render progress while the durable loop runs underneath.

The terminal answer and any error are NOT events: they come from AgentStream.Final (mirroring how the model Stream yields Events but returns the assembled Message separately). A run that pauses for approval or halts on an unsafe resume emits the relevant lifecycle event and then surfaces the *PendingApproval / *ResumeHalt via Final, exactly as Run returns it.

func ProjectEvents(recs []Record) (events []AgentEvent, sources []int)

func ReplayEvents(ctx context.Context, store Durable, runID string) ([]AgentEvent, error)

type AgentStream ¶

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

AgentStream is a live view of a running agent: range Events for progress, then call Final for the terminal answer (or error). It is the streaming counterpart of Run, the same way the model Stream is the counterpart of Generate — Run is literally Stream(...).Final().

A Stream is consumed once. Either range Events fully (Final then returns immediately) or call Final directly (it drains and discards events); calling Final after breaking out of Events early drains whatever remains. Cancel ctx to abandon a run without draining — pending emits then unblock on ctx.Done rather than leaking.

func (as *AgentStream) Events() iter.Seq[AgentEvent]

func (as *AgentStream) Final() (Message, error)

type ApprovalPolicy ¶ added in v0.4.0

type ApprovalPolicy struct {
	Need      int      // decisions required to proceed (k), 1 <= Need <= len(Approvers)
	Approvers []string // eligible approver ids; the bounded set (n)
}

ApprovalPolicy declares a k-of-n human gate. Need is k; the eligible approvers are the bounded set (n = len(Approvers)). A tool with a non-nil Approval requires approval whether or not RequiresApproval is also set.

func (p ApprovalPolicy) Validate() error

type ApprovalRequired ¶

type ApprovalRequired struct {
	ToolUseID string
	Name      string
	Args      json.RawMessage
	// Quorum is the running tally when the tool has an m-of-n Safety.Approval policy, so a
	// streaming UI can show progress ("1 of 2 approved") without waiting for Final. Nil for
	// a 1-of-1 gate.
	Quorum *ApprovalTally
}

ApprovalRequired fires immediately before the run pauses for a human decision on a tool that requires approval. The run then returns *PendingApproval from Final; record a decision (Approve, or ApproveAs for an m-of-n gate) and re-invoke to continue.

type ApprovalSubject ¶ added in v0.4.0

type ApprovalSubject struct {
	RunID     string
	ToolUseID string
	ToolName  string
	Args      json.RawMessage
}

ApprovalSubject is exactly what an approver decides on: one tool call, with its name and arguments, in one run. The decision bytes bind all of it, so a signature approves this call and no other: not another run, not another call, and not the same call id with different arguments.

type ApprovalTally ¶ added in v0.4.0

type ApprovalTally struct {
	Need       int      `json:"need"`                  // the policy's k
	Approvers  []string `json:"approvers"`             // the eligible set the gate enforced, in policy order
	Approved   int      `json:"approved"`              // approvers whose counted decision is an approval
	Denied     int      `json:"denied"`                // approvers whose counted decision is a denial
	ApprovedBy []string `json:"approved_by,omitempty"` // those approvers, in journal order
	DeniedBy   []string `json:"denied_by,omitempty"`   // those approvers, in journal order
	Pending    []string `json:"pending,omitempty"`     // eligible approvers with no valid decision yet, in policy order
	// Records names every decision record on this call the gate read, valid or not, in
	// journal order. Evidence must disclose all of them, so an omitted decision is detectable.
	Records []string `json:"records,omitempty"`
}

ApprovalTally is the m-of-n gate's count for one call. At a pause it is the running tally (PendingApproval.Quorum, ApprovalRequired.Quorum). At a terminal outcome the gate journals it under ApprovalTallyStep, before the tool runs, as the record of what it enforced and what it read.

func (t ApprovalTally) Passed() bool

func (t ApprovalTally) Unreachable() bool

type ApproveOption ¶ added in v0.4.0

type ApproveOption func(*approveOptions)

ApproveOption configures ApproveAs.

func WithDecisionCheck(verifierFor ApproverVerifierFor) ApproveOption

type ApproverVerifier ¶ added in v0.4.0

type ApproverVerifier interface {
	Verify(message, sig []byte) bool
}

ApproverVerifier checks an approver's signature over the decision bytes. Any audit.Verifier satisfies it structurally, so a deployment reuses the existing ed25519/ML-DSA/hybrid verifiers with no new cryptography and no agent->audit import.

type ApproverVerifierFor ¶ added in v0.4.0

type ApproverVerifierFor func(approverID string) (ApproverVerifier, bool)

ApproverVerifierFor resolves the verifier for an approver id (the caller's PKI, mirroring audit's issuer lookup). It reports ok=false for an unknown approver; the counting rule treats that approver's decisions as unverifiable.

type AssistantTurn ¶

type AssistantTurn struct {
	Message  Message
	Replayed bool
}

AssistantTurn is the fully-assembled assistant message for a turn. Replayed is true when it was reconstructed from the journal on resume rather than produced by a live model call (in which case no ModelEvent deltas preceded it).

type Awaiting ¶

type Awaiting struct {
	RunID string
	// RootRunID is the run to re-invoke to continue: the top-level run. It differs from RunID
	// when the signal comes from inside a sub-agent, whose journal is RunID. Record the answer
	// against RunID (Resume, Approve, ResolveHalt, Signal), then run RootRunID with the root agent.
	RootRunID string
	Name      string
	Prompt    any // optional caller payload describing what the run is waiting for
}

Awaiting is returned by Run when a tool called Await and no signal has been delivered for that name yet. The run has paused durably at the await point. Deliver a signal with Signal (same name), then re-invoke Run with the same runID to continue. Awaiting is the externally-pushed dual of Interrupted: Interrupt asks a human and resumes with their answer; Await waits for an event an outside system delivers.

func (e *Awaiting) Error() string

type Compensator ¶

type Compensator interface {
	// Compensate undoes a completed call. args are the arguments the tool accepted (after tool
	// middleware; see CompensatedFunc); result
	// is what Call returned. Must be idempotent — on a crash mid-rollback it may re-run.
	Compensate(ctx context.Context, args, result json.RawMessage) error
}

Compensator is an optional interface a Tool implements to declare how to UNDO its side effect. In a saga run (RunSaga), if a step fails after earlier writes succeeded, the completed compensatable writes are rolled back in reverse order — automatically, and recursively through sub-agent trees.

This is the transactional / saga agent: "charged the card and booked the flight, then failed on the hotel → cleanly refund + cancel." It's the gsm compensation idea applied to the agent runtime — the journal records exactly which writes completed, so well-founded reverse compensation falls out of the durable substrate.

A saga step must be ATOMIC: it must not leave a partial external side effect before returning an error, because the failing step itself is not compensated (there's no recorded result to drive Compensate). Make forward steps all-or-nothing, or idempotent.

type DecisionCheck ¶ added in v0.4.0

type DecisionCheck struct {
	Step     string // the record's journal name
	Approver string
	Approved bool
	Counted  bool   // this is the approver's decision: their first valid one
	Reason   string // why it did not count; empty when Counted
}

DecisionCheck is how the counting rule classified one decision record.

type Describer ¶ added in v0.8.0

type Describer interface {
	Describe() ModelInfo
}

Describer is implemented by a Model that can say what it is. It is optional: the agent never requires it, and ModelInfoOf reports false for a Model that does not implement it.

type Doc ¶

type Doc struct {
	ID       string         `json:"id,omitempty"`
	Text     string         `json:"text"`
	Score    float64        `json:"score,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

Doc is a document returned by a Retriever: its text plus optional id, similarity score, and metadata. This is the neutral shape the retrieval helpers speak; your Retriever maps your store's results onto it. A NaN or infinite Score (cosine similarity against a zero vector is 0/0) has no JSON encoding, so the retrieval helpers drop it (report 0).

type Durable ¶

type Durable interface {
	// Do returns the recorded Record for (runID, name) without running fn if present;
	// otherwise runs fn, records the returned Record (with Name set and a fresh Salt: persist
	// the bytes JournalEntry returns), and returns it. A recorded Record is read back with
	// DecodeStoredRecord, which refuses a row whose record names another step.
	// If fn errors, nothing is recorded — the step re-runs on the next attempt. Once fn has
	// returned a record, Do records it even if ctx was cancelled meanwhile: fn may have fired a
	// side effect, and its outcome must not be lost (see durabletest).
	Do(ctx context.Context, runID, name string, fn func(context.Context) (Record, error)) (Record, error)
	// History returns all recorded steps for a run, in order, each read back with
	// DecodeStoredRecord under the name it is stored under.
	History(ctx context.Context, runID string) ([]Record, error)
}

Durable is the crash-safe substrate: named-step memoization. Do runs a step at most-once per (runID, name): a recorded step returns without re-running fn. This mirrors DBOS RunAsStep and ADK v2 RunNode; our SQLite default implements it directly, and store/postgres is the high-availability backend. The side-effect-safety layer (Safety / ResumeHalt) sits ABOVE this and is substrate-agnostic (see Agent.Run).

type Emit ¶

type Emit struct {
	Event Event
	Err   error
}

Emit is what an adapter pushes onto its event channel (event or terminal error).

type Event ¶

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

Event is a normalized streamed model event. The stream/ package maps every provider wire format (OpenAI SSE / Anthropic typed / Gemini NDJSON / Bedrock binary) onto these.

type Finish ¶

type Finish struct {
	Reason    FinishReason
	Raw       string // the provider's own finish reason, as it sent it ("end_turn", "STOP"); empty if it sent none
	Usage     Usage
	Discarded Usage
}

Finish ends a model turn. Reason says why the turn ended, in the neutral vocabulary below; an adapter maps its provider's reasons onto it where they enter, and keeps the provider's own value in Raw. A first-party adapter always sets Reason: a provider reason it does not know is passed through unchanged (Reason is then Raw), and a turn the provider ended without naming a reason is FinishStop with an empty Raw. A Model that does not know the reason may leave Reason empty, which counts as a natural stop.

The reason decides whether the turn is the model's answer. Stream.Message (and so every agent run) returns ErrOutputTruncated for FinishLength and ErrOutputFiltered for FinishFiltered rather than a message, since what arrived is only part of what the model would have said, and a run that recorded it would end with that part as its final answer. Any other reason is ErrStreamProtocol: the core does not guess what a provider's own word means.

The reason never decides whether tools run: the calls the turn carries do. A turn with calls runs them whatever its reason says (OpenAI reports stop under a forced tool_choice), and a FinishToolUse turn with no call is ErrStreamProtocol, since the calls it was for were lost.

Usage is what the turn's own response cost. Discarded is usage billed for responses the turn threw away (failed attempts a middleware retried, losing hedge targets); a live adapter leaves it zero, and a Model that replays a recorded turn reports the discarded spend it recorded there.

type FinishReason ¶ added in v0.8.0

type FinishReason string

FinishReason is why a model turn ended, in a neutral vocabulary every adapter maps its provider's reasons onto (see Finish). The set is closed: the core accepts only the constants below and the empty reason.

const (
	FinishStop     FinishReason = "stop"     // the model ended its answer (end of turn, a stop sequence)
	FinishToolUse  FinishReason = "tool_use" // the model ended its turn to call tools
	FinishLength   FinishReason = "length"   // the output hit its token limit (or the context window) and was cut off
	FinishFiltered FinishReason = "filtered" // a safety or content filter, or a refusal, stopped the output
)

type Finished ¶

type Finished struct{ Final Message }

Finished carries the terminal assistant answer — the same Message that Run returns and that Final reports. The event stream closes after this.

type HaltTooYoung ¶ added in v0.3.0

type HaltTooYoung struct {
	RunID     string
	ToolUseID string
	Age       time.Duration // elapsed since the effect was attempted
	Min       time.Duration // the required minimum
}

HaltTooYoung is returned by ResolveHalt when WithMinHaltAge is set and the halt has not aged past the grace period yet. Wait and retry the resolution later.

func (e *HaltTooYoung) Error() string

type Identity ¶

type Identity struct {
	// Actor is the acting agent instance: a deployment plus model version, e.g. "exec-agent@1.4.2".
	Actor string `json:"actor,omitempty"`
	// OnBehalfOf is the principal the agent acts for: a desk, an account, a user.
	OnBehalfOf string `json:"on_behalf_of,omitempty"`
	// AuthorityRef identifies the grant that authorizes this action: the digest or id of a signed
	// capability/authority record (see audit anchoring), so the leaf links to what permitted it.
	AuthorityRef string `json:"authority_ref,omitempty"`
}

Identity is the accountability binding for a run: which agent instance acted, on whose behalf, and under what authority. It is assigned by the DEPLOYMENT, not by the model: the operator sets it at run start from its own auth layer (an IdP, a signed capability grant, a service identity), and it rides the context so every governed action and every sub-agent call inherits it. The SDK anchors and proves the identity CLAIM (these fields, committed in the audit log); it does not authenticate the principal, which is the operator's IdP/PKI, and the attribution is only as strong as custody of whatever key signs the run's tree heads and grants.

The model has no inherent identity. "The agent's identity" is the identity the deployment binds to this run, so a compromised or misconfigured deployment attributes to whatever it claims. That boundary is deliberate and matches the model/governance split: prove the record and the granted authority, do not overclaim the intent behind them.

func IdentityFrom(ctx context.Context) (Identity, bool)

func (i Identity) Empty() bool

type Image ¶

type Image struct {
	Mime string `json:"mime,omitempty"` // MIME type for Data (required when Data is set), e.g. "image/jpeg"; ignored for URL
	Data []byte `json:"data,omitempty"` // raw image bytes; adapters base64-encode. Mutually exclusive with URL.
	URL  string `json:"url,omitempty"`  // hosted image URL. Mutually exclusive with Data.
}

Image is a provider-neutral image input. Exactly one of Data or URL is set (Data XOR URL). For raw bytes, set Data and Mime (e.g. "image/png"); the adapter base64-encodes it (Anthropic base64 source / OpenAI data URI). For a hosted image, set URL and leave Data nil; Mime is not required for URLs. This is an input-only part: models emit text, reasoning, and tool calls, never images, so nothing produces an Image on the response path.

func ImageData(mime string, data []byte) Image

func ImageURL(url string) Image

type Interrupted ¶

type Interrupted struct {
	RunID string
	// RootRunID is the run to re-invoke to continue: the top-level run. It differs from RunID
	// when the signal comes from inside a sub-agent, whose journal is RunID. Record the answer
	// against RunID (Resume, Approve, ResolveHalt, Signal), then run RootRunID with the root agent.
	RootRunID string
	Key       string
	Prompt    any // caller-defined payload for the human: a question, options, current state
}

Interrupted is returned by Run when a tool called Interrupt and no resume value has been recorded for that key yet. The run has paused durably at the interrupt point. Inspect Prompt to decide what to ask the human, record an answer with Resume (same Key), then re-invoke Run with the same runID to continue.

func (e *Interrupted) Error() string

type Leaser ¶

type Leaser interface {
	// AcquireLease claims runID for holder until now+ttl. It returns true if granted (the run is
	// unleased or the live lease is already holder's, which renews it), false if another holder
	// currently holds a live lease. An expired lease is available to any holder.
	AcquireLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
	// RenewLease extends holder's lease on runID, returning false if holder no longer holds it (it
	// expired or was taken). A driver whose work outlasts ttl renews to keep the lease.
	RenewLease(ctx context.Context, runID, holder string, ttl time.Duration) (bool, error)
	// ReleaseLease relinquishes runID if held by holder (a no-op otherwise) so another process can
	// take it immediately rather than waiting for expiry.
	ReleaseLease(ctx context.Context, runID, holder string) error
}

Leaser is the optional capability that coordinates driving a run across processes. Without it, several processes recovering against a shared store all re-drive the same in-flight runs. That is safe but wasteful: side effects stay at-most-once because each non-idempotent call is guarded by an exclusive attempt claim (ClaimAttempt), but the drivers duplicate model calls and a loser of a claim halts with ResumeHalt. A store that implements Leaser lets a driver take a time-bounded lease on a run so normally only the holder drives it; a dead holder's lease expires and another process takes over, which is the high-availability property. Recover uses it automatically when the store provides it. A lease is an efficiency and liveness mechanism, not the safety one: no lease can guarantee mutual exclusion against a holder that stalls past its TTL, which is why the claim, not the lease, is what keeps side effects at-most-once.

The base Durable contract does not require leasing, and MemStore's implementation is in-process (for tests and as the reference); the cross-process payoff is a shared backend (store/postgres) implementing this with an atomic upsert over a leases table.

type Lister ¶

type Lister interface {
	// Runs returns the IDs of every run the store holds, in no guaranteed order.
	Runs(ctx context.Context) ([]string, error)
}

Lister is the optional capability a crash-recovery supervisor needs: it enumerates the runs a store knows about, so Recover can find in-flight runs to re-drive after a restart. The base Durable interface intentionally does NOT require it: memoization (Do) and replay (History) are the crash-safety core, and enumeration is a separate, backend-specific concern (a SQL store lists with a query; a sharded store may not enumerate cheaply at all). A store opts in by implementing Runs; Recover finds it with Capability, so a wrapper that implements Unwrap keeps its inner store's Lister.

type MemStore ¶

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

MemStore is an in-memory Durable for tests and local dev. SQLite is the shipping default; store/postgres is the high-availability backend.

It keeps each record as its journal encoding (EncodeRecord) and decodes on every read, the same way the SQL stores do. So a record a caller gets back is always an independent copy (modifying it cannot change the journal), and Do hands back the record a replay reads, on the live path too, which keeps tests on MemStore faithful to SQLite and Postgres. (Do that writes a record hands back the decoding EncodeRecord's round trip already made, when that is the stored bytes' decoding, rather than decode the same bytes twice.)

func NewMemStore() *MemStore

func (m *MemStore) AcquireLease(_ context.Context, runID, holder string, ttl time.Duration) (bool, error)

func (m *MemStore) Do(ctx context.Context, runID, name string, fn func(context.Context) (Record, error)) (Record, error)

func (m *MemStore) History(_ context.Context, runID string) ([]Record, error)

func (m *MemStore) ReleaseLease(_ context.Context, runID, holder string) error

func (m *MemStore) RenewLease(_ context.Context, runID, holder string, ttl time.Duration) (bool, error)

func (m *MemStore) Runs(_ context.Context) ([]string, error)

type MemWaker ¶

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

MemWaker is an in-process Waker: it holds pending timers and, when Fire is called with the current time (or via a Start ticker), resumes every run whose timer is due by calling the resume function it was built with. resume is how the deployment re-invokes a run, typically agent.Run(ctx, runID, savedInput); a resumed run whose wait is over proceeds, and one that sleeps again re-registers a new wake here. MemWaker is a reference and a local-dev default, not a durable scheduler: a process exit loses its in-memory timer set, so the wake times must also live in the durable journal (they do, Sleep journals them), and a restarted deployment rebuilds pending wakes by scanning runs, or an external scheduler owns the trigger.

func NewMemWaker(resume func(ctx context.Context, runID string) error) *MemWaker

func (w *MemWaker) Fire(ctx context.Context, now time.Time) (int, error)

func (w *MemWaker) Schedule(runID, name string, fireAt time.Time)

func (w *MemWaker) Start(ctx context.Context, every time.Duration, onError func(error)) <-chan struct{}

type Message ¶

type Message struct {
	Role  Role
	Parts []Part
}

Message is one turn. Its content is a sequence of typed Parts (NOT a flat string), so reasoning/thinking parts (which Anthropic requires echoed back across turns), tool calls, tool results, and image inputs all survive round-trips intact. This is the provider-neutral type; adapters translate to/from provider wire formats.

func SystemText(s string) Message

func UserParts(parts ...Part) Message

func UserText(s string) Message

func (m Message) MarshalJSON() ([]byte, error)

func (m Message) Text() string

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

type Middleware ¶

type Middleware func(ModelHandler) ModelHandler

Middleware wraps a ModelHandler — the net/http-style func(Handler) Handler chain, at the SEMANTIC layer (it sees messages, tool calls, token usage — not bytes). Batteries live in the middleware/ package (Retry, RateLimit, Cost, ...).

func WithRetrieval(r Retriever, k int) Middleware

type Model ¶

type Model interface {
	Stream(ctx context.Context, req Request) (*Stream, error)
}

Model is the provider primitive. Streaming is FIRST-CLASS: Stream is the only method an adapter must implement. Generate is a convenience drain built on top — the opposite of frameworks that make blocking generation primary and bolt streaming on later.

func Replay(ctx context.Context, source Durable, runID string) (Model, error)

type ModelCallHook ¶ added in v0.8.0

type ModelCallHook struct {
	// Before runs before the request is sent, with the request's context. An error fails the
	// call without sending it.
	Before func(ctx context.Context) error
	// After runs once a sent request has ended, successfully or not, with the usage it reported:
	// for a failed request, the part reported before it failed.
	After func(u Usage)
}

ModelCallHook runs around each request the agent's model handler sends to a model: every retried attempt and every hedged target, wherever the middleware that installed it sits in the chain. Middleware whose effect belongs to requests actually sent, rather than to calls through it, uses one: RateLimit waits for a token in Before, Cost counts spend in After.

type ModelEvent ¶

type ModelEvent struct{ Event Event }

ModelEvent forwards one live model stream Event (TextDelta, ReasoningDelta, ToolCallDelta, Finish) from the current turn — the token-by-token feed. Emitted only for a FRESH model call; on durable replay the turn is reused from the journal and produces no deltas (an AssistantTurn with Replayed=true is emitted instead). When the turn's model call starts over (see TurnRestarted), the deltas before it are not part of the recorded turn.

type ModelHandler ¶

type ModelHandler func(context.Context, Request) (Message, Usage, error)

ModelHandler generates one assistant turn. Middleware wraps it.

type ModelInfo ¶ added in v0.8.0

type ModelInfo struct {
	Provider       string
	Model          string
	ResponseFormat bool
}

ModelInfo identifies a Model. Provider names the API it calls ("anthropic", "openai", "gemini"), Model is the provider's model ID the requests name, and ResponseFormat reports whether the Model honours Request.ResponseFormat (a Model that does not fails a request that sets it, rather than drop the constraint).

func ModelInfoOf(m Model) (ModelInfo, bool)

type Part ¶

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

Part is a single piece of message content. Concrete parts: Text, Reasoning, ToolUse, ToolResult, Image.

type PendingApproval ¶

type PendingApproval struct {
	RunID string
	// RootRunID is the run to re-invoke to continue: the top-level run. It differs from RunID
	// when the signal comes from inside a sub-agent, whose journal is RunID. Record the answer
	// against RunID (Resume, Approve, ResolveHalt, Signal), then run RootRunID with the root agent.
	RootRunID string
	ToolUseID string
	ToolName  string
	Args      json.RawMessage
	// Quorum is non-nil for an m-of-n gate: the running tally at the pause. Record
	// decisions with ApproveAs, then re-run.
	Quorum *ApprovalTally
}

PendingApproval is returned by Agent.Run when a tool requiring human approval has no recorded decision yet. The run has paused durably; call Approve then re-run to resume.

func (e *PendingApproval) Error() string

func (e *PendingApproval) Subject() ApprovalSubject

sig := signer.Sign(agent.ApprovalDecisionBytes(pend.Subject(), "finance", true))

type RateLimited ¶

type RateLimited struct {
	RetryAfter time.Duration
	Message    string // the provider's error message, if it sent one
	Err        error
}

RateLimited is returned by a provider adapter when it is rate limited (HTTP 429 that is not an exhausted quota; see ClassifyHTTPError). It carries an optional RetryAfter hint from the Retry-After response header or the provider's own retry delay (0 means no hint was provided), and the provider's error message. It wraps the caller-supplied Err (typically wrapping ErrModel) so errors.Is(err, ErrModel) holds.

func (e *RateLimited) Error() string

func (e *RateLimited) Unwrap() error

type Reasoning ¶

type Reasoning struct {
	Text      string `json:"text"`
	Signature string `json:"signature,omitempty"`
	Redacted  string `json:"redacted,omitempty"`
}

Reasoning is model thinking. Signature is the provider's opaque token that must be echoed back on later turns (Anthropic extended thinking); dropping it corrupts the conversation — which is exactly why Content can't be a flat string.

Redacted holds reasoning the provider returned encrypted (Anthropic redacted_thinking data), which must also go back unchanged; Text and Signature are empty when it is set. Each thinking block is its own Reasoning part, in the order the model produced them.

type ReasoningDelta ¶

type ReasoningDelta struct {
	Text      string
	Signature string // opaque provider token to echo back on later turns (Anthropic thinking)
	Redacted  string // encrypted reasoning to echo back unchanged (Anthropic redacted_thinking)
}

ReasoningDelta is a fragment of model thinking. A Signature ends the thinking block it belongs to, so the next ReasoningDelta starts a new Reasoning part. Redacted carries a whole encrypted block (Anthropic redacted_thinking), which becomes a Reasoning part of its own.

type Received ¶

type Received[T any] struct {
	Key     string
	Payload T
}

Received is one message pulled from a channel.

func Receive[T any](ctx context.Context, channel string) (Received[T], error)

type Record ¶

type Record struct {
	Name    string   `json:"name"`
	Kind    StepKind `json:"kind"`
	Message *Message `json:"message,omitempty"` // StepModel
	// Usage is token usage. On a StepModel record, the call's. On a StepToolResult or StepSagaFail
	// record, the Usage of the runs the tool call started (sub-agents): their recorded responses.
	Usage *Usage `json:"usage,omitempty"`
	// DiscardedUsage is billed usage no recorded response carries. On a StepModel record, the
	// turn's other model requests: failed attempts a middleware retried, losing hedge targets. On
	// a StepValue record named "@spend/<n>", a model call that failed for good. On a
	// StepToolResult or StepSagaFail record, the rest of the Spend of the runs the tool call
	// started. Nil when there was none. WithTokenBudget counts it.
	DiscardedUsage *Usage          `json:"discarded_usage,omitempty"`
	ToolUseID      string          `json:"tool_use_id,omitempty"` // StepToolResult
	Result         json.RawMessage `json:"result,omitempty"`      // StepToolResult / StepValue
	IsError        bool            `json:"is_error,omitempty"`    // StepToolResult
	Approved       bool            `json:"approved,omitempty"`    // StepApproval
	Approver       string          `json:"approver,omitempty"`    // StepApproval written by ApproveAs
	Signature      []byte          `json:"signature,omitempty"`   // StepApproval written by ApproveAs
	// AttemptedAt is the Unix-millis wall-clock time an attempt marker (StepAttempt) was
	// written, i.e. just before a non-retriable side effect fired. It is set once and read
	// back verbatim on replay, so it stays deterministic. Zero (and omitted) on every
	// other kind; a reconciler uses it to honor a grace period before resolving a halt.
	AttemptedAt int64 `json:"attempted_at,omitempty"`
	// Reconciled marks a StepToolResult that ResolveHalt injected from verified evidence
	// rather than one the tool produced by running. It lets a later reader (and bide-audit)
	// tell a reconciled outcome from a clean one at a glance.
	Reconciled bool `json:"reconciled,omitempty"`
	// ReadOnly marks a StepToolResult for a call whose tool was declared ReadOnly when the call
	// ran. A saga rollback skips such a call (it changed nothing) and treats any other completed
	// call as a write, whatever the tool is declared as by the time the rollback runs. A result
	// that ResolveHalt injected is never ReadOnly: only a call that was not retry-safe halts.
	ReadOnly bool `json:"read_only,omitempty"`
	// Evidence is what a reconciler read to decide the outcome (a queried provider record,
	// a message id, a log line). It is carried on the reconciled result and signed with it,
	// so the verdict and its basis live in the journal beside the outcome.
	Evidence json.RawMessage `json:"evidence,omitempty"`
	// Claim is the random id of the driver that wrote an attempt marker (see ClaimAttempt).
	// A driver runs the side effect only if the marker it gets back carries its own claim, so
	// two drivers of the same run can never both run it, whatever their leases say.
	Claim string `json:"claim,omitempty"`
	// Salt is SaltSize random bytes a store sets when it first journals the record (see
	// JournalEntry), replacing any salt the step returned. It is persisted with the record and
	// read back verbatim, so it is stable across replay and across stores. It has no meaning to
	// the run; the audit trail needs it. An audit leaf commits to the record's journal encoding,
	// salt included, and an inclusion proof for one record carries its neighbours' leaf hashes, so
	// without the salt anyone holding a proof could confirm a guessed neighbour (an approval, a
	// small tool result) by hashing it. The salt is disclosed only with its own record.
	Salt []byte `json:"salt,omitempty"`
}

Record is one durably-recorded, named event. The ordered sequence of Records for a run is its full, replayable history; resume rebuilds state by replaying them. Name is the stable identity used for memoization (see Durable.Do).

func ClaimAttempt(ctx context.Context, d Durable, runID, name string, rec Record) (won bool, got Record, err error)

func DecodeRecord(b []byte) (Record, error)

func DecodeStoredRecord(runID, name string, b []byte) (Record, error)

type RecoverOption ¶

type RecoverOption func(*recoverConfig)

RecoverOption configures Recover. Lease options apply only when the store implements Leaser.

func WithLeaseHolder(id string) RecoverOption

func WithLeaseTTL(d time.Duration) RecoverOption

func WithRecoverConcurrency(n int) RecoverOption

func WithRecoverErrors(fn func(error)) RecoverOption

func WithRecoverInterval(d time.Duration) RecoverOption

type Request ¶

type Request struct {
	Messages       []Message
	Tools          []Tool
	Sampling       Sampling        // generation controls; zero value = provider/model defaults
	ResponseFormat *ResponseFormat // nil = free-form; set = constrain output to a JSON schema
	ToolChoice     *ToolChoice     // nil = provider default (auto); see ToolChoice
}

Request is a single model call.

type ResolveOption ¶ added in v0.3.0

type ResolveOption func(*resolveConfig)

ResolveOption configures ResolveHalt.

func WithEvidence(v any) ResolveOption

func WithMinHaltAge(d time.Duration) ResolveOption

func WithNow(now func() time.Time) ResolveOption

type ResponseFormat ¶

type ResponseFormat struct {
	Name   string
	Schema json.RawMessage
}

ResponseFormat asks the provider to constrain the model's output to a named JSON schema (OpenAI structured outputs / "json_schema" response format). An adapter that does not support it (Anthropic) fails the request with ErrConfig rather than drop the constraint. Name is the schema name; Schema is provider-neutral JSON Schema (as from the schema package). See RunTypedNative.

type Result ¶

type Result struct {
	// Message is the final assistant answer, identical to what Run / RunSaga return.
	Message Message

	// Usage is the sum of the usage of the model responses the run recorded, one per turn
	// (input, output, and cache tokens). It is the whole run's, read from the journal: the same
	// whether the run finished in one invocation or was resumed after a crash, and the same again
	// when a finished run is re-entered.
	Usage Usage

	// Spend is every token the run's model requests used: Usage plus the usage of requests whose
	// responses were discarded (failed attempts a middleware retried, losing hedge targets) and of
	// model calls that failed. It is what the provider bills, and what WithTokenBudget counts.
	// Like Usage it is the whole run's, from the journal (see Record.DiscardedUsage).
	Spend Usage

	// Turns is the number of live model turns this invocation executed. Turns replayed from
	// the journal are not counted: unlike Usage and Spend, it describes this invocation.
	Turns int

	// Duration is the wall-clock elapsed time for the run (from entry to return).
	Duration time.Duration

	// RunID echoes the run identifier passed to RunResult / RunSagaResult.
	RunID string
}

Result is a rich envelope returned by RunResult and RunSagaResult. It carries the terminal assistant message plus telemetry accumulated over the whole run: total token usage (sum of every model-call Usage), the number of model turns, wall-clock duration, and the run ID.

Run and RunSaga are unchanged and remain the idiomatic path for callers that only need the final message; RunResult / RunSagaResult are the additive counterparts for callers that need observability data.

type ResumeHalt ¶

type ResumeHalt struct {
	RunID string
	// RootRunID is the run to re-invoke to continue: the top-level run. It differs from RunID
	// when the signal comes from inside a sub-agent, whose journal is RunID. Record the answer
	// against RunID (Resume, Approve, ResolveHalt, Signal), then run RootRunID with the root agent.
	RootRunID string
	ToolUseID string
	ToolName  string
	// AttemptedAt is when the effect was attempted (the attempt marker's timestamp), zero
	// if unknown (including a marker stamped zero or negative, see markerTime). A reconciler uses it to honor a grace period before resolving (see
	// ResolveHalt with WithMinHaltAge) so it does not query the provider before its record
	// has settled.
	AttemptedAt time.Time
}

ResumeHalt is returned when resume can't safely proceed: a non-retriable tool was invoked but no result was recorded, so its outcome is unknown. The run stops for confirmation rather than risk a double side effect (e.g. a double charge).

It is also returned when another driver of the same run claimed the call first (see ClaimAttempt), for example a second node that took over after this node's lease lapsed. That driver owns the side effect; once it records the result, re-running proceeds normally.

func (e *ResumeHalt) Error() string

type RetrievalOption ¶ added in v0.8.0

type RetrievalOption func(*retrievalToolConfig)

RetrievalOption configures a RetrievalTool.

func RetrievalDescription(description string) RetrievalOption

func RetrievalName(name string) RetrievalOption

type Retriever ¶

type Retriever interface {
	Retrieve(ctx context.Context, query string, k int) ([]Doc, error)
}

Retriever is the bring-your-own-RAG port: given a query, return the top-k relevant documents from YOUR store (pgvector, Pinecone, a file index — anything). Bide ships no vector store and no embedder; you implement Retrieve against infrastructure you already run, and wire it in with RetrievalTool (agentic — the model searches on demand) or WithRetrieval (classic — top-k auto-injected as context on each user turn). Sessions already give conversational memory; this is the seam for semantic / long-term memory.

Retrieve must be safe for concurrent use: parallel tool calls in one turn, concurrent runs on one Agent, and sub-agents sharing a Retriever call it at once.

type Role ¶

type Role string

Role identifies the author of a Message.

const (
	RoleSystem    Role = "system"
	RoleUser      Role = "user"
	RoleAssistant Role = "assistant"
	RoleTool      Role = "tool"
)

type RunStart ¶ added in v0.8.0

type RunStart struct {
	Input string `json:"input"`
	Saga  bool   `json:"saga,omitempty"`
}

RunStart is how a run was started, as its first drive records it: the input it answers (for a Session turn, the turn's message) and whether it runs as a saga (RunSaga, StreamSaga, RunSagaResult, or a sub-agent called inside a saga). A run's model turns and tool calls answer that input under that entry point's rules, so every later drive is held to it: resuming an unfinished run with another input, or through the other entry point (Run for a saga, RunSaga for a run), is ErrConfig. A finished run returns its recorded answer whatever it is passed, as before.

A run whose earlier drives predate this record gets it on its first drive under this version, with the input and entry point that drive is given.

func RecordedStart(ctx context.Context, d Durable, runID string) (RunStart, bool, error)

start, ok, err := agent.RecordedStart(ctx, store, runID)
if err != nil {
    return err
}
if !ok {
    start = startFor(runID) // the deployment's own record, for a run not driven under this version
}
if start.Saga {
    _, err = a.RunSaga(ctx, runID, start.Input)
} else {
    _, err = a.Run(ctx, runID, start.Input)
}

type Safety ¶

type Safety struct {
	// ReadOnly: no external side effects — always safe to re-run.
	ReadOnly bool
	// Idempotent: mutates state but is safe to retry, because a repeat with the same
	// key is a no-op downstream. Set IdempotencyKey to make that concrete.
	Idempotent bool
	// IdempotencyKey derives a stable key from the args so a retried call can be
	// de-duplicated. Empty result => not derivable.
	IdempotencyKey func(args json.RawMessage) string
	// RequiresApproval pauses the run for a durable human decision (HITL) before the
	// tool executes — surfaced as *PendingApproval; resume after agent.Approve.
	RequiresApproval bool
	// Approval, when non-nil, upgrades the approval gate from one
	// decision to an m-of-n human gate over a bounded, named set of
	// approvers. nil = the existing 1-of-1 RequiresApproval behavior.
	Approval *ApprovalPolicy
}

Safety declares how a tool may be retried when a run resumes after a crash and the call's outcome is unknown (it was invoked, but no result was journaled). Replaces a coarse Read/Write flag. For a trusted MCP server, its tool annotations (readOnlyHint / idempotentHint) map onto it (see mcp.TrustAnnotations).

func ToolSafety(ctx context.Context) (s Safety, ok bool)

func (s Safety) RetrySafe() bool

type SagaAborted ¶

type SagaAborted struct {
	RunID         string
	Cause         error
	Compensated   []string
	Uncompensated []string
	CompensateErr error
}

SagaAborted is returned by RunSaga when a step failed and the transaction was rolled back. Compensated lists tools whose side effects were undone (reverse of execution, including sub-agent trees). Uncompensated lists completed WRITES that had no compensator — dangling side effects needing manual cleanup. CompensateErr is non-nil if a compensator itself failed: rollback stopped, so writes before it remain uncompensated.

func (e *SagaAborted) Error() string

func (e *SagaAborted) Unwrap() error

type Sampling ¶

type Sampling struct {
	Temperature *float64 // 0..2 (OpenAI) / 0..1 (Anthropic); determinism at 0
	TopP        *float64 // nucleus sampling
	MaxTokens   *int     // cap on generated tokens; overrides the adapter's construction default
	Stop        []string // stop sequences
	Seed        *int64   // best-effort determinism (OpenAI; ignored where unsupported)
}

Sampling holds provider-neutral generation controls. Pointer fields distinguish "unset" (nil → use the provider/model default) from an explicit value — so a deliberate Temperature of 0 is not confused with "not specified". Each adapter maps the set fields onto its wire format and ignores those it doesn't support (e.g. Anthropic has no Seed). Set it once with Agent.WithSampling.

type SamplingOption ¶

type SamplingOption func(*Sampling)

SamplingOption sets one field of the Sampling config; see Temperature, TopP, MaxTokens, Stop, Seed.

func MaxTokens(v int) SamplingOption

func Seed(v int64) SamplingOption

func Stop(seqs ...string) SamplingOption

func Temperature(v float64) SamplingOption

func TopP(v float64) SamplingOption

type ScriptedModel ¶

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

ScriptedModel is a deterministic, LLM-free Model that replays a fixed script of turns, one turn per model call. It is the batteries-included version of the model fakes people otherwise reverse-engineer from ToolCallDelta + Finish for tests, examples, and local dev, so you can drive the whole agent loop offline.

It is replay-safe: it selects the turn to emit by counting the assistant messages already in the request, not by an internal cursor. On a durable resume the agent loop replays journaled assistant turns without calling the model, so a cursor would drift; counting the transcript instead lines the script back up with the live turn every time, including after a crash and re-run. Once the script is exhausted it repeats its last turn, so an over-long conversation does not panic.

Build turns with ToolTurn, TextTurn, and ErrorTurn:

m := agent.NewScriptedModel(
    agent.ToolTurn("call-1", "lookup", `{"q":"weather"}`),
    agent.TextTurn("it is sunny"),
)
a := agent.New(m, agent.NewMemStore(), lookupTool)
out, err := a.Run(ctx, "run-1", "what's the weather?")

A ScriptedModel is safe for the sequential agent loop; it is not intended for concurrent Stream calls from multiple runs at once.

func NewScriptedModel(turns ...ScriptedTurn) *ScriptedModel

func (m *ScriptedModel) Stream(_ context.Context, req Request) (*Stream, error)

type ScriptedTurn ¶

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

ScriptedTurn is one scripted model output. Construct one with ToolTurn, TextTurn, or ErrorTurn rather than building it directly.

func ErrorTurn(err error) ScriptedTurn

func TextTurn(text string) ScriptedTurn

func ToolTurn(id, name, args string) ScriptedTurn

type Session ¶

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

Session is a durable multi-turn conversation. Each Send is one full agent run (tools, resume, side-effect safety and all), seeded with the transcript so far — so the agent remembers earlier turns. The transcript is journaled turn-by-turn in the session's journal, so a Session reloaded (after a restart) from the same store resumes the conversation.

Layering: a turn runs under its own run ID ("<id>>@turn/<n>" for Send, "<id>>@event/<key>" for SendOnce, the key encoded), whose durable journal handles crash resume WITHIN the turn; the session's journal, "<id>>@session", records which message started each Send turn and each completed turn's (input, answer) so the transcript can be rebuilt. A root run ID may not contain '>', so no run started with Run shares a journal with a session, and IsSessionRun tells a session's run IDs apart from every other. Recover skips them: a turn is seeded with the transcript before it, which only the session holds, and its answer is recorded only by the session, so an unfinished turn resumes when its message is sent again (the same Send, or the redelivered SendOnce). Intermediate tool calls stay in the turn's journal and are NOT carried into later turns — the conversational memory is the question/answer transcript, not every tool call. Each turn also journals the transcript it started from (as "from/<turn run>"), so a turn resumed after a crash is seeded with exactly the turns its earlier model calls saw, even if other messages were answered in between.

A turn belongs to the message that started it: while a Send turn is unfinished, Send with a different message is ErrConfig rather than resuming that turn. Several handles on one session (a stale handle, or two workers) never lose a turn or answer one message with another's reply; a handle that finds the journal moved on reloads it.

A Session is safe for concurrent use: callers sharing one handle behave as callers on separate handles do, and their turns run in parallel.

func (s *Session) History() []Message

func (s *Session) Send(ctx context.Context, input string) (Message, error)

func (s *Session) SendOnce(ctx context.Context, key, input string) (Message, error)

func (s *Session) Turns() int

type Sleeping ¶

type Sleeping struct {
	RunID string
	// RootRunID is the run to re-invoke to continue: the top-level run. It differs from RunID
	// when the signal comes from inside a sub-agent, whose journal is RunID. Record the answer
	// against RunID (Resume, Approve, ResolveHalt, Signal), then run RootRunID with the root agent.
	RootRunID string
	Name      string
	FireAt    time.Time
}

Sleeping is returned by Run when a tool called Sleep or WaitUntil and the wake time has not yet passed. The run has paused durably at the timer: its wake time is journaled, so the pause survives a restart. Re-invoke Run with the same runID at or after FireAt to resume (a Waker does this automatically; otherwise the deployment re-invokes on its own schedule).

func (e *Sleeping) Error() string

type StepKind ¶

type StepKind string

StepKind records what a journal entry represents.

const (
	StepModel      StepKind = "model"       // an assistant message from the model
	StepToolResult StepKind = "tool_result" // a completed tool call + its result
	StepValue      StepKind = "value"       // a user-authored durable step (see Step[T])
	StepSignal     StepKind = "signal"      // an external event delivered into a run (see Signal/Await)
	StepApproval   StepKind = "approval"    // a durable human approve/deny decision (HITL)
	StepAttempt    StepKind = "attempt"     // "about to run a non-retriable side effect" marker
	StepSagaFail   StepKind = "saga_fail"   // a saga step failed → durable abort trigger
	// StepNotStarted records that the attempt whose marker it names never called its side
	// effect, written by the driver that claimed it (see attempt.go). That attempt then no
	// longer halts a resume, and the effect is re-attempted under a new marker.
	StepNotStarted StepKind = "not_started"
)

type StepOption ¶ added in v0.6.0

type StepOption func(*stepConfig)

StepOption configures Step.

func StepSafety(s Safety) StepOption

type Stream ¶

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

Stream is a live model response. Range over Events() for a streaming UI, OR call Message() to drain it into the fully-assembled assistant Message — not both (a Stream is consumed once).

A consumer that stops early releases the producer: breaking out of Events() does it, and so does Close. Cancelling the context passed to Model.Stream also releases it.

func NewStream(ch <-chan Emit) *Stream

func NewStreamFunc(ctx context.Context, produce func(send func(Emit) bool)) *Stream

func (s *Stream) Close()

func (s *Stream) Events() iter.Seq2[Event, error]

func (s *Stream) Message() (Message, Usage, error)

type Task ¶

type Task[T any] struct {
	Name string
	Fn   func(context.Context) (T, error)
	// Safety declares whether the task may re-run after a crash, as StepSafety does for a Step.
	// The zero value treats the task as a side effect: it runs at most once, and a crash after
	// its effect halts the resumed call with *ResumeHalt. Mark a check or a lookup ReadOnly.
	Safety Safety
}

Task is one unit of durable parallel work: a named step returning a T. Name is the durable memoization key within the run, so it must be unique across the tasks in one Parallel call. Because each task is a journaled step, a resumed run returns a completed task's recorded result without re-running it, and that result is an independently provable record (see audit.ProveStep).

type Text ¶

type Text struct {
	Text string `json:"text"`
}

Text is plain assistant/user text.

type TextDelta ¶

type TextDelta struct{ Text string }

type Tool ¶

type Tool interface {
	Name() string
	Description() string
	// ArgsSchema is the provider-NEUTRAL argument schema. The schema/ package emits
	// per-provider dialects (OpenAI-strict / Gemini / Anthropic) from it — so this is
	// never a single frozen blob handed straight to a provider.
	ArgsSchema() json.RawMessage
	// Safety declares how the tool may be retried on resume.
	Safety() Safety
	Call(ctx context.Context, args json.RawMessage) (json.RawMessage, error)
}

Tool is an action the agent can take. The interface is untyped (json.RawMessage) so heterogeneous tools share one type — including runtime MCP tools whose schema is only known at runtime and can't be a Go struct. Native tools get compile-time typing via Func (below); that's the primary ergonomic.

func CompensatedFunc[In, Out any](
	name, description string,
	safety Safety,
	do func(context.Context, In) (Out, error),
	undo func(context.Context, In, Out) error,
) Tool

func Func[In, Out any](name, description string, safety Safety, fn func(context.Context, In) (Out, error)) Tool

func RetrievalTool(r Retriever, k int, opts ...RetrievalOption) Tool

// Your store, behind the Retriever port (here a trivial in-memory one).
docs := map[string]string{"france": "Paris is the capital of France."}
r := retrieverFunc(func(_ context.Context, query string, _ int) ([]Doc, error) {
	if d, ok := docs[strings.ToLower(query)]; ok {
		return []Doc{{Text: d}}, nil
	}
	return nil, nil
})

tool := RetrievalTool(r, 1)
out, _ := tool.Call(context.Background(), json.RawMessage(`{"query":"france"}`))
fmt.Println(string(out))

Output:
[{"text":"Paris is the capital of France."}]

func SubAgent(name, description string, sub *Agent) Tool

type ToolCallDelta ¶

type ToolCallDelta struct {
	Index        int
	ID           string
	Name         string
	ArgsFragment json.RawMessage
	Signature    string // opaque provider token for this call, kept on ToolUse.Signature (Gemini thoughtSignature)
}

ToolCallDelta is an incremental fragment of a tool call, keyed by Index. Fragments are concatenated and gated by json.Valid before use (the UTF-8/partial-JSON safety the research flagged as universally missing).

type ToolChoice ¶

type ToolChoice struct {
	Mode string // "", "auto", "none", "required", or "tool"
	Name string // tool name to force; only meaningful when Mode == "tool"
}

ToolChoice controls whether and how the model may call tools on a request. Mode is one of "" or "auto" (model decides, the default), "none" (never call a tool), "required" (must call some tool), or "tool" (must call the specific tool named in Name). A nil *ToolChoice on a Request means the provider default (auto).

CAVEAT: in the multi-turn agent loop, forcing "required" or "tool" on EVERY turn prevents the model from ever emitting a final text answer, so the loop never terminates. Those two modes are intended for single-turn or typed/structured calls where exactly one tool round-trip is expected. Use "auto" (the default) for the loop.

type ToolCompleted ¶

type ToolCompleted struct {
	ToolUseID string
	Name      string
	Result    json.RawMessage
	IsError   bool
}

ToolCompleted carries a tool call's result. Emitted for live executions, for a human-denied call, and for each result reconstructed from the journal on resume.

type ToolHandler ¶

type ToolHandler func(context.Context, ToolUse) (json.RawMessage, error)

ToolHandler executes one tool call: given the ToolUse (ID, Name, Args), it returns the raw JSON result or an error. It is the tool-side analogue of ModelHandler.

type ToolMiddleware ¶

type ToolMiddleware func(ToolHandler) ToolHandler

ToolMiddleware wraps a ToolHandler — the same func(Handler) Handler idiom as model Middleware, but around TOOL execution. First added = outermost. A middleware can:

• observe/log/trace a call (its name, args, duration, error);
• MUTATE the outgoing args (validate, redact, inject defaults) by calling next with a modified ToolUse;
• transform the result before it is journaled;
• SHORT-CIRCUIT — return a result (a cache hit) or an error (a policy denial) WITHOUT calling next, so the tool never runs.

A middleware that may call next more than once (a retry) or not at all (a cache) must check the tool's Safety first, with ToolSafety(ctx): repeating or skipping a side effect is not its call to make. The agent enforces the first half itself: a tool that is not RetrySafe runs at most once per tool call, and a second call to next for it returns ErrToolReinvoked without running the tool.

The chain runs INSIDE the durable, memoized step, so a short-circuit result or a transformed result is what gets journaled — resume replays it and never re-runs the middleware or the tool. Batteries live in the middleware/ package (ToolLog, ToolCache).

type ToolResult ¶

type ToolResult struct {
	ToolUseID string          `json:"tool_use_id"`
	Result    json.RawMessage `json:"result,omitempty"`
	IsError   bool            `json:"is_error,omitempty"`
}

ToolResult carries a tool's output back to the model (tool turn).

type ToolStarted ¶

type ToolStarted struct {
	ToolUseID string
	Name      string
	Args      json.RawMessage
}

ToolStarted fires when a tool call begins executing: after any approval gate and, for non-idempotent tools, after the durable attempt marker is written, immediately before the tool is called. A call that does not start (cancelled after its attempt marker and before the call, and recorded as not started) emits neither ToolStarted nor ToolCompleted.

type ToolUse ¶

type ToolUse struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Args      json.RawMessage `json:"args,omitempty"`
	Signature string          `json:"signature,omitempty"`
}

ToolUse is the model's request to call a tool (assistant turn). Signature is an opaque provider token bound to this call that must be sent back with it on later turns (a Gemini thoughtSignature); it is journaled with the call, and adapters that have no such token leave it empty and ignore it.

func FindToolCall(recs []Record, toolUseID string) (idx int, call ToolUse, ok bool)

type TurnRestarted ¶ added in v0.8.0

type TurnRestarted struct{ Seq int }

TurnRestarted fires when the model call for turn Seq starts over after an attempt that had already streamed ModelEvent deltas: a middleware such as Retry called the model again after that attempt failed, or delivered a different response in its place. The deltas received since TurnStarted{Seq} (or the previous TurnRestarted) belong to the discarded attempt and are not part of the recorded turn, so a consumer rendering the turn should clear them. Not emitted when the discarded attempt streamed nothing.

type TurnStarted ¶

type TurnStarted struct{ Seq int }

TurnStarted marks the beginning of a fresh model turn (Seq is the model-call sequence number within the run). Not emitted for turns replayed from the journal.

type Usage ¶

type Usage struct {
	// InputTokens is input tokens neither read from nor written to the prompt cache.
	InputTokens  int `json:"input_tokens,omitempty"`
	OutputTokens int `json:"output_tokens,omitempty"`
	// CacheReadTokens is input tokens served from the provider's prompt cache (billed at
	// a discount). CacheWriteTokens is input tokens written to the cache on this call
	// (Anthropic cache creation; 0 for providers that cache implicitly, like OpenAI).
	CacheReadTokens  int `json:"cache_read_tokens,omitempty"`
	CacheWriteTokens int `json:"cache_write_tokens,omitempty"`
}

Usage is token accounting for a call; middleware turns it into cost. The four counts are disjoint, whatever the provider: each input token is counted in exactly one of InputTokens, CacheReadTokens, or CacheWriteTokens, so each is billed once at its own rate and TotalInputTokens is the whole prompt. Providers differ on the wire (Anthropic reports uncached input separately; OpenAI and Gemini report a prompt total that includes cached tokens), and adapters normalize to this form.

func (u Usage) TotalInputTokens() int

func (u Usage) TotalTokens() int

func (u Usage) Validate() error

type Waker ¶

type Waker interface {
	// Schedule registers that runID should be resumed at fireAt, idempotent per (runID, name).
	// runID is the top-level run; name identifies the timer within it (for a timer inside a
	// sub-agent it is qualified by the sub-run, so same-named timers of two sub-agents differ).
	Schedule(runID, name string, fireAt time.Time)
}

Waker is the pluggable trigger that re-invokes a sleeping run when its durable timer is due. Sleep registers a wake with the Waker bound to the run's context (WithWaker); the Waker later calls back to resume the run. The SDK provides the durable, at-most-once timer and its resume safety; what re-invokes the run at the wake time is deployment policy (an in-process loop, a cron, a queue), exactly as the inbound trigger for an event-driven run is (see docs/guides/messaging.md). MemWaker is the reference in-process implementation.