Skip to main content
Version: Next

Structured Visual Agents

A simple agent hands the model a prompt, some tools, and a knowledge base, and lets it decide what to do. A structured visual agent replaces that open loop with an explicit graph of typed blocks — routing, LLM calls, tool calls, state, output — so you control exactly how the agent responds. Use it when you need determinism, inspectability, or a fixed multi-step procedure rather than free-form tool use.

Any simple agent converts losslessly to a structured one: it becomes a single Agentic Loop block that behaves identically. Start structured only when you outgrow the single loop.

Agent kinds​

Agent Builder offers three kinds:

KindRuntime
VisualThe block graph described on this page.
CodeA Python function you write — see Code agents.
PluginPackaged agent from a plugin (backend runtime pending — shown "Coming soon").

The block graph​

A structured agent is a graph of blocks executed by the block-graph runtime. State flows between blocks; edges can carry conditions. The block kinds:

GroupBlocks
Control flowrouting, core_loop (agentic loop), for_each, parallel, reflection
LLM & toolsllm_request, tool_call, delegate (call another agent)
State & memoryset_state, set_scratchpad, context_compression, memory_retrieve, memory_store
Outputoutput (CEL / Jinja template), generate_artifact, python
Feedbackfeedback_use, feedback_detect

Routing​

A routing block chooses the next block from its conditions. Conditions are recursive AND/OR trees evaluated with CEL, so you can express "if the question is about revenue AND the period is closed, go to the revenue branch." On a follow-up turn, smart subsequent-turn mode lets the model pick the entry block from the graph's catalog rather than always restarting at the root.

CEL expressions​

Edge conditions and output templates use a small Common Expression Language engine. It is sandboxed by construction — a pure AST walk with no eval, no dunder access, and no imports — and guards against pathological inputs (e.g. sequence-repetition blow-ups). Use it for conditions (answer.rows > 0) and for shaping the final string.

State, scratchpad & memory​

set_state / set_scratchpad write into the run's working state, which persists on chat_sessions.agent_state. context_compression summarizes prior context to stay under the token budget. memory_retrieve / memory_store read and write the agent's conversational and semantic memory.

Output templates​

An output block renders the final answer from a template. Two template types: a CEL expression, or a Jinja "Emit-Output" template rendered in a SandboxedEnvironment with StrictUndefined (a missing variable errors loudly rather than emitting an empty string).

The Design view​

The graph is authored in a visual flow-graph Design view (rich node cards, edge condition labels). Turn on drag-to-wire editing (the editable toggle) to connect, rewire, and remove edges directly on the canvas. Tools appear as first-class nodes.

Code agents​

The Code agent kind runs Python you write. Define:

def agent(query, context):
    # return a string, or yield strings to stream
    return f"You asked: {query}"

Your function returns a str (or an Iterator[str] to stream token-by-token). It runs subprocess-isolated with a 60-second wall-clock timeout, and is served on both /chat and /chat/stream.

See also​