Documentation
¶
Index ¶
- func AppendAddressSegment(ctx context.Context, segType AddressSegmentType, segID string, subID string) context.Context
- func BatchResumeWithData(ctx context.Context, resumeData map[string]any) context.Context
- func GetInterruptState[T any](ctx context.Context) (wasInterrupted bool, hasState bool, state T)
- func GetNextResumptionPoints(ctx context.Context) (map[string]bool, error)
- func GetResumeContext[T any](ctx context.Context) (isResumeTarget bool, hasData bool, data T)
- func PopulateInterruptState(ctx context.Context, id2Addr map[string]Address, ...) context.Context
- func SignalToPersistenceMaps(is *InterruptSignal) (map[string]Address, map[string]InterruptState)
- type Address
- type AddressSegment
- type AddressSegmentType
- type CheckPointStore
- type InterruptConfig
- type InterruptCtx
- type InterruptInfo
- type InterruptOption
- type InterruptSignal
- type InterruptState
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func AppendAddressSegment ¶
func AppendAddressSegment(ctx context.Context, segType AddressSegmentType, segID string, subID string) context.Context
AppendAddressSegment creates a new execution context for a sub-component (e.g., a graph node or a tool call).
It extends the current context's address with a new segment and populates the new context with the appropriate interrupt state and resume data for that specific sub-address.
- ctx: The parent context, typically the one passed into the component's Invoke/Stream method.
- segType: The type of the new address segment (e.g., "node", "tool").
- segID: The unique ID for the new address segment.
func BatchResumeWithData ¶
BatchResumeWithData is the core function for preparing a resume context. It injects a map of resume targets and their corresponding data into the context.
The `resumeData` map should contain the interrupt IDs (which are the string form of addresses) of the components to be resumed as keys. The value can be the resume data for that component, or `nil` if no data is needed (equivalent to using `Resume`).
This function is the foundation for the "Explicit Targeted Resume" strategy. Components whose interrupt IDs are present as keys in the map will receive `isResumeFlow = true` when they call `GetResumeContext`.
func GetInterruptState ¶
GetInterruptState provides a type-safe way to check for and retrieve the persisted state from a previous interruption. It is the primary function a component should use to understand its past state.
It returns three values:
- wasInterrupted (bool): True if the node was part of a previous interruption, regardless of whether state was provided.
- state (T): The typed state object, if it was provided and matches type `T`.
- hasState (bool): True if state was provided during the original interrupt and successfully cast to type `T`.
func GetNextResumptionPoints ¶
GetNextResumptionPoints finds the immediate child resumption points for a given parent address.
func GetResumeContext ¶
GetResumeContext checks if the current component is the target of a resume operation and retrieves any data provided by the user for that resumption.
This function is typically called *after* a component has already determined it is in a resumed state by calling GetInterruptState.
It returns three values:
- isResumeFlow: A boolean that is true if the current component's address was explicitly targeted by a call to Resume() or ResumeWithData().
- hasData: A boolean that is true if data was provided for this component (i.e., not nil).
- data: The typed data provided by the user.
### How to Use This Function: A Decision Framework
The correct usage pattern depends on the application's desired resume strategy.
#### Strategy 1: Implicit "Resume All" In some use cases, any resume operation implies that *all* interrupted points should proceed. For example, if an application's UI only provides a single "Continue" button for a set of interruptions. In this model, a component can often just use `GetInterruptState` to see if `wasInterrupted` is true and then proceed with its logic, as it can assume it is an intended target. It may still call `GetResumeContext` to check for optional data, but the `isResumeFlow` flag is less critical.
#### Strategy 2: Explicit "Targeted Resume" (Most Common) For applications with multiple, distinct interrupt points that must be resumed independently, it is crucial to differentiate which point is being resumed. This is the primary use case for the `isResumeFlow` flag.
- If `isResumeFlow` is `true`: Your component is the explicit target. You should consume the `data` (if any) and complete your work.
- If `isResumeFlow` is `false`: Another component is the target. You MUST re-interrupt (e.g., by returning `StatefulInterrupt(...)`) to preserve your state and allow the resume signal to propagate.
### Guidance for Composite Components
Composite components (like `Graph` or other `Runnable`s that contain sub-processes) have a dual role:
- Check for Self-Targeting: A composite component can itself be the target of a resume operation, for instance, to modify its internal state. It may call `GetResumeContext` to check for data targeted at its own address.
- Act as a Conduit: After checking for itself, its primary role is to re-execute its children, allowing the resume context to flow down to them. It must not consume a resume signal intended for one of its descendants.
func PopulateInterruptState ¶
func SignalToPersistenceMaps ¶
func SignalToPersistenceMaps(is *InterruptSignal) (map[string]Address, map[string]InterruptState)
SignalToPersistenceMaps flattens an InterruptSignal tree into two maps suitable for persistence in a checkpoint.
Types ¶
type Address ¶
type Address []AddressSegment
Address represents a full, hierarchical address to a point in the execution structure.
func GetCurrentAddress ¶
GetCurrentAddress returns the hierarchical address of the currently executing component. The address is a sequence of segments, each identifying a structural part of the execution like an agent, a graph node, or a tool call. This can be useful for logging or debugging.
type AddressSegment ¶
type AddressSegment struct {
// ID is the unique identifier for this segment, e.g., the node's key or the tool's name.
ID string
// Type indicates whether this address segment is a graph node, a tool call, an agent, etc.
Type AddressSegmentType
// In some cases, ID alone are not unique enough, we need this SubID to guarantee uniqueness.
// e.g. parallel tool calls with the same name but different tool call IDs.
SubID string
}
AddressSegment represents a single segment in the hierarchical address of an execution point. A sequence of AddressSegments uniquely identifies a location within a potentially nested structure.
type AddressSegmentType ¶
type AddressSegmentType string
AddressSegmentType defines the type of a segment in an execution address.
type CheckPointStore ¶
type InterruptConfig ¶
type InterruptConfig struct {
LayerPayload any
}
InterruptConfig holds optional parameters for creating an interrupt.
type InterruptCtx ¶
type InterruptCtx struct {
// ID is the unique, fully-qualified address of the interrupt point.
// It is constructed by joining the individual Address segments, e.g., "agent:A;node:graph_a;tool:tool_call_123".
// This ID should be used when providing resume data via ResumeWithData.
ID string
// Address is the structured sequence of AddressSegment segments that leads to the interrupt point.
Address Address
// Info is the user-facing information associated with the interrupt, provided by the component that triggered it.
Info any
// IsRootCause indicates whether the interrupt point is the exact root cause for an interruption.
IsRootCause bool
// Parent points to the context of the parent component in the interrupt chain.
// It is nil for the top-level interrupt.
Parent *InterruptCtx
}
InterruptCtx provides a complete, user-facing context for a single, resumable interrupt point.
func ToInterruptContexts ¶
func ToInterruptContexts(is *InterruptSignal, addrModifier func(Address) Address) []*InterruptCtx
ToInterruptContexts converts the internal InterruptSignal tree into a list of user-facing InterruptCtx objects for the root causes of the interruption. Each returned context has its Parent field populated (if it has a parent), allowing traversal up the interrupt chain.
func (*InterruptCtx) EqualsWithoutID ¶
func (ic *InterruptCtx) EqualsWithoutID(other *InterruptCtx) bool
type InterruptInfo ¶
func (*InterruptInfo) String ¶
func (i *InterruptInfo) String() string
type InterruptOption ¶
type InterruptOption func(*InterruptConfig)
InterruptOption is a function that configures an InterruptConfig.
func WithLayerPayload ¶
func WithLayerPayload(payload any) InterruptOption
WithLayerPayload creates an option to attach layer-specific metadata to the interrupt's state.
type InterruptSignal ¶
type InterruptSignal struct {
ID string
Address
InterruptInfo
InterruptState
Subs []*InterruptSignal
}
func FromInterruptContexts ¶
func FromInterruptContexts(contexts []*InterruptCtx) *InterruptSignal
FromInterruptContexts converts a list of user-facing InterruptCtx objects into an internal InterruptSignal tree. It correctly handles common ancestors and ensures that the resulting tree is consistent with the original interrupt chain.
This method is primarily used by components that bridge different execution environments. For example, an `adk.AgentTool` might catch an `adk.InterruptInfo`, extract the `adk.InterruptCtx` objects from it, and then call this method on each one. The resulting error signals are then typically aggregated into a single error using `compose.CompositeInterrupt` to be returned from the tool's `InvokableRun` method. FromInterruptContexts reconstructs a single InterruptSignal tree from a list of user-facing InterruptCtx objects. It correctly merges common ancestors.
func Interrupt ¶
func Interrupt(ctx context.Context, info any, state any, subContexts []*InterruptSignal, opts ...InterruptOption) ( *InterruptSignal, error)
func (*InterruptSignal) Error ¶
func (is *InterruptSignal) Error() string
type InterruptState ¶
func (*InterruptState) String ¶
func (is *InterruptState) String() string
Source Files