Python Code

The Python Code block lets you execute fully custom logic within a Structured Visual Agent.

The block runs a configured Python function from the block code.

The function can be:

• a regular function that returns text or a NextBlock

• a generator function that yields one or more output chunks, and can also yield a NextBlock

Each yielded chunk is streamed to the user as soon as it is produced. Output chunks can be a plain string or a dict of the form {"chunk": {"text": "..."}}.

If the function does not return or yield a NextBlock, execution continues with the default next block.

Special variables

A number of special variables are exposed in the scope of the Python block, allowing the Python code to interact with the Structured Visual Agent.

State and scratchpad

Access the agent’s state and scratchpad using the Python dictionaries state and scratchpad. These are both readable and writable.

For example:

• Reading a state value: my_var = state["state_param_name"]

• Writing a scratchpad value: scratchpad["scratchpad_param_name"] = my_var

Output of other blocks

Access the last text output from a previous block using the Python string last_output. This variable is read-only. It is None if no previous block produced text output in this turn.

Access the sources and artifacts generated by previous blocks in the current turn, using the Python lists sources and artifacts. These are both readable and writable.

Conversation history

Access the agent’s current conversation messages using the Python lists:

• initial_messages: The messages passed to this turn of the agent, for example previous user/agent conversation history.

• generated_messages: Any messages produced by the agent during this turn, for example tool calls.

• all_messages: The full conversation history that is passed to other blocks such as the agentic loop block. This is read-only, and is initial_messages + generated_messages.

While both initial_messages and generated_messages are writable, modifications to initial_messages will only affect later blocks in the current turn, not subsequent turns (because the agent’s caller will send the same initial messages on the next turn) but modifications to generated_messages will affect subsequent turns (if short term memory is enabled).

Agent context

Access the context passed to the agent using the Python dictionary context.