oneshot

Documentation

Overview

Package oneshot runs one bounded-lifetime Google ADK agent invocation.

Each Run owns an ephemeral in-memory session and native ADK runner. It uses only the model, literal instruction, prompt, and tools supplied in Request. The package performs no discovery, persistence, or filesystem I/O. Supplied tools retain their own authority and responsibility for side effects.

Index

• Variables
• type Error
  • func (e *Error) Error() string
  • func (e *Error) Unwrap() error
• type ErrorCode
  • func CodeOf(err error) ErrorCode
• type Metadata
• type ProbeRequest
• type Request
• type Result
  • func Probe(ctx context.Context, request ProbeRequest) (Result, error)
  • func ProbeToolCalling(ctx context.Context, llm model.LLM) (Result, error)
  • func Run(ctx context.Context, request Request) (Result, error)
• type ToolExecutionPolicy
• type ToolResult
• type Usage

Variables

var (
	ErrInvalidArgument        = errors.New("oneshot: invalid argument")
	ErrCanceled               = errors.New("oneshot: canceled")
	ErrModelPanic             = errors.New("oneshot: caller model panicked")
	ErrToolPanic              = errors.New("oneshot: caller tool panicked")
	ErrOutputTruncated        = errors.New("oneshot: model output truncated")
	ErrTextTruncated          = errors.New("oneshot: returned text truncated")
	ErrModelCallLimit         = errors.New("oneshot: model call limit reached")
	ErrToolCallLimit          = errors.New("oneshot: tool call limit exceeded")
	ErrToolCallingUnsupported = errors.New("oneshot: tool calling unsupported")
	ErrNoFinalResponse        = errors.New("oneshot: no final response")
	ErrExecutionFailed        = errors.New("oneshot: execution failed")
	ErrCleanupFailed          = errors.New("oneshot: cleanup failed")
)

Types

type Error

type Error struct {
	Code ErrorCode
	Op   string
	Err  error
}

Error carries a stable code without exposing recovered panic values.

func (*Error) Error

func (e *Error) Error() string

func (*Error) Unwrap

func (e *Error) Unwrap() error

type ErrorCode

type ErrorCode string

ErrorCode is a stable machine-readable one-shot failure category.

const (
	CodeInvalidArgument        ErrorCode = "invalid_argument"
	CodeCanceled               ErrorCode = "canceled"
	CodeModelPanic             ErrorCode = "model_panic"
	CodeToolPanic              ErrorCode = "tool_panic"
	CodeOutputTruncated        ErrorCode = "output_truncated"
	CodeTextTruncated          ErrorCode = "text_truncated"
	CodeModelCallLimit         ErrorCode = "model_call_limit"
	CodeToolCallLimit          ErrorCode = "tool_call_limit"
	CodeToolCallingUnsupported ErrorCode = "tool_calling_unsupported"
	CodeNoFinalResponse        ErrorCode = "no_final_response"
	CodeExecutionFailed        ErrorCode = "execution_failed"
	CodeCleanupFailed          ErrorCode = "cleanup_failed"
)

func CodeOf

func CodeOf(err error) ErrorCode

CodeOf returns the first one-shot error code in err's unwrap tree.

type Metadata

type Metadata struct {
	ModelCalls int
	ToolCalls  int
	Usage      Usage
}

Metadata reports work completed during one invocation.

type ProbeRequest

type ProbeRequest struct {
	Model           model.LLM
	MaxOutputTokens int32
}

ProbeRequest contains the model and output-token budget for one tool-calling capability probe. MaxOutputTokens must be positive.

type Request

type Request struct {
	Model                   model.LLM
	Instruction             string
	Prompt                  string
	Tools                   []tool.Tool
	MaxOutputTokens         int32
	MaxReturnedTextBytes    int
	MaxModelCalls           int
	MaxToolCallsPerResponse int
	ToolExecution           ToolExecutionPolicy
}

Request contains the complete authority and input for one invocation. Every maximum must be positive. The zero-value ToolExecution policy is sequential.

type Result

type Result struct {
	Text        string
	ToolResults []ToolResult
	Metadata    Metadata
}

Result contains final or partial root-agent text, completed tool results, and execution metadata. A non-nil error may carry partial results; a cleanup-only failure can accompany a complete execution result. Empty final text is valid when a successful final response contains no non-thought text parts.

func Probe

func Probe(ctx context.Context, request ProbeRequest) (Result, error)

Probe makes one direct, non-streaming model request with the supplied positive output-token budget and succeeds only when the model returns the advertised inert ping call. It does not construct a runner, session, or executable tool.

func ProbeToolCalling

func ProbeToolCalling(ctx context.Context, llm model.LLM) (Result, error)

ProbeToolCalling makes one direct, non-streaming model request and succeeds only when the model returns the advertised inert ping call. It does not construct a runner, session, or executable tool. It uses a 64-token output budget. Use Probe when the host needs a different positive budget.

func Run

func Run(ctx context.Context, request Request) (Result, error)

Run executes one synchronous, non-streaming native ADK turn. On a non-nil error, the returned Result may contain partial Text and completed ToolResults.

type ToolExecutionPolicy

type ToolExecutionPolicy uint8

ToolExecutionPolicy controls how calls from one model response execute.

const (
	// ToolExecutionSequential runs calls one at a time in response order.
	ToolExecutionSequential ToolExecutionPolicy = iota
	// ToolExecutionParallel allows calls from one response to overlap.
	ToolExecutionParallel
)

type ToolResult

type ToolResult struct {
	ID       string
	Name     string
	Response map[string]any
}

ToolResult is a completed native tool response. Results retain model response order even when Request enables parallel tool execution.

type Usage

type Usage struct {
	InputTokens  int64
	OutputTokens int64
	TotalTokens  int64
}

Usage aggregates token counts reported by every model response.