Help us shape the future of Go! Take the 2026 Go Developer Survey

builtin

package
v0.7.1 Latest Latest
Warning

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

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

Documentation

Overview

Package builtin is the generic ADK host for builtin-runtime agents: the gateway ships this one host compiled into agw/agwd, and a builtin agent is a persisted definition (agent.BuiltinRuntime) that the host materializes into an eino ADK object graph on demand. See docs/design/agents-control-plane.md §5.7.

Index

Constants

View Source 
const (
	EventSession    = "session"
	EventDelta      = "delta"
	EventContent    = "content"
	EventToolCall   = "tool_call"
	EventUsage      = "usage"
	EventPermission = "permission"
	EventDone       = "done"
	EventError      = "error"
)

Turn event names.

View Source 
const (
	StopReasonPermissionRequired = "permission_required"
	StopReasonCancelled          = "cancelled"
)

Done stop reasons beyond "end_turn".

Variables

View Source 
var ErrAgentNotFound = errors.New("builtin agent not found")

ErrAgentNotFound is returned when the agent id does not resolve.

View Source 
var ErrInvalidRequest = errors.New("invalid builtin turn request")

ErrInvalidRequest marks client-correctable turn failures (unknown agent runtime, disabled agent, empty input, depth exceeded). The dispatcher maps it to HTTP 400, mirroring the ACP error contract.

View Source 
var ErrPermissionCapacity = errors.New("builtin agent pending permission capacity exceeded")

ErrPermissionCapacity is returned when permissions.max_pending is reached: the interrupting turn fails instead of storing another checkpoint (fail-closed, §5.7.7).

View Source 
var ErrSessionBusy = errors.New("builtin session has a turn in flight")

ErrSessionBusy is returned when waiting for an in-flight turn on the same session is cancelled (client disconnect or turn timeout). Fail-closed and client-correctable: retry once the running turn finishes.

View Source 
var ErrSessionLimitExceeded = errors.New("builtin agent session limit exceeded")

ErrSessionLimitExceeded is returned when an agent is at its session cap and no idle session can be evicted. Fail-closed: the new session is rejected, never queued.

View Source 
var ErrTurnLimitExceeded = errors.New("builtin agent concurrent turn limit exceeded")

ErrTurnLimitExceeded is returned when limits.max_concurrent_turns is reached. Fail-closed: the turn is rejected, never queued.

Functions

func RegisterFactory 

func RegisterFactory(name string, f Factory) error

RegisterFactory registers a compiled-in custom agent factory, mirroring provider.RegisterProviderFactory. It also records the name in pkg/agent's name registry so definition validation can reject unknown factories.

Types

type AgentSource 

type AgentSource interface {
	Get(ctx context.Context, id string) (agent.Agent, error)
}

AgentSource resolves agent definitions; *agent.Manager satisfies it.

type CancelMode 

type CancelMode string

CancelMode selects how an operator-requested cancel stops a running turn. It answers the "forced-cancel for stuck turns" question in docs/design/agents-control-plane.md §10 by adopting the ADK Runner cancel primitive (eino-reuse.md §5) for the builtin host. 

const (
	// CancelModeForce aborts the turn immediately (adk.CancelImmediate): the
	// in-flight model or tool step is abandoned and the turn ends now. This is
	// the default and the answer for stuck turns.
	CancelModeForce CancelMode = "force"
	// CancelModeGraceful stops after the current model or tool step completes
	// (the adk safe-points CancelAfterChatModel|CancelAfterToolCalls),
	// propagating those safe-points through nested agents and escalating to
	// force if none is reached within cancelGracePeriod.
	CancelModeGraceful CancelMode = "graceful"
)

func ParseCancelMode 

func ParseCancelMode(s string) (CancelMode, error)

ParseCancelMode normalizes an operator-supplied mode; empty defaults to force. An unknown mode is a client-correctable error.

type ChatModelResolver 

type ChatModelResolver interface {
	ResolveChatModel(ctx context.Context, llmRouteID, model string, requireTools bool) (einomodel.ToolCallingChatModel, error)
}

