Structured Response Tool

The Structured Response Tool configures your agent to respond in JSON with a schema you provide.

How To Add

In Agent Studio, open Agent Tools, click Add Tool, and choose Structured Response.

Fill in three things:

• Schema Name — what the shape is called, for example BookSummary.
• Schema Description — a description of the schema. An example description for BookSummary would be, This schema contains information about a book in our inventory.
• Schema Fields — describe the fields (items) that make up your schema.

All three are required. Deploy to Test or Live and your agent answers with the shape from that point on.

The Field Types

Type	What your agent sends	Example value
Text	A string.	"Dune"
Number	Any number.	12.99
Whole Number	A number with no decimal part.	412
Yes / No	true or false.	true
Choice	One of the values you list.	"happy"
List of …	A list whose items are all one type: text, numbers, whole numbers, yes/no values, choices, or groups.	["sci-fi", "classic"]
Group of Fields	An object with fields of its own.	{ "name": "Frank Herbert" }

Field names use letters, digits and _, and start with a letter. They cannot contain spaces or hyphens, because some models will not produce them as keys—use favorite_book, not favorite-book.

Every Field Is Always Present

Every field you define is in every structured response, at every level. Only the values change:

• A Text, Number, Whole Number, Yes / No or Choice field that the agent could not fill comes back as null.
• A List is always a list. With nothing to put in it, it comes back as []—never null.
• A Group is always an object. If the agent could not fill it, each of its fields is null.

We use null rather than 0, false or "" because those are real values. A price of 0 and "no price found" must look different.

Because no field ever appears or disappears, your app can walk the same tree on every response.

A Worked Example

A bookshop wants its agent to return a summary of a book. In the card, the shape is:

Field name	Type	Description
title	Text	The book's title.
price	Number	Retail price in GBP.
mood	Choice: happy, sad, neutral	The overall tone.
genres	List of … Text	Every genre that applies.
author	Group of Fields, holding name (Text)	Who wrote it.

A request for Dune, where the agent could not find a price, returns:

200 OK
{
  "agent_response": null,
  "agent_structured_response": {
    "title": "Dune",
    "price": null,
    "mood": "neutral",
    "genres": ["science fiction", "classic"],
    "author": { "name": "Frank Herbert" }
  },
  "agent_structured_response_status": "provided"
}

price is null because the agent did not invent a price it could not find. The key is still there.

Read the object only when agent_structured_response_status is provided. The Response-Agent reference describes the other two statuses.

Import a JSON Schema

If you already have a JSON Schema for the shape, choose Paste a JSON Schema on the card. The card converts its properties into fields, in order, and then discards the text. It is a one-time conversion, not a second way to edit.

• required is ignored, because every field is always present.
• A property that allows null becomes a plain field; every field can be null anyway.
• A keyword the builder has no field for, such as format or oneOf, is refused, and the card names where it was found.

Limits

• Up to 100 fields in total, counting the fields inside groups.
• Up to 3 levels of fields in the builder—for example, a field inside a group inside a group.
• One level of container per field: a list can hold groups, but it cannot hold lists.

The card also shows the Generated JSON Schema that your fields produce, read-only and ready to copy.

Test and Live

A shape is part of the agent build, and each environment has its own build. Build and test the shape in Test, then deploy to Live. Until you do, your live app receives not_configured.

Removing It

Press Remove on the card and deploy. Your agent goes back to answering in text: agent_response holds the answer and the status is not_configured.

What It Costs

A structured response is billed exactly like a text one. See Pricing.