toolcalls

package
v3.0.0-dev.2 Latest Latest
Warning

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

Go to latest
Published: Oct 20, 2026 License: Apache-2.0 Imports: 5 Imported by: 0

Documentation

Overview

Package toolcalls records the tool calls an agent made, as the runtime observed them going past.

It exists for the delegation boundary. A subagent hands its parent prose — `return_result`'s text, or its last assistant turn. Prose cannot be cited, and a parent that is graded on grounding its claims therefore re-issues the reads its child already made. Measured on the GKE drill's OOMKill scenario, whose follow-up asks for a value the child already established AND for the read behind it: 4 of 6 runs re-issued one, and 66% of the bytes the parent read after the handoff were bytes it already had. Afterwards, 0 of 11 (#1014).

Do not read that as a corpus-wide rate. The drill's RBAC scenario asks instead whether the workload is healthy NOW, which no metadata can answer, and it re-reads at the same rate before and after — it should (#1034).

The fix is not a bigger or better-compressed payload. What the parent lacks is PROVENANCE — "the child ran this, with these arguments, and it succeeded" — and provenance is metadata the runtime already sees: every FunctionCall part in the child's event stream. A Recorder collects them so a delegation result can carry what the child DID alongside what it concluded, at roughly a hundred bytes per call against the several thousand a re-read costs. The parent keeps its isolation, because provenance is not payload.

The child is never asked to report on itself. A self-report is another claim in need of evidence; these are observations, and a subagent cannot understate, embellish or forget them.

Index

Constants

View Source
const DefaultMaxArgBytes = 256

DefaultMaxArgBytes bounds the serialized size of one argument value.

Arguments are identifying information — a resource name, a namespace, a path — and at that size they cost almost nothing. But the same field carries a `bash` command line or a file's whole contents, and echoing those back to the parent would reintroduce the payload this package exists to avoid.

View Source
const DefaultMaxCalls = 64

DefaultMaxCalls bounds how many calls one Recorder keeps.

A delegation result is read by a language model with a finite context, and the whole point of this package is to spend fewer tokens than the re-read it replaces; an unbounded list from a runaway subagent would invert that. 64 is comfortably above every archived drill run (the busiest child made 7 calls) and far below the point where the list costs more than it saves.

Variables

This section is empty.

Functions

func Note

func Note(n, truncated int) string

Note is the prose that ships beside a non-empty call list: n recorded, truncated dropped. Empty when there is nothing to describe.

A bare array does not change what a model does with it. That lesson is #710's — spawn_agent's stop_reason enum lost the argument to a well-formed `output` that read like a finished report, and what won it back was a sentence written in language, next to the data, at the moment of the decision. Shipping the calls without this would be shipping the enum without the sentence.

It licenses the re-read that IS warranted. A parent re-running a call to learn whether state has since changed is doing its job; a parent re-running one to obtain something it is already entitled to cite is paying twice for one fact, and only the second is what #1014 measures. Blurring the two would trade a redundancy problem for an ungroundedness problem.

Lives here because both delegation doors need the identical sentence and the packages behind them (pkg/agent, pkg/agent/background) cannot import each other — two copies would drift, and a note that says something subtly different depending on which door a recipe wired is worse than no note.

func ResponseError

func ResponseError(resp map[string]any) string

ResponseError extracts the tool error from an ADK function response, returning "" for a successful call. The reserved key is "error".

A non-string, non-error value under "error" still counts as a failure — a tool that returns a structured error object is failing, and treating an unrecognized shape as success would silently drop exactly the observations this signal exists to make.

Types

type Call

type Call struct {
	// Tool is the tool's registered name.
	Tool string `json:"tool"`
	// Args are the call's arguments, with oversized values shortened
	// (see [DefaultMaxArgBytes]). Presentational and identifying
	// arguments alike are kept: this is a record of what happened, not
	// a normalized key for comparing two calls.
	Args map[string]any `json:"args,omitempty"`
	// Error is the tool's failure text, empty for a call that returned
	// cleanly.
	//
	// It travels with the call because a citation to a call that failed
	// is worse than no citation: it reads as grounding while grounding
	// nothing. The 2026-09-11 drill run is the case — a delegation died
	// on a 429, and a `calls` list that recorded the attempt without
	// recording the failure would have invited the parent to cite it.
	Error string `json:"error,omitempty"`
}

Call is one tool invocation, as observed rather than as reported.

func Append

func Append(dst, src []Call, max int) (out []Call, dropped int)

Append adds src to dst, stopping at max total calls and reporting how many it refused. A negative max is unbounded.

It exists because a per-recorder cap bounds one turn, and the thing that needs bounding is the delegation RESULT — a standing worker runs for hundreds of turns, each individually under the cap.

type Recorder

type Recorder struct {
	// Skip lists tool names to leave out, compared case-insensitively.
	//
	// The caller's own control plane belongs here. In particular the
	// done/return tool: its argument IS the delegation's `output`
	// field, so recording it would ship the same prose twice in one
	// result — the opposite of the saving this package is for.
	Skip []string
	// MaxCalls overrides [DefaultMaxCalls]. Negative means unbounded.
	MaxCalls int
	// MaxArgBytes overrides [DefaultMaxArgBytes]. Negative means
	// values are never shortened.
	MaxArgBytes int
	// contains filtered or unexported fields
}

Recorder accumulates the tool calls in an event stream.

The zero value is usable and applies the package defaults. Not safe for concurrent use — one Recorder belongs to one agent's event loop, which is single-threaded by construction.

func (*Recorder) Calls

func (r *Recorder) Calls() []Call

Calls returns the recorded calls in the order they were observed.

func (*Recorder) Dropped

func (r *Recorder) Dropped() int

Dropped returns how many calls were seen past Recorder.MaxCalls and therefore not recorded.

func (*Recorder) Observe

func (r *Recorder) Observe(ev *session.Event)

Observe records any tool calls and tool outcomes carried by ev.

Partial events are ignored. A streaming provider emits a function call as chunks and then again as one consolidated part, so counting partials would report a single call several times — the same discipline the text collectors in pkg/agent and pkg/agent/autonomous follow, and for the same reason.

Jump to

Keyboard shortcuts

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