ChatModelResolver resolves a gateway LLM route to an eino chat model. The gateway-side implementation wraps a RoutedProvider through the einomodel bridge, so credential scheduling, candidate fallback, and LLM usage recording apply unchanged. requireTools narrows logical-model candidates to tool-capable bindings so a node that carries tools never routes to a model that cannot call them.

type Config 

type Config struct {
	Agents   AgentSource
	Models   ChatModelResolver
	Tools    einotool.ToolCaller
	Observer usage.InteractionObserver
}

Config wires the host's collaborator seams.

type ContinuationCursor 

type ContinuationCursor struct {
	RunID        string
	NextSequence uint64
	NextSegment  uint32
}

ContinuationCursor is opaque common event-ordering state stored beside a pending Host checkpoint. The gateway adapter translates it to/from its runtime-neutral cursor without exposing ADK checkpoint data.

type EntryState 

type EntryState struct {
	Materialized   bool      `json:"materialized"`
	MaterializedAt time.Time `json:"materialized_at,omitzero"`
	TopologyKind   string    `json:"topology_kind,omitempty"`
	InflightTurns  int       `json:"inflight_turns"`
	LiveSessions   int       `json:"live_sessions"`
}

EntryState is the workspace-facing materialization view of one agent.

type EventSink 

type EventSink func(TurnEvent) error

EventSink receives turn events in emission order.

type Factory 

type Factory func(ctx context.Context, deps FactoryDeps, def *agent.BuiltinRuntime) (adk.Agent, error)

Factory builds a custom ADK agent from a builtin definition. It is the escape hatch for agents that need custom Go logic (docs/design/agents-control-plane.md §5.7.3): implement the factory, register it, and blank-import the package in cmd/agw/main.go, cmd/agwd/main.go, and cmd/agwctl/main.go.

type FactoryDeps 

type FactoryDeps struct {
	Models ChatModelResolver
	Tools  einotool.ToolCaller
}

FactoryDeps hands a custom factory the same gateway-governed building blocks the declarative materializer uses.

type Host 

type Host struct {
	// contains filtered or unexported fields
}

Host is the generic ADK host. One instance serves every builtin agent: definitions are materialized lazily and cached keyed by agent id + updated_at, so a definition update re-materializes on the next turn while in-flight turns drain on the old graph.

func NewHost 

func NewHost(cfg Config) *Host

func (*Host) CancelRun 

func (h *Host) CancelRun(agentID, runID string, mode CancelMode) (bool, error)

CancelRun targets the exact logical run id used by the common Agent API.

func (*Host) CancelTurn 

func (h *Host) CancelTurn(agentID, sessionID string, mode CancelMode) (bool, error)

CancelTurn requests cancellation of the running turn for (agentID, sessionID) and reports whether one was in flight. force aborts immediately; graceful stops after the current model/tool step, escalating to force after a grace period. The cancelled turn's own SSE stream emits a done event with stop_reason "cancelled"; a discarded (uncommitted) partial exchange leaves the session history untouched.

func (*Host) ExpirePermission 

func (h *Host) ExpirePermission(agentID, requestID string) bool

ExpirePermission discards one opaque suspended checkpoint fail-closed.

func (*Host) ListInFlight 

func (h *Host) ListInFlight() []InFlightTurnView

ListInFlight reports the running turns for the Admin API.

func (*Host) LoadContinuationCursor 

func (h *Host) LoadContinuationCursor(agentID, requestID string) (ContinuationCursor, bool)

LoadContinuationCursor reads, but does not consume, the cursor attached to a pending permission. The Host's one-shot checkpoint take owns deletion, so a request rejected before take may be corrected and retried.

func (*Host) Runtime 

func (h *Host) Runtime() RuntimeView

Runtime reports the host-wide runtime view for the Admin API.

func (*Host) ServeTurn 

func (h *Host) ServeTurn(ctx context.Context, agentID string, req TurnRequest, emit EventSink) error

ServeTurn runs one turn of a builtin agent and streams events to emit. Client-correctable failures wrap ErrInvalidRequest; concurrency rejection wraps ErrTurnLimitExceeded; unknown agents wrap ErrAgentNotFound.

func (*Host) State 

func (h *Host) State(agentID string) EntryState

