Welcome back to Agent Support—a developer advice column for those head-scratching moments when you’re building an AI agent! Each post answers a real question from the community with simple, practical guidance to help you build smarter agents.

💬 Dear Agent Support

I’m building an agent that feeds its response into another app—but sometimes the output is messy or unpredictable. Can you help?

This looks like a job for JSON! While agent output often comes back as plain text, there are times when you need something more structured, especially if another system, app, or service needs to reliably parse and use that response.

🧠 What’s the Deal with JSON Output?

If your agent is handing off data to another app, you need the output to be clean, consistent, and easy to parse. That’s where JSON comes in.

JSON (JavaScript Object Notation) is a lightweight, widely supported format that plays nicely with almost every modern tool or platform. Whether your agent is powering a dashboard, triggering a workflow, or sending data into a UI component, JSON makes the handoff smooth. You can define exactly what shape the response should take (i.e. keys, values, types) so that other parts of your system know what to expect every single time.

Without it? Things get messy fast! Unstructured text can vary wildly from one response to the next. A missing field, a misaligned format, or even just an unexpected line break can break downstream logic, crash a frontend, or silently cause bugs you won’t catch until much later. Worse, you end up writing brittle post-processing code to clean up the output just to make it usable.

The bottom line: If you want your agent to work well with others, it needs to speak in a structured format. JSON isn’t just a nice-to-have, it’s the language of interoperability.

🧩 When You’d Want Structured Output

Not every agent needs to speak JSON, but if your response is going anywhere beyond the chat window, structured output is your best bet.

Let’s say your agent powers a dashboard. You might want to display the response in different UI components—a title, a summary, maybe a set of bullet points. That only works if the response is broken into predictable parts. Same goes for workflows. If you’re passing the output into another service, like Power Automate, an agent framework like Semantic Kernal, or even another agent, it needs to follow a format those systems can recognize.

Structured output also makes logging and debugging easier. When every response follows the same format, you can spot problems faster. Missing fields, weird values, or unexpected data types stand out immediately. It also future proofs your agent. If you want to add new features later, like saving responses to a database or triggering different actions based on the content, having structured output gives you the flexibility to build on top of what’s already there.

If the output is meant to do more than just be read by a human, it should be structured for a machine.

📄 How to Define a JSON Format

Once you know your agent’s output needs to be structured, the next step is telling the model exactly how to structure it. That’s where defining a schema comes in.

In this context, a schema is just a blueprint for the shape of your data. It outlines what fields you expect, what type of data each one should hold, and how everything should be organized. Think of it like a form template: the model just needs to fill in the blanks.

Here’s a simple example of a JSON schema for a to-do app:

{ "task": "string", "priority": "high | medium | low", "due_date": "YYYY-MM-DD" }

Once you have your format in mind, include it directly in your prompt. But if you’re using the AI Toolkit in Visual Studio Code, you don’t have to do this manually every time!

🔧 Create a JSON schema with the AI Toolkit

The Agent Builder feature supports structured output natively. You can provide a JSON schema alongside your prompt, and the agent will automatically aim to match that format.

This takes the guesswork out of prompting. Instead of relying on natural language instructions to shape the output, you’re giving the model a concrete set of instructions to follow.

Here’s how to do it:

1. Open the Agent Builder from the AI Toolkit panel in Visual Studio Code.
2. Click the + New Agent button and provide a name for your agent.
3. Select a Model for your agent.
4. Within the System Prompt section, enter: You recommend a movie to watch.
5. Within the User Prompt section, enter: Recommend a science-fiction movie with robots.
6. In the Structured Output section, select json_schema as the output format.
7. Click Prepare schema.
8. In the wizard, select Use an example.
9. For the example, select paper_metadata.
10. Save the file to your desired location. You can name the file: movie_metadata.
11. In the Agent Builder, select movie_metadata to open the file.
12. Using the template provided, modify the schema to format the title, genre, year, and reason. Once done, save the file.

{ "name": "movie_metadata", "strict": true, "schema": { "type": "object", "properties": { "title": { "type": "string" }, "genre": { "type": "array", "items": { "type": "string" } }, "year": { "type": "string" }, "reason": { "type": "array", "items": { "type": "string" } } }, "required": [ "title", "genre", "year", "reason" ], "additionalProperties": false } }

And just like that, you’ve set up a JSON schema for your agent’s output!

🧪 Test Before You Build

You can submit a prompt with the Agent Builder to validate whether the agent adheres to the JSON schema when returning its response.

When you click Run, the agent’s response will appear in the Prompt tab, ideally in JSON format.

🔁 Recap

Here’s a quick rundown of what we covered:

• JSON lets you create reliable, machine-friendly agent responses.
• JSON is essential for interoperability between apps, tools, and workflows.
• Without JSON, you risk fragile pipelines, broken features, or confusing bugs.
• The AI Toolkit supports including a JSON schema with your agent’s prompt.

📺 Want to Go Deeper?

Check out the AI Agents for Beginners curriculum in which we dive a bit more into agentic design patterns which includes defining structured outputs. We’ll have a video landing soon in the Build an Agent Series that takes you through a step-by-step look of creating a JSON schema for your agent!