Getting Structured JSON from Agent Mode with a Response Schema

Attach a Response Schema to an Agent mode Connector node so the AI returns predictable JSON fields you can map into later steps, and learn when forcing structure is worth the extra AI cost.

Overview

A Connector node in Agent mode lets an AI agent read a prompt, decide which connector tool or tools to call, and reason across several steps. By default the agent returns free-form text, which is hard to wire into the rest of your workflow because the wording changes from run to run. A Response Schema solves this: it is an optional JSON schema you attach to the Agent mode node that forces the agent to return its answer as structured JSON with the exact fields you defined. Once the output is structured, you can reference individual fields downstream with variables like {{ classify.category }} instead of parsing a paragraph of prose.

The mental model is simple: Agent mode without a schema is a conversation, and Agent mode with a Response Schema is a form the agent must fill in. Spojit hands the schema to the intelligent layer along with your prompt, and the node's output variable then holds an object whose shape matches the schema. This makes Agent mode safe to feed into a Condition node, a Transform node, or another Connector node that needs clean inputs. You still pay AI credits for Agent mode runs, so the goal is to force structure only where a downstream step actually depends on it.

Before You Start

A workflow open in the Spojit Workflow Designer with a Connector node already on the canvas.
A connection set up for the connector whose tools the agent will call (for example a Shopify or Slack connection), if the agent needs to take actions rather than only reason over data passed in.
A clear idea of the exact fields you want back, since the schema defines the contract for every run.

Steps

Follow these steps to switch a Connector node to Agent mode and force structured JSON output.

Step 1: Switch the Connector node to Agent mode

Click the Connector node on the canvas to open the properties panel on the right. Set the mode selector to Agent mode. Unlike Direct mode, where you pick one tool and map its inputs by hand, Agent mode lets the agent choose tools for you based on the prompt. Pick the connector the agent is allowed to use so its tools are available to the agent during the run.

Step 2: Write the prompt

In the Prompt field, describe the task in plain language and reference upstream data with handlebars variables, for example {{ input.text }} or {{ order.lineItems }}. Be specific about what you want the agent to produce. If you are about to attach a Response Schema, you do not need to spell out the JSON shape in the prompt itself, because the schema already enforces it, but a short reminder such as "classify this message" keeps the agent focused on the right outcome.

Step 3: Attach the Response Schema

In the properties panel, open the Response Schema field and paste a JSON schema describing the object you want back. Define each field name and its type, and mark the fields the agent must always return as required. For a support-ticket classifier you might use:

{
  "type": "object",
  "properties": {
    "category": { "type": "string", "enum": ["billing", "shipping", "technical", "other"] },
    "priority": { "type": "string", "enum": ["low", "normal", "high"] },
    "summary":  { "type": "string" }
  },
  "required": ["category", "priority", "summary"]
}

Using an enum for fields like category and priority keeps the agent's answers inside a fixed set of values, which is what makes them safe to branch on later.

Step 4: Set the Output Variable

Give the node a clear Output Variable name, for example classify. When the run finishes, that variable holds an object shaped exactly like your schema, so downstream steps can read {{ classify.category }}, {{ classify.priority }}, and {{ classify.summary }}.

Step 5: Map the structured fields downstream

Connect the Connector node to the next step and reference the schema fields directly. A common pattern is a Condition node that checks {{ classify.priority }} equals high and routes the true branch to a Send Email node or a Slack send-message call. Because the schema guarantees the field exists and holds one of the allowed values, your branching logic stays reliable across every run.

Step 6: Test and confirm the shape

Run the workflow and open the execution log for the Agent mode node. Confirm the output matches your schema field for field. If a field is missing or holds an unexpected value, tighten the schema (add the field to required or constrain it with an enum) and sharpen the prompt, then run again.

When Forcing Structure Is Worth the AI Cost

Agent mode consumes AI credits on every run, and a Response Schema does not change that. Reach for a schema when a later step must read specific fields: branching in a Condition node, mapping values into a connector tool such as Shopify create-order, or building a row to insert with MongoDB insert-documents. In those cases structured output removes brittle text parsing and is well worth the cost.

If the agent's result is only ever read by a human, for example a one-line summary dropped into a Send Email body, a schema adds little value and you can leave the output as free-form text. And if the task is a single, predictable tool call with no judgement involved, consider Direct mode instead: it runs the exact tool you choose with no AI credits at all.

Tips

Keep schemas small. Ask only for the fields a downstream step actually consumes; every extra field is more for the agent to reason about and more chance of drift.
Constrain string fields with an enum wherever the value feeds a Condition node, so branches always match one of a known set of values.
Name the Output Variable after the job (classify, extracted, scored) so the variables you reference downstream read clearly.
Let Miraxa, the intelligent layer across your automation, scaffold the node for you with a prompt like "Add a Connector node in Agent mode that classifies {{ input.text }} and returns category and priority as JSON", then fine-tune the schema in the properties panel.

Common Pitfalls

Mapping a field the schema does not guarantee. If a property is not in required, the agent may omit it and your downstream {{ var.field }} resolves empty. Add every field you depend on to required.
Invalid JSON in the Response Schema field. A stray comma or unquoted key means the schema will not save; paste valid JSON and confirm the node saves cleanly before running.
Using Agent mode for a single deterministic call. If you already know the exact tool and inputs, a schema cannot remove the AI cost; switch to Direct mode instead.
Free-text values where you needed fixed options. Without an enum, the agent might return "urgent" one run and "High" the next, breaking equality checks in a Condition node.