0Pricing
AI Agents · Lesson

JSON Mode and Tool-Call Outputs

Use response_format={'type':'json_object'} or a single tool call to force machine-parseable output.

JSON Mode and Tool-Call Outputs is a free AI Agents lesson on CoddyKit — lesson 1 of 4. You can read the complete lesson below for free — then practise it hands-on in the browser with a built-in code editor and a 24/7 AI tutor. It is part of the AI Agents learning path, one of 4 lessons in the course, and your progress syncs across the web and the CoddyKit app.

The Need for Structure

Free-form text from LLMs is hostile to code. Production agents need parseable output: JSON, XML, function arguments — never "the answer is..."

JSON Mode (OpenAI)

Tell the model "always return JSON":

from openai import OpenAI
client = OpenAI()

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=[
        {'role': 'system', 'content': 'Return a JSON object with name and age.'},
        {'role': 'user', 'content': 'Alice, 30 years old.'}
    ],
    response_format={'type': 'json_object'}
)
import json
data = json.loads(response.choices[0].message.content)

JSON Mode Caveat

JSON mode only guarantees valid JSON — not your SHAPE. The model could return {} or {"foo": "bar"}. Always validate the shape too.

Structured Outputs (Strict)

OpenAI Structured Outputs guarantees the response matches a JSON Schema:

schema = {
    'name': 'person',
    'schema': {
        'type': 'object',
        'properties': {
            'name': {'type': 'string'},
            'age': {'type': 'integer'}
        },
        'required': ['name', 'age'],
        'additionalProperties': False
    },
    'strict': True
}

response = client.chat.completions.create(
    model='gpt-4o-2024-08-06',
    messages=...,
    response_format={'type': 'json_schema', 'json_schema': schema}
)

How Strict Mode Works

Strict mode constrains the decoder so the model literally cannot produce an invalid token. The output 100% matches the schema.

Tool Calls as Structured Output

You can force a specific tool call as a way to extract structured data:

tools = [{'type': 'function', 'function': {
    'name': 'submit_person',
    'parameters': {
        'type': 'object',
        'properties': {'name': {'type': 'string'}, 'age': {'type': 'integer'}},
        'required': ['name', 'age']
    }
}}]

response = client.chat.completions.create(
    model='gpt-4o-mini',
    messages=...,
    tools=tools,
    tool_choice={'type': 'function', 'function': {'name': 'submit_person'}}
)
args = json.loads(response.choices[0].message.tool_calls[0].function.arguments)

Anthropic Tool-Use as Output

Anthropic has the same pattern with tool_choice="tool":

tool_choice = {'type': 'tool', 'name': 'submit_person'}
print(tool_choice)

JSON via Pre-filling (Anthropic)

For Claude without tools, pre-fill the assistant turn with {

messages = [
    {'role': 'user', 'content': 'Give me JSON for Alice, 30.'},
    {'role': 'assistant', 'content': '{'}
]
# Output starts with { and likely produces valid JSON.
for m in messages:
    print(f"{m['role']}: {m['content']}")
print("Output starts with { and likely produces valid JSON.")

Pydantic + Strict Mode

OpenAI Python SDK has a Pydantic shortcut:

from pydantic import BaseModel

class Person(BaseModel):
    name: str
    age: int

response = client.beta.chat.completions.parse(
    model='gpt-4o-2024-08-06',
    messages=...,
    response_format=Person
)
person = response.choices[0].message.parsed
# Pydantic instance, type-safe

Common Pitfalls

  • JSON mode without strict — model can return wrong shape
  • Forgetting additionalProperties: false in strict
  • Required fields not listed in "required" array
  • Strict mode is gpt-4o-2024-08-06+ only

Cost of Structured Outputs

Strict mode has minor overhead from grammar-constrained decoding — negligible vs the quality benefit. Always on when shape matters.

Combine With Validation

Even strict outputs should be validated by Pydantic afterwards. Defense in depth — catches edge cases like out-of-range integers.

Strict Mode Guarantee

What does OpenAI Structured Outputs (strict mode) guarantee?

Recap

JSON mode for permissive structure, Strict Outputs for guaranteed shapes, tool calls for the same effect, Anthropic pre-fill for Claude. Always validate after.

Frequently asked questions

Is the “JSON Mode and Tool-Call Outputs” lesson free?

Yes — the full text of “JSON Mode and Tool-Call Outputs” is free to read here on the web, and the AI Agents course includes 4 lessons in total. To practise it interactively (a built-in code editor and a 24/7 AI tutor) and unlock the rest of the AI Agents course, upgrade to CoddyKit PRO.

What will I learn in “JSON Mode and Tool-Call Outputs”?

Use response_format={'type':'json_object'} or a single tool call to force machine-parseable output. You practise AI Agents with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start AI Agents?

No prior experience is required. AI Agents on CoddyKit is structured for beginners through advanced learners; this is — lesson 1 of 4, so you can start here or from the beginning and move at your own pace.

How long does the “JSON Mode and Tool-Call Outputs” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this AI Agents lesson?

Yes. Every AI Agents lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

  1. JSON Mode and Tool-Call Outputs
  2. Pydantic Schema Validation
  3. Repair Loops for Malformed Output
  4. Instructor / Outlines for Guaranteed Structure
← Back to AI Agents