Control Plane Workflows — Conceptual Guide

TL;DR — The control plane gives SCHEMABOUND a structured way to track and execute multi-step agent workflows. Instead of issuing tool calls one at a time with no shared state, clients submit complete plans and drive execution step by step. Each step returns an LlmContextUpdate that carries tool output and schema changes back to the LLM for the next invocation.

Use this page if you need to: understand why stateful workflows exist, learn how plans/steps/LLM context updates work, or decide whether to adopt the control plane for your use case.

The control plane gives SCHEMABOUND a structured way to track and execute multi-step agent workflows. Instead of issuing tool calls one at a time with no shared state, a client can submit a complete plan and drive execution step by step, receiving a feedback object after each step that carries tool output and any schema changes back to the LLM for the next invocation.

Why a Control Plane

A single tool call is stateless. The agent asks a question, SCHEMABOUND answers it, and the conversation moves on. Most production workflows are not that simple — they involve dependent queries, operations that discover schema at runtime, and decisions that build on earlier results.

Without a control plane:

• the LLM must track intermediate state itself, which is unreliable across long conversations
• schema changes that occur mid-workflow reach the LLM late or not at all
• there is no stable record of what the agent intended versus what actually executed

The control plane solves this by making the plan a first-class object that persists through the full execution lifecycle.

Concepts

Plan

A plan is a named, versioned collection of steps with explicit dependency relationships. Steps declare their dependencies with depends_on; the control plane validates the dependency graph before any step executes and rejects cycles.

A submitted plan is assigned a stable plan_id that clients use for all subsequent operations.

Step

Each step in a plan corresponds to one tool call. A step carries:

• a tool_name and tool_intent that govern policy evaluation
• a query_template that may reference prior step output via the {{step.<id>.output}} syntax
• schema_table_hints that tell the control plane which tables to snapshot for schema diffing
• a depends_on list naming steps that must complete before this step can execute

LLM Context Update

When a step finishes, the control plane returns an LlmContextUpdate alongside the step result. This is the explicit feedback object the SDK passes to the next LLM API call.

It carries:

• tool_output_json — the serialised result of the step, ready to include in the next message
• schema_additions — a list of SchemaTableDelta entries (NEW, MODIFIED, or REMOVED) for any tables named in schema_table_hints that changed during step execution
• augmentation_hints — human-readable strings derived from schema deltas, ready to append to the system prompt

The LLM always sees the current schema state before choosing its next action, which means tool definitions stay accurate even when schema evolves mid-workflow.

Template Substitution

Query templates support {{step.<id>.output}} placeholders. The control plane resolves these server-side before calling the query service — the LLM does not need to construct final SQL or query strings directly.

For example, a step template like:

SELECT * FROM orders WHERE customer_id = {{step.lookup_customer.output}}

becomes a fully resolved query once the lookup_customer step has completed and its output is available.

Runtime Context Headers for Control Plane

Steps execute under the same gRPC metadata model as ordinary queries. Two additional headers carry control-plane identity:

These are emitted into query events alongside the standard session, user, and organization fields.

Event Integration

Control-plane events flow through the same global EventBus used by the rest of the runtime. Four new event variants are available to handlers:

Existing AuditLogHandler, QueryMetricsHandler, and SessionActivityHandler receive these events the same way they receive query events — no changes to handler registration are needed.

Schema Topology Integration (Enterprise)

When executing plan steps, the control plane consults schema topology information for foreign-key cascade awareness. This ensures that operations affecting referenced tables trigger appropriate cascade actions across dependent objects without manual orchestration. The topology graph is maintained by a background introspection binary and consulted during step execution to determine safe ordering of related operations.

Reference

For gRPC proto definitions, REST API endpoints, and the WorkflowOrchestrator trait contract, see Control Plane Reference.