subagent

package
v0.10.0-alpha.19 Latest Latest
Warning

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

Go to latest
Published: Aug 21, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Overview

Package subagent provides a durable backgroundtask executor for ADK sub-agent runs.

Index

Constants

View Source
const (
	// ExecutorKey is the backgroundtask executor key for durable sub-agent tasks.
	ExecutorKey = "eino.dev/subagent"
)

Variables

This section is empty.

Functions

func ChildSessionIDFromTask

func ChildSessionIDFromTask(task *backgroundtask.Task) (string, error)

ChildSessionIDFromTask returns the persistent child session owned by a durable sub-agent task.

func Submit

func Submit[M adk.MessageType](
	ctx context.Context,
	manager *backgroundtask.Manager,
	req *SubmitRequest[M],
) (*backgroundtask.Task, error)

Submit serializes and persists a durable sub-agent task through manager. If the returned error wraps backgroundtask.ErrTaskCreatedEventUndelivered and task is non-nil, durable ownership has transferred and callers must not retry Submit.

Types

type AgentRegistration

type AgentRegistration[M adk.MessageType] struct {
	Agent             adk.TypedResumableAgent[M]
	RunOptionsFactory RunOptionsFactory
}

AgentRegistration binds a persisted name to worker-local dependencies. Every worker eligible to execute that name must provide a semantically equivalent registration for the full lifetime of its resumable tasks. Incompatible Agent or run-option changes require draining existing tasks or registering a new agent name.

type Executor

type Executor[M adk.MessageType] struct {
	// contains filtered or unexported fields
}

Executor runs durable sub-agent tasks through ADK Runner checkpointing.

func NewExecutor

func NewExecutor[M adk.MessageType](config *ExecutorConfig[M]) (*Executor[M], error)

NewExecutor constructs a durable sub-agent executor with explicit session and checkpoint dependencies.

func (*Executor[M]) Execute

func (e *Executor[M]) Execute(
	ctx context.Context,
	task *backgroundtask.Task,
	runtime backgroundtask.ExecutionRuntime,
) (result *backgroundtask.ExecutionResult, err error)

Execute runs or resumes the sub-agent task and returns its lifecycle outcome.

func (*Executor[M]) Key

func (e *Executor[M]) Key() string

Key returns the backgroundtask executor key for sub-agent tasks.

func (*Executor[M]) LeaseExpiryPolicy

func (*Executor[M]) LeaseExpiryPolicy() backgroundtask.LeaseExpiryPolicy

LeaseExpiryPolicy allows another worker to resume a lost sub-agent attempt.

func (*Executor[M]) ReadProgress

func (e *Executor[M]) ReadProgress(
	ctx context.Context,
	task *backgroundtask.Task,
	format func(context.Context, string, M) (string, error),
) (string, error)

ReadProgress projects a bounded child-session transcript without exposing the Executor's session store. It returns an empty string for tasks owned by another executor. format converts one materialized child-session message to one transcript record; an empty result skips the message. It may be called concurrently and must not mutate the message.

func (*Executor[M]) Register

func (e *Executor[M]) Register(name string, registration *AgentRegistration[M]) error

Register binds a stable sub-agent name to the implementation and output policy.

func (*Executor[M]) SupportsDrain

func (e *Executor[M]) SupportsDrain() bool

SupportsDrain reports true because sub-agent drain captures an ADK Runner checkpoint before returning a suspended result.

func (*Executor[M]) ValidateExecution

func (e *Executor[M]) ValidateExecution(_ context.Context, task *backgroundtask.Task) error

ValidateExecution verifies worker dependencies without mutating external state.

func (*Executor[M]) ValidateSpec

func (e *Executor[M]) ValidateSpec(spec backgroundtask.Spec) error

ValidateSpec verifies that spec contains a compatible sub-agent payload.

type ExecutorConfig

type ExecutorConfig[M adk.MessageType] struct {
	// SessionStore persists child events without attempt-specific construction.
	// It is retained for providers whose store performs fencing by another
	// mechanism. Persistent child sessions may be used by multiple task IDs, so
	// production providers must serialize concurrent turns for one session
	// across workers. Configure exactly one of SessionStore and
	// SessionStoreFactory.
	SessionStore adk.SessionEventStore[M]
	// SessionStoreFactory constructs a task-bound child event store.
	// Stores returned for tasks sharing a ChildSessionID must coordinate the
	// same durable session and serialize concurrent turns across workers.
	SessionStoreFactory SessionStoreFactory[M]
	// CheckPointStore persists ADK Runner checkpoints for interruption and recovery.
	CheckPointStore adk.CheckPointStore
	// SessionConfig optionally customizes child-session persistence.
	SessionConfig *adk.SessionConfig[M]
}

ExecutorConfig provides the durable session dependencies shared by every sub-agent task executed by an Executor.

type RunOptionsFactory

type RunOptionsFactory func() ([]adk.AgentRunOption, error)

RunOptionsFactory reconstructs deployment-owned run options for each task attempt. It may be called concurrently, must return fresh option values, and must not panic. Every worker serving the same registered agent name must configure a semantically equivalent factory for the full task lifetime. An error fails that attempt before agent execution.

type SessionStoreFactory

type SessionStoreFactory[M adk.MessageType] func(
	context.Context,
	*backgroundtask.Task,
) (adk.SessionEventStore[M], error)

SessionStoreFactory constructs the child Session store for one task access. It is called for execution attempts and progress reads. Durable providers use task ID and attempt to bind append authorization to the active task lease while retaining read access after the attempt ends. It may be called concurrently and must return a fresh, semantically equivalent store on every call.

type SubmitRequest

type SubmitRequest[M adk.MessageType] struct {
	TaskID                        string
	SubAgentName                  string
	Input                         *adk.TypedAgentInput[M]
	Description                   string
	SessionID                     string
	ChildSessionID                string
	DisableLifecycleNotifications bool
	InitialCheckpoint             []byte
}

SubmitRequest describes a durable sub-agent task. Input must be non-nil and contain at least one non-nil message. Eino serializes it before persistence; concrete values stored in interface fields must be registered with schema. Empty TaskID asks Manager to allocate one. SessionID identifies the parent session notified when the child waits for input or terminates. Empty ChildSessionID creates a new opaque child session when empty; a non-empty value is used as-is and continues that existing child session with its committed history. DisableLifecycleNotifications suppresses automatic waiting and terminal notifications without suppressing TaskCreated recovery.

type TaskContext

type TaskContext struct {
	TaskID          string
	ParentSessionID string
	SubAgentName    string
	ChildSessionID  string
	Attempt         int64
}

TaskContext describes the durable task currently executing a sub-agent. The child session ID is opaque; use TaskID for task-owned metadata lookups.

func TaskContextFromContext

func TaskContextFromContext(ctx context.Context) (TaskContext, bool)

TaskContextFromContext returns durable sub-agent task metadata for the current execution attempt.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL