Module functional

Available on crate features functional and graph only.

Expand description

§Functional API for Graph Workflows

The Functional API provides a higher-level programming model for adk-graph that allows developers to write agent workflows as normal async Rust functions with automatic checkpointing, typed state reducers, and interrupt/resume support.

§Overview

Rather than manually constructing nodes, edges, and routers, developers annotate functions with #[entrypoint] and #[task] macros and use standard Rust control flow (if, for, match, loop) to express workflow logic.

This module is gated behind the functional feature flag.

§Features

TaskContext: Runtime context for tasks providing state, checkpointing, and streaming
ReducedValue<T>: Append-only state container persisted across checkpoints
UntrackedValue<T>: Transient state container excluded from checkpoints
MessagesValue: Chat message container with ID-based deduplication
TypedReducer: Custom merge strategies for typed state values
ExecutionLog: Task completion tracking for resume-skip behavior
StateSchemaValidator: Schema validation for initial state and task output

§Quick Start

use adk_graph::functional::{TaskContext, ReducedValue, MessagesValue};
use adk_rust_macros::{entrypoint, task};

#[task]
async fn fetch_data(ctx: &mut TaskContext) -> Result<String, FunctionalError> {
    ctx.emit(serde_json::json!({"status": "fetching"})).await;
    Ok("data result".to_string())
}

#[task(retry(max_attempts = 3, backoff = "1s"))]
async fn process(ctx: &mut TaskContext, data: &str) -> Result<String, FunctionalError> {
    Ok(format!("processed: {data}"))
}

#[entrypoint]
async fn my_workflow(ctx: &mut TaskContext) -> Result<(), FunctionalError> {
    let data = fetch_data(ctx).await?;
    let result = process(ctx, &data).await?;
    ctx.set("output", serde_json::json!(result));
    Ok(())
}

§Typed State Reducers

use adk_graph::functional::{ReducedValue, UntrackedValue, MessagesValue, ChatMessage, MessageRole};

// Append-only accumulator — persisted across checkpoints
let mut results: ReducedValue<String> = ReducedValue::default();
results.push("step 1 output".to_string());
results.push("step 2 output".to_string());
assert_eq!(results.len(), 2);

// Transient value — excluded from checkpoints
let mut temp: UntrackedValue<Vec<u8>> = UntrackedValue::default();
temp.set(vec![1, 2, 3]);

// Chat messages with deduplication
let mut messages = MessagesValue::default();
messages.push(ChatMessage {
    id: "msg-1".to_string(),
    role: MessageRole::User,
    content: "Hello".to_string(),
    metadata: Default::default(),
});

Modules§

execution_log: Execution log for tracking task completion status within a workflow run.
messages: Chat message container with ID-based deduplication.
reducers: Typed state reducers for the Functional API.
schema: State schema validation for the functional API.
typed_reducer: Typed reducer trait and built-in reducer implementations.

Structs§

AppendReducer: Built-in reducer: append to a Vec (list concatenation).
ChatMessage: A chat message with a unique identifier.
ExecutionLog: Tracks task completion status within a workflow run. Stored as part of the checkpoint metadata.
MergeReducer: Built-in reducer: deep merge for JSON-like structures.
MessagesValue: Chat message container with ID-based deduplication.
ReducedValue: Append-only state container. Accumulates values across tasks. Persisted to checkpoints on each task completion.
ReplaceReducer: Built-in reducer: replace with incoming value (last-write-wins).
StateSchemaValidator: Validates workflow state against a declared schema.
TaskContext: Runtime context passed to #[entrypoint] and #[task] functions.
TaskRecord: A record of a single task’s execution state.
UntrackedValue: Transient runtime value excluded from checkpoints.

Enums§

ExpectedType: Expected JSON value type for a state field.
FunctionalError: Errors specific to the functional API.
MessageRole: A chat message role indicating the sender of a message.
TaskStatus: The lifecycle status of a task within a workflow execution.

Traits§

TypedReducer: Trait for defining custom merge strategies for state values.