google__adk-docs/docs/graphs/data-handling.md

Data handling for agent workflows

Supported in ADKPython v2.0.0TypeScript v2.0.0Go v2.0.0

Structuring and managing data between agents and graph-based nodes is critical for building reliable processes with ADK. This guide explains data handling within graph-based workflows and collaboration agents, including how information is transmitted and received between graph nodes. It covers the essential parameters for passing data, content, and state, and explains how to implement structured data transfer for both function and agent nodes using data format schemas and specific instruction syntax.

Workflow data flow

Within a graph-based workflow, nodes pass data to downstream steps through events. A step writes its output to a named event field, and the next step receives it as its typed input.

=== "Python"

In Python, data is exchanged between graph nodes using ***Events***. The key
parameters for node data handling are:

-   **`output`**: Parameter for passing information between *nodes*.
-   **`message`**: Data intended as a response to a user.
-   **`state`**: Data automatically persisted across nodes via ***Events***
    throughout an ADK session.

=== "TypeScript"

In ADK TypeScript v2.0.0, nodes exchange data through events. The key
fields for node data handling are:

-   **`output`**: the value passed to the next node. Return a value
    directly and ADK wraps it in an event, or set the field explicitly
    with `createEvent({output})`.
-   **`content`**: a message for the user. The runtime renders this
    field, but the graph does not pass it to the next node.
-   **`route`**: the routing keys that select which conditional edge to
    follow.

Session state is separate from the event. A node reads and writes state
through `ctx.state`, and the accumulated delta is attached to that
node's events. State keys can carry a prefix that controls their
lifetime and scope:

| Prefix | Scope |
|---|---|
| `app:` | Shared across all users and sessions for the app |
| `user:` | Tied to the user, shared across their sessions |
| `temp:` | Discarded after the current invocation ends |
| *(none)* | Persists for the lifetime of the session |

=== "Go"

In ADK Go v2.0.0, the data-passing mechanism depends on which agent style
you use:

**workflow package** (`FunctionNode`, `AgentNode`, `DynamicNode`): nodes
communicate through `session.Event` fields, mirroring Python closely:

-   **`Event.Output`**: the node's return value, set automatically by the
    framework when a `FunctionNode` returns a non-`*genai.Content` value.
    The successor node receives this as its typed `input` parameter.
-   **`Event.Routes`**: routing keys set explicitly by an emitting node to
    select which conditional edge to follow — the Go equivalent of
    Python's `Event(route=...)`.
-   **`Event.NodeInfo`**: scheduler metadata (`path`, `MessageAsOutput`,
    `OutputFor`). Set by the workflow engine; nodes do not set this
    directly.

**Prebuilt workflow agents** (`sequentialagent`, `parallelagent`,
`loopagent`): these agents communicate through session state:

-   **`OutputKey`** on `llmagent.Config`: the framework writes the agent's
    final text response to `state[OutputKey]` after each turn.
-   **`ctx.Session().State().Set` / `.Get`**: write or read arbitrary
    values from state inside custom code.
-   **`{key}` in `Instruction`**: the framework substitutes `state["key"]`
    into the prompt before calling the model.

State keys may carry a prefix that controls their lifetime and scope:

| Prefix constant | Prefix string | Scope |
|---|---|---|
| `session.KeyPrefixApp` | `"app:"` | Shared across all users and sessions for the app |
| `session.KeyPrefixUser` | `"user:"` | Tied to the user, shared across their sessions |
| `session.KeyPrefixTemp` | `"temp:"` | Discarded after the current invocation ends |
| *(none)* | — | Persists for the lifetime of the session |

Node output

Each step in a workflow produces output for its successor.

=== "Python"

Use the ***return*** or ***yield*** syntax to hand off data to the next node:

```python
from google.adk import Event

def my_function_node(node_input: str):
    output_value = node_input.upper()
    return Event(output=output_value) # "THE RESULT"
```

Use the ***return*** syntax when outputting ***Event*** data that does not
require additional processing. When emitting data that requires additional
processing, or if you are generating more than one data item, you can use
more than one ***yield*** command. Each ***yield*** call adds to a list of
data objects on the Event which is passed to the next node of a graph. A
***return*** or ***yield*** command without a parameter passes a `None` value
to the next node.

=== "TypeScript"

There are three equivalent ways to produce a node's output: return a
value directly, return `createEvent({output})`, or yield events from an
async generator to stream progress alongside the result.

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/node_output.ts:node-output"
```

!!! warning "Caution: emit `output` from one event per execution"

    A node can yield any number of events carrying `output`, and ADK
    does not raise an error in this case. Each event overwrites the
    previous one, and the successor node receives only the final value.
    Use `content` for progress messages instead.

=== "Go"

**workflow package**: a `FunctionNode` simply returns a typed Go value.
The framework automatically wraps the return value in a `session.Event`
and sets `Event.Output`. The successor node receives this value as its
typed `input` parameter — no manual event construction needed:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:event-output"
```

