Documentation
¶
Overview ¶
Package subagent provides a durable backgroundtask executor for ADK sub-agent runs.
Index ¶
- Constants
- func ChildSessionIDFromTask(task *backgroundtask.Task) (string, error)
- func Submit[M adk.MessageType](ctx context.Context, manager *backgroundtask.Manager, req *SubmitRequest[M]) (*backgroundtask.Task, error)
- type AgentRegistration
- type Executor
- func (e *Executor[M]) Execute(ctx context.Context, task *backgroundtask.Task, ...) (result *backgroundtask.ExecutionResult, err error)
- func (e *Executor[M]) Key() string
- func (*Executor[M]) LeaseExpiryPolicy() backgroundtask.LeaseExpiryPolicy
- func (e *Executor[M]) ReadProgress(ctx context.Context, task *backgroundtask.Task, ...) (string, error)
- func (e *Executor[M]) Register(name string, registration *AgentRegistration[M]) error
- func (e *Executor[M]) SupportsDrain() bool
- func (e *Executor[M]) ValidateExecution(_ context.Context, task *backgroundtask.Task) error
- func (e *Executor[M]) ValidateSpec(spec backgroundtask.Spec) error
- type ExecutorConfig
- type RunOptionsFactory
- type SessionStoreFactory
- type SubmitRequest
- type TaskContext
Constants ¶
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]) 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 ¶
SupportsDrain reports true because sub-agent drain captures an ADK Runner checkpoint before returning a suspended result.
func (*Executor[M]) ValidateExecution ¶
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.