State reports the materialization/runtime state for the workspace view.

func (*Host) StoreContinuationCursor 

func (h *Host) StoreContinuationCursor(agentID, requestID string, cursor ContinuationCursor) bool

StoreContinuationCursor attaches common event-ordering state to a pending permission checkpoint. It fails closed if the checkpoint identity no longer exists or belongs to another Agent/run.

type InFlightTurnView 

type InFlightTurnView struct {
	AgentID      string    `json:"agent_id"`
	SessionID    string    `json:"session_id"`
	RunID        string    `json:"run_id"`
	RequestID    string    `json:"request_id,omitempty"`
	Operation    string    `json:"operation"`
	TopologyKind string    `json:"topology_kind,omitempty"`
	StartedAt    time.Time `json:"started_at"`
}

InFlightTurnView is the admin view of one running turn.

type PendingPermissionCall 

type PendingPermissionCall struct {
	CallID       string `json:"call_id"`
	MCPServiceID string `json:"mcp_service_id"`
	ToolName     string `json:"name"`
	Arguments    string `json:"arguments,omitempty"`
}

PendingPermissionCall is the admin/SSE view of one gated tool call.

type PendingPermissionView 

type PendingPermissionView struct {
	RequestID string                  `json:"request_id"`
	AgentID   string                  `json:"agent_id"`
	SessionID string                  `json:"session_id"`
	RunID     string                  `json:"run_id"`
	CreatedAt time.Time               `json:"created_at"`
	ExpiresAt time.Time               `json:"expires_at"`
	Calls     []PendingPermissionCall `json:"calls"`
}

PendingPermissionView is the admin runtime view of one suspended turn.

type RuntimeView 

type RuntimeView struct {
	Agents             map[string]EntryState   `json:"agents"`
	PendingPermissions []PendingPermissionView `json:"pending_permissions"`
	InFlight           []InFlightTurnView      `json:"in_flight"`
}

RuntimeView is the /admin/builtin/runtime payload: per-agent materialization state plus the suspended interactive turns awaiting a decision.

type TurnEvent 

type TurnEvent struct {
	Event      string          `json:"-"`
	SessionID  string          `json:"session_id,omitempty"`
	RunID      string          `json:"run_id,omitempty"`
	RequestID  string          `json:"request_id,omitempty"`
	Text       string          `json:"text,omitempty"`
	StopReason string          `json:"stop_reason,omitempty"`
	Message    string          `json:"message,omitempty"`
	Data       json.RawMessage `json:"data,omitempty"`
}

TurnEvent is one SSE event of a builtin turn. The vocabulary is a marked subset of the ACP turn vocabulary: session, delta, content, tool_call, usage, permission, done, error.

type TurnPermission 

type TurnPermission struct {
	RequestID string                   `json:"request_id"`
	Outcome   string                   `json:"outcome,omitempty"`
	Decisions []TurnPermissionDecision `json:"decisions,omitempty"`
}

TurnPermission answers a pending tool-permission request. Outcome is empty to deliver per-call decisions, or "cancel" to discard the suspended turn. A pending call absent from Decisions is denied (fail-closed).

type TurnPermissionDecision 

type TurnPermissionDecision struct {
	CallID  string `json:"call_id"`
	Outcome string `json:"outcome"`
}

TurnPermissionDecision resolves one gated tool call: outcome "allow" or "deny".

type TurnRequest 

type TurnRequest struct {
	// RunID is allocated by the Agent execution boundary for a fresh run. A
	// permission resume preserves the pending checkpoint's logical run id.
	RunID      string          `json:"-"`
	SessionID  string          `json:"session_id,omitempty"`
	Input      string          `json:"input,omitempty"`
	Permission *TurnPermission `json:"permission,omitempty"`
}

TurnRequest is the data-plane turn input. Sessions are in-memory conversation histories keyed by session_id; state does not survive a gateway restart (documented PB1 semantics — durable checkpoints wait for eino v0.10). Exactly one of Input and Permission must be set: Input starts a turn, Permission resumes one suspended on a tool-permission interrupt (§5.7.7) and streams the continuation on this request's SSE response.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.