**Prebuilt workflow agents**: use `OutputKey` on `llmagent.Config` to
save an agent's text response to session state, then reference it with
`{key}` in downstream agents' `Instruction` templates:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:output-key"
```

Node output: passing structured data

=== "Python"

You can pass longer, structured data in a serializable format:

```python
def my_function_node_3():
    yield Event(
        output={
            "city_name": "Paris",
            "city_time": "10:10 AM",
        },
    )
```

!!! warning "Caution: Event.output limitation"

    Nodes are only allowed to emit a single ***Event.output*** data payload
    per execution. This limitation means that while you can use more than
    one ***yield*** in a node, having two or more ***yield*** commands with
    an ***Event.output*** results in a runtime error.

=== "TypeScript"

The `output` field is not limited to text. Any serializable value is
passed to the next node, which receives it as a typed object, with no
JSON parsing or state reads required. Attaching an `outputSchema` to the
producing node, or an `inputSchema` to the consuming node, makes the
contract explicit and validates it at runtime:

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/structured_output.ts:structured-output"
```

=== "Go"

**workflow package**: a `FunctionNode` can return any JSON-serializable
Go struct. The framework serializes it into `Event.Output` and
deserializes it back into the successor node's typed `input` parameter.
There is no single-payload restriction — each node has exactly one typed
return value:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:structured-output"
```

**Prebuilt workflow agents**: use multiple `OutputKey` values, one per
agent, to store individual fields in session state. Downstream agents
read each field independently via `{key}` in their `Instruction`.

Routing output

=== "Python"

Use the `route` parameter of an ***Event*** to drive conditional edge
dispatch:

```python
def router(node_input: str):
    return Event(route="BUG")
```

=== "TypeScript"

The `route` value is independent of `output`, so one event can both
select a branch and forward a payload to it. The `DEFAULT_ROUTE` setting
catches any value that no other branch matched:

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/routing_output.ts:routing-output"
```

=== "Go"

**workflow package**: an emitting `FunctionNode` constructs a
`session.Event` directly, sets `Event.Routes` to the desired route keys,
and sets `Event.Output` to forward the payload to the successor. The
workflow engine reads `Event.Routes` at dispatch time to select the
matching edge:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:routing-output"
```

User-facing messages

=== "Python"

Use the ***message*** parameter of an ***Event*** to send a response to a
user rather than pass data to the next node:

```python
async def user_message(node_input: str):
  """Tell user research process is starting."""
  yield Event(message="Beginning research process...")
```

=== "TypeScript"

A message for the user is the event's `content` field. The runtime
renders `content`, but the graph does not pass it to the next node. Use
`content` for the user and `output` for the next node. A node can emit
both by sending two events, where only one carries `output`:

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/user_message.ts:user-message"
```

=== "Go"

**workflow package**: to emit a user-visible message without advancing
the node's typed output, set `Event.Content` on an intermediate event
emitted via the `emit` callback in an `EmittingFunctionNode`. The
terminal return value (or `nil`) controls `Event.Output`.

**Prebuilt workflow agents**: any `llmagent` step automatically emits its
model response as a user-facing event. For non-LLM steps, write a custom
`Run` function on an `agent.Agent` that yields events whose
`LLMResponse.Content` contains the text.

Session state and state scopes

Session state persists data across turns within a session. It is the primary data-sharing mechanism for the prebuilt workflow agents, and is also available inside tools and callbacks regardless of which agent style you use.

=== "Python"

Use the ***state*** parameter of an ***Event*** to maintain values across
nodes. Nodes can modify state values, and the modified state values are
available to downstream nodes:

```python
async def init_state_node(attempts: int = 0):
  yield Event(
      state={
          "attempts": attempts,
      },
  )

async def task_attempt_node(node_input: Content, attempts: int):
  yield Event(
      state={
          "attempts": attempts + 1,
      },
  )

async def read_state_node(ctx: Context):
  print(f"attempts state: {ctx.state}") # attempts state: attempts: 1

root_agent = Workflow(
    name="root_agent",
    edges=[("START", init_state_node, task_attempt_node, read_state_node)],
)
```

!!! warning "Caution: `state` property data limitations"

    The state parameter *should not be used to persist large amounts of
    data* between nodes. Use artifacts or other data persistence mechanisms,
    such as database Tools, to persist large data resources during the life
    cycle of a Workflow.

=== "TypeScript"

Write state through `ctx.state` rather than returning it. A write is
visible to every later node in the same run, and is committed with the
writing node's events:

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/session_state.ts:session-state"
```

!!! warning "Caution: `state` data limitations"

    Session state is a lightweight key-value store. Do not use it to
    move large payloads between nodes; use artifacts or a database tool
    instead. When only the next node needs a value, pass it along the
    edge as node `output`. Use state when a value must outlive the run,
    or be read by a tool, a callback, or `{key}` instruction templating.

=== "Go"

State is written with `ctx.Session().State().Set(key, value)` and read
with `.Get(key)`. The `session` package defines prefix constants that map
to the same lifetime scopes as Python's state parameter. This pattern
applies to prebuilt workflow agents and to tools and callbacks in any
agent style:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:state-scopes"
```

