Documentation
¶
Index ¶
- type Agent
- func (d *Agent) Cancel()
- func (d *Agent) Close()
- func (d *Agent) Fingerprint() string
- func (d *Agent) FlushPendingMessages()
- func (d *Agent) IsRunning() bool
- func (d *Agent) Run(ctx context.Context, userMessages []*schema.Message, handler agui.EventHandler) error
- func (d *Agent) RunWithUsage(ctx context.Context, userMessages []*schema.Message, handler agui.EventHandler) (*ProviderUsage, error)
- func (d *Agent) StopAndFlush()
- type AgentEvent
- type Config
- type Option
- type ProviderUsage
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Agent ¶
type Agent struct {
// contains filtered or unexported fields
}
func New ¶
func New(ctx context.Context, workdir string, modelCfg *modelbuilder.ModelConfig, opts ...Option) (*Agent, error)
func (*Agent) Close ¶
func (d *Agent) Close()
Close cancels any in-flight run and waits for Run() to finish its deferred cleanup so the round builder's final flush can reach disk before Close returns.
Waiting is bounded so a stuck iterator can't prevent shutdown; if the deadline fires we proceed anyway and log — the deferred flush uses a detached context so it still persists what it can. The local sandbox client holds no releasable resources (no container, no remote connection), so there is nothing to release here.
func (*Agent) Fingerprint ¶
Fingerprint returns the deterministic hash that captures this agent's constructor inputs. Callers caching agents use it to invalidate cached agents whose inputs (model / workdir / system prompt) no longer match the next caller's request.
func (*Agent) FlushPendingMessages ¶
func (d *Agent) FlushPendingMessages()
FlushPendingMessages drains the round builder and persists any round still in flight. Delegates to round.FlushPending, the shared cleanup path. The persist call is wrapped in round.PersistContext so the canonical persist deadline applies — see round.PersistTimeout for the scope of what that deadline currently covers (lock-wait yes, blocking file I/O no).
func (*Agent) IsRunning ¶
IsRunning reports whether any Run() call is currently executing on this agent. Agent caches check this to avoid closing an agent that's still streaming.
func (*Agent) Run ¶
func (d *Agent) Run(ctx context.Context, userMessages []*schema.Message, handler agui.EventHandler) error
Run feeds a prompt through the eino adk runner, aggregates adk events into rounds via round.Builder, and persists completed rounds incrementally. Messages on disk have identical shape to the acp path: one assistant message per round followed by its role=tool results in declaration order.
Concurrency / cancellation ¶
The runner wraps ctx with a cancelable child (runCtx) and stores the cancel on Agent so Cancel() can be called from another goroutine. runCtx being cancelled simply exits the event loop; a deferred cleanup block (FinalizeStreaming + PendingToolCallIDs + flush) ensures a clean round close in all paths, including mid-loop panic.
func (*Agent) RunWithUsage ¶
func (d *Agent) RunWithUsage(ctx context.Context, userMessages []*schema.Message, handler agui.EventHandler) (*ProviderUsage, error)
RunWithUsage is Run plus the provider-reported token usage for this prompt turn. The returned usage aggregates every underlying ChatModel invocation (including tool-loop follow-ups); nil means none of the model calls reported usage. On cancellation or another run error, usage from every observed streaming chunk and completed non-streaming call is returned.
func (*Agent) StopAndFlush ¶
func (d *Agent) StopAndFlush()
StopAndFlush atomically cancels any in-flight Run and ensures the builder's accumulated state reaches disk. Replaces the prior FlushPendingMessages -> Cancel idiom from cleanup callers, which had a real race window: FlushPendingMessages emitted pending-end events and cleared the builder's accumulators, but the Run was still active and could push new stream events into the just-cleared builder. The late events would be dropped (no matching round / no terminal site) and a real tool terminal arriving after the eager superseded flush would never reach disk — only the canceled placeholder would.
New order:
- Cancel runCtx so the Run loop exits ASAP.
- Wait (bounded by stopAndFlushTimeout) for Run to finish its deferred cleanup chain — that chain runs round.FinalizeRound while onFlush is still installed, so any in-flight round is persisted atomically with the cancel.
- As a safety net, run FlushPendingMessages. If Run already drained the builder, this is a no-op (CollectMessages returns nothing). If Run hung past the timeout, this still gets the builder's accumulators onto disk via the inline persist callback that runs because onFlush has been ClearOnFlush'd.
type AgentEvent ¶
type AgentEvent = adk.AgentEvent
type Config ¶
type Config struct {
SystemPrompt string
SessionID string
SessionDir string
SessionToucher chatctx.SessionToucher
}
type Option ¶
type Option func(*Config)
func WithSessionDir ¶
func WithSessionID ¶
func WithSessionToucher ¶
func WithSessionToucher(t chatctx.SessionToucher) Option
WithSessionToucher wires a SessionToucher so BeginRun can bump session meta's UpdatedAt through the caller's session writer instead of writing the session meta file directly.
func WithSystemPrompt ¶
type ProviderUsage ¶
type ProviderUsage struct {
InputTokens int64
OutputTokens int64
TotalTokens int64
CachedReadTokens int64
ThoughtTokens int64
}
ProviderUsage is the provider-reported token usage for one Agent Run. It is deliberately separate from the context-window usage_update notifications: those are local tokenizer estimates over persisted history, while these are the authoritative counters returned by the model provider for this turn.
Source Files