Documentation
¶
Index ¶
- Variables
- func DefaultFailureClassifier(err error, stage session.TurnFailureStage) *session.TurnFailure
- func ValidateToolProtocol(events []model.Event) error
- type FailureClassifier
- type Option
- type ProjectionInput
- type Projector
- type ProjectorFunc
- type Runner
- type SessionNotFoundError
- type ToolExecutionUnknownError
- type ToolProtocolIssue
Constants ¶
This section is empty.
Variables ¶
var ErrSessionNotFound = errors.New("runner: session not found")
ErrSessionNotFound indicates that the requested session does not exist.
var ErrToolExecutionUnknown = errors.New("runner: tool execution status unknown")
ErrToolExecutionUnknown indicates that persisted history contains tool calls without matching durable results, so their execution status cannot be determined safely.
Functions ¶
func DefaultFailureClassifier ¶ added in v0.1.0
func DefaultFailureClassifier(err error, stage session.TurnFailureStage) *session.TurnFailure
DefaultFailureClassifier trusts only errors implementing session.TurnFailureProvider. Other errors receive a stable generic code and no persisted message.
func ValidateToolProtocol ¶ added in v0.1.0
ValidateToolProtocol returns ErrToolExecutionUnknown when events contain an assistant tool call without a matching result. Runner applies this check after every context projection, including custom Projector implementations.
Types ¶
type FailureClassifier ¶ added in v0.1.0
type FailureClassifier func(err error, stage session.TurnFailureStage) *session.TurnFailure
FailureClassifier converts an execution error into structured information that is safe to persist and display. It must not copy arbitrary error text.
type Option ¶ added in v0.0.9
type Option func(*Runner)
Option configures a Runner.
func WithFailureClassifier ¶ added in v0.1.0
func WithFailureClassifier(classifier FailureClassifier) Option
WithFailureClassifier configures conversion of execution errors into safe, structured Turn failure metadata. It must return nil or a valid TurnFailure and must not copy arbitrary error text. A nil classifier restores the default.
func WithProjector ¶ added in v0.1.0
WithProjector configures how durable Turns and Events are converted into Agent context. A nil projector restores the default durable-Turn projector. Runner validates the projected tool protocol regardless of this option, but custom implementations remain responsible for the semantic truth of any tool results they create.
func WithTracer ¶ added in v0.0.9
WithTracer configures span-oriented tracing for Runner and the agents it invokes. A nil tracer disables tracing.
type ProjectionInput ¶ added in v0.1.0
type ProjectionInput struct {
Turns []*session.Turn
Events []*sessionevent.Event
}
ProjectionInput contains durable Turn metadata and Event facts to project into provider-neutral model context. Events must be in conversation order.
type Projector ¶ added in v0.1.0
type Projector interface {
Project(ctx context.Context, input ProjectionInput) ([]model.Event, error)
}
Projector converts durable session facts into context safe to provide to an Agent. Implementations must not mutate or persist the input. Runner always applies ValidateToolProtocol to the returned context.
func NewDefaultProjector ¶ added in v0.1.0
func NewDefaultProjector() Projector
NewDefaultProjector returns ADK's durable-Turn context projector. Completed and legacy Turns are replayed as recorded. Running Turns are omitted. Failed and interrupted Turns retain their safe prefix and gain an ephemeral status notice; an unmatched tool call and its suffix are omitted.
type ProjectorFunc ¶ added in v0.1.0
ProjectorFunc adapts a function to Projector.
func (ProjectorFunc) Project ¶ added in v0.1.0
func (f ProjectorFunc) Project(ctx context.Context, input ProjectionInput) ([]model.Event, error)
Project implements Projector.
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner coordinates a stateless Agent with a SessionService. It loads conversation history from the session, forwards it to the agent, and persists complete yielded events back to the session. Sessions implementing session.TurnStore preserve failed and interrupted turns durably; other implementations retain the legacy rollback behavior.
func (*Runner) Run ¶
func (r *Runner) Run(ctx context.Context, sessionID string, userInput model.Content) iter.Seq2[*model.Event, error]
Run handles one user turn. It fetches the session history, appends the user input, invokes the agent, and yields each produced Event to the caller. Complete events (Event.Partial=false) are persisted to the session; partial streaming fragments are forwarded to the caller for real-time display but are not persisted. Durable Turn stores retain events when execution fails or iteration stops early and use a safe projection when constructing later LLM context. Other stores remove events created by an incomplete turn. The caller iterates the returned sequence and decides whether to continue the conversation by calling Run again.
If active history contains assistant tool calls without matching durable results, Run yields ErrToolExecutionUnknown before persisting the user input or invoking the agent.
userInput must contain the user's input content (via Text or Parts). Its Role is always set to RoleUser by the runner.
type SessionNotFoundError ¶ added in v0.0.6
type SessionNotFoundError struct {
SessionID string
}
SessionNotFoundError reports that the requested session does not exist.
func (*SessionNotFoundError) Error ¶ added in v0.0.6
func (e *SessionNotFoundError) Error() string
Error implements the error interface.
func (*SessionNotFoundError) Unwrap ¶ added in v0.0.6
func (e *SessionNotFoundError) Unwrap() error
Unwrap allows callers to match ErrSessionNotFound with errors.Is.
type ToolExecutionUnknownError ¶ added in v0.0.10
type ToolExecutionUnknownError struct {
// SessionID identifies the affected session.
SessionID string
// TurnID identifies the turn that emitted the assistant tool calls. It may
// be empty for events written before turn IDs were introduced.
TurnID string
// EventID identifies the persisted assistant event containing the calls.
EventID int64
// ToolCalls contains only calls that have no matching persisted result.
ToolCalls []model.ToolCall
}
ToolExecutionUnknownError reports unresolved tool calls from one assistant event. Runner returns this error before persisting a new user event or invoking the agent.
func (*ToolExecutionUnknownError) Error ¶ added in v0.0.10
func (e *ToolExecutionUnknownError) Error() string
Error implements the error interface.
func (*ToolExecutionUnknownError) TurnFailure ¶ added in v0.1.0
func (e *ToolExecutionUnknownError) TurnFailure() session.TurnFailure
TurnFailure returns safe structured metadata for durable Turn display.
func (*ToolExecutionUnknownError) Unwrap ¶ added in v0.0.10
func (e *ToolExecutionUnknownError) Unwrap() error
Unwrap allows callers to match ErrToolExecutionUnknown with errors.Is.
type ToolProtocolIssue ¶ added in v0.1.0
type ToolProtocolIssue struct {
// SessionID identifies the affected session when available.
SessionID string
// TurnID identifies the turn containing the assistant tool calls.
TurnID string
// EventID identifies the assistant event containing the calls.
EventID int64
// ToolCalls contains only calls that have no matching result.
ToolCalls []model.ToolCall
}
ToolProtocolIssue describes assistant tool calls without matching results.
func InspectToolProtocol ¶ added in v0.1.0
func InspectToolProtocol(events []model.Event) []ToolProtocolIssue
InspectToolProtocol returns every assistant tool-call group that does not have a matching result for every call. Results are matched only within the contiguous tool-result events following the assistant event, and only within the same Turn, so reused provider call IDs cannot close an older group.
Source Files