The highest tagged major version is
Documentation
¶
Overview ¶
Package runner drives the agent through a real conversation — either a single one-shot prompt (Headless) or a multi-turn stdin REPL (REPL). Both share an Agent under the hood and route partial text + tool-call summaries through the same streaming consumer.
Index ¶
- Constants
- func Headless(ctx context.Context, m adkmodel.LLM, prompt string, stdout, stderr io.Writer, ...) (int, error)
- func IsTerminal(w io.Writer) bool
- func REPL(ctx context.Context, m adkmodel.LLM, stdin io.Reader, stdout, stderr io.Writer, ...) (int, error)
- func WriteEvents(events iter.Seq2[*session.Event, error], out, info io.Writer, ...) error
- func WriteSummary(w io.Writer, t *usage.Tracker, modelID string)
- type EventsOption
Constants ¶
const ( ExitOK = 0 ExitAgentError = 1 ExitConfigError = 2 )
Exit codes — kept distinct so CI can disambiguate failure modes.
Variables ¶
This section is empty.
Functions ¶
func Headless ¶
func Headless(ctx context.Context, m adkmodel.LLM, prompt string, stdout, stderr io.Writer, tracker *usage.Tracker, pricing usage.Pricing, agentOpts []agent.Option, eventsOpts ...EventsOption) (int, error)
Headless executes prompt against m and streams the assistant's text to stdout as partial events arrive. Tool-call summaries are written to stderr as one line per call. Returns an exit code suitable for os.Exit.
agentOpts lets the caller pass extra agent.Options (typically WithTools, WithToolsets, WithSystemInstructionPrefix). Pass nil for no tools and the default instruction.
tracker (optional) records per-turn usage; when supplied, the caller can write a summary using its totals after Headless returns. Pass nil to skip accounting.
eventsOpts forwards through to WriteEvents (e.g. WithColor) so callers can opt into ANSI styling without reaching into the formatter directly.
A trailing newline is always added to stdout when at least one chunk was written, so shell pipelines see a clean terminator.
func IsTerminal ¶
IsTerminal reports whether w is connected to a terminal (TTY). Use to gate WithColor: pass WithColor(IsTerminal(os.Stdout)) so color renders interactively but not when output is captured to a file or piped to another process.
Returns false for any writer that isn't a *os.File (buffers, pipes, network connections). On Unix and modern Windows, character devices report ModeCharDevice; that's the signal we trust.
func REPL ¶
func REPL(ctx context.Context, m adkmodel.LLM, stdin io.Reader, stdout, stderr io.Writer, tracker *usage.Tracker, pricing usage.Pricing, agentOpts []agent.Option, eventsOpts ...EventsOption) (int, error)
REPL drives a multi-turn stdin loop against m. Each line is sent through the same Agent so the ADK runner accumulates conversation history across turns (the in-memory session service appends events per session ID, which the Agent reuses).
Prompts are written to stdout, partial assistant text streams back inline, and tool-call summaries go to stderr — same shape as Headless. Built-in commands: `/exit`, `/quit`, EOF (Ctrl-D).
agentOpts mirrors Headless. The same tracker/pricing pair is used across every turn so the final summary is meaningful. eventsOpts (e.g. WithColor) forward through to WriteEvents for every turn.
func WriteEvents ¶
func WriteEvents(events iter.Seq2[*session.Event, error], out, info io.Writer, opts ...EventsOption) error
WriteEvents formats events from agent.Run(...) for human-readable streaming display. It's the library-friendly counterpart to the formatter inside Headless / REPL — library callers who want their agent loop to look like an interactive chat session can pass the returned iterator straight in.
Routing:
- Partial assistant text (event.Partial == true) streams to out as it arrives, with no prefix — so a model's reply renders character-by-character like an interactive chat.
- Tool calls render as `→ name(key=value, ...)` to info.
- Tool responses render as `← name(key=value, ...)` to info.
- Final TurnComplete events are skipped (they repeat the text already streamed via Partial events).
out and info may point at the same writer (e.g. both os.Stdout) when you want a single combined stream — useful for tmux capture or piping. They're separate parameters so the default CLI path can keep tool chatter on stderr away from the assistant's reply on stdout.
Pass WithColor(true) to enable ANSI styling — typically gated on IsTerminal(out) so piped output stays clean.
Returns the first iterator error, or nil on clean completion. A trailing newline is written to out if any text was streamed.
Types ¶
type EventsOption ¶
type EventsOption func(*eventsConfig)
EventsOption configures WriteEvents. Use the With* helpers below.
func WithColor ¶
func WithColor(on bool) EventsOption
WithColor enables ANSI color codes in WriteEvents output. Tool calls and responses render in cyan; partial assistant text in green. Off by default — colored output looks like garbage when piped to a file, so callers must opt in (typically guarded by IsTerminal(out)).
Source Files