!!! warning "Caution: state data limitations"

    Session state is a lightweight key-value store. Do not use it to persist
    large payloads such as file contents or binary data. Use ADK artifacts
    or external storage tools instead.

!!! tip "workflow package: prefer Event.Output over state"

    For the `workflow` package (`FunctionNode`, `AgentNode`, `DynamicNode`),
    pass data between nodes by returning typed values — the framework sets
    `Event.Output` automatically. Only use `State().Set` when you need to
    share values with tools, callbacks, or agent `Instruction` templates.

Constrain node data with schemas

You can set input and output data schemas to constrain the data formats accepted and produced by any agent node.

=== "Python"

Use `input_schema` and `output_schema` with a class that extends
***BaseModel*** to constrain any agent's input and output:

```python
from google.adk import Agent
from pydantic import BaseModel

class FlightSearchInput(BaseModel):
    origin: str           # Airport code "SFO"
    destination: str      # Airport code "CDG"
    departure_date: date  # date(2026, 3, 15)
    passengers: int = 1   # Number of passengers

class FlightSearchOutput(BaseModel):
    flights: list[Flight]
    cheapest_price: float

flight_searcher = Agent(
    name="flight_searcher",
    instruction="Search for available flights.",
    input_schema=FlightSearchInput,
    output_schema=FlightSearchOutput,
    tools=[search_flights_api],
    mode="single_turn",
    ...
)

assistant = Agent(
    name="assistant",
    instruction="You help users plan trips.",
    sub_agents=[flight_searcher],
    ...
)
```

=== "TypeScript"

Schemas are Zod objects or a genai `Schema`. The location of the schema
determines its effect:

-   The `LlmAgent.outputSchema` option requires the model to answer in
    that shape.
-   The `LlmAgent.inputSchema` option applies only when the agent is
    exposed as a tool. Inside a graph, set the schema that validates a
    node's input on the node itself, using `node(agent, {inputSchema})`.

Agents in a graph must run in `single_turn` mode, which is the default,
or `task` mode.

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/schemas.ts:schemas"
```

=== "Go"

**workflow package**: use `workflow.NewAgentNodeTyped[Input, Output]` to
attach schemas to an agent node. The generic type parameters are reflected
into `*jsonschema.Schema` automatically — no hand-built schema construction
needed. The node's `Event.Output` carries the structured result to the
successor — no `OutputKey` or state write is needed:

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:input-output-schema"
```

**Prebuilt workflow agents**: set `InputSchema` and `OutputSchema` on
`llmagent.Config`. `OutputSchema` forces the model to reply with a JSON
object matching the schema (the agent cannot use tools when `OutputSchema`
is set). Use `OutputKey` to save the JSON string to state for downstream
agents to reference via `{key}` in their `Instruction`.

Access structured data in agents

=== "Python"

Use the curly-brace `{ }` syntax to select properties from the input
schema, or `< >` to select a property and also qualify it by the name
of the source node:

```python
class CityTime(BaseModel):
    time_info: str  # time information
    city: str       # city name

def lookup_time_function(city: str):
    """Simulate returning the current time in the specified city."""
    return Event(output=CityTime(time_info='10:10 AM', city=city))

city_report_agent = Agent(
    name="city_report_agent",
    model="gemini-flash-latest",
    input_schema=CityTime,

    # data selection based on class and parameter
    # instruction="""
    #     Return a sentence in the following format:
    #     It is {CityTime.time_info} in {CityTime.city} right now.
    # """,

    # more restrictive data selection based on source node name
    instruction="""
        Return a sentence in the following format:
        It is <CityTime.time_info from lookup_time_function> in
        <CityTime.city from lookup_time_function> right now.
    """,
)

root_agent = Workflow(
    name="root_agent",
    edges=[
        (START, city_generator_agent, lookup_time_function, city_report_agent)
    ],
)
```

=== "TypeScript"

Two data-selection forms are available inside an agent instruction:

-   The `{Class.field}` form reads a field from this node's input.
-   The `<Class.field from source_node>` form reads a field from a named
    predecessor's output. Use this form when several upstream nodes
    share a field name.

Both forms are distinct from `{state_key}`, which reads session state.
The `Class.` prefix is documentation only; resolution uses the field
name after the dot.

```typescript
--8<-- "examples/typescript/snippets/graphs/data-handling/structured_access.ts:structured-access"
```

=== "Go"

In ADK Go v2.0.0, a `FunctionNode` returns a typed struct and the
framework serializes it into `Event.Output`. The successor `AgentNode`
receives the struct as its user content — the fields are available to the
agent's `Instruction` without any `{key}` template syntax. This is the
direct equivalent of Python's `input_schema=CityTime` with
`{CityTime.time_info}` template placeholders: the struct fields are
delivered as typed input rather than looked up by name from state.

```go
--8<-- "examples/go/snippets/graphs/data-handling/main.go:structured-output"
```

For a complete example of this workflow, see Graph-based agent workflows.