Search⌘ K
AI Features
Home
Courses
Forward Deployed Engineer for AI Systems

The Responses API, Tool Calling, and Structured Outputs

Northstar Equipment Services handles a high volume of support requests each month and uses an AI assistant to prioritize tickets by urgency. The Responses API supports this workflow through tool calls that retrieve ticket data and provide the information needed to compare ticket statuses. The lesson covers conversation state, tool calling, and Structured Outputs, which constrain model responses to a defined JSON Schema. It also explains how the tool dispatcher enforces authorization, validates inputs, and verifies ticket identifiers to prevent unauthorized access or incorrect record selection. The lesson concludes by introducing the OpenAI Agents SDK, which provides higher-level abstractions for agent orchestration, tool execution, and workflow management.

We'll cover the following...

Northstar Equipment Services handles about 18,000 support requests a month. An operator asks the new assistant to compare two tickets and identify which requires attention first. NS-104 is waiting for a replacement part expected in 36 hours. NS-209 has a customer callback due within two hours.

The assistant incorrectly reports that NS-104 needs a callback within two hours and NS-209 is waiting for a replacement part.

The database returned both ticket records correctly, and the model interpreted the information it received as intended. The application matched the database results to tool calls by completion order rather than by their identifiers. When the requests finished out of order, the application associated each result with the wrong tool call.

Changing the model's instructions cannot correct this result-mapping bug. The application must associate each tool result with the correct call identifier, and the FDE is responsible for ensuring the integration handles that correctly.

In this lesson, you'll build Northstar's read-only ticket comparison using the Responses API, which OpenAI recommends for new integrations. You'll examine response objects, conversation state, the tool-calling loop, built-in tools, and the guarantees and limitations of Structured Outputs.

What does a Responses API call return?

The Python SDK is the openai package, and the code widgets in this lesson already have it installed. Add your OpenAI API key in the widget before you run a program: the code reads it from there.

A first call needs a model, the input, and usually some instructions.

Python 3.14.0
from openai import OpenAI
client = OpenAI(api_key="{{OPENAI_API_KEY}}")
MODEL = "gpt-6.1-terra"
INSTRUCTIONS = "You compare Northstar support tickets. You never change tickets or contact anyone."
response = client.responses.create(
    model=MODEL,
    instructions=INSTRUCTIONS,
    input="In one sentence, what can you do and what can't you do?",
    store=False,
)
# An incomplete response can stop before the useful part, so check first.
if response.status != "completed":
    raise RuntimeError(f"response ended as {response.status}")
print("Status:", response.status)
print("Output item types:", [item.type for item in response.output])
print("Answer:", response.output_text)
print("Tokens:", response.usage.input_tokens, "in,", response.usage.output_tokens, "out")

Here’s what each part does:

  • instructions carries the developer’s rules. input carries the user’s request, either as a string or as a list of items.

  • response.status can be completed, incomplete, failed, and a few in-progress states. We check it before reading any output, because an incomplete response can end before the useful part.

  • response.output is a list of items: messages, function calls, reasoning items, and more. output_text is a convenience that joins the text of the message items. If the model asked for a tool, that request is in output, not in output_text.

  • store=False stops the response from being saved for later retrieval through the API. The default is True. It is one data control among several, and it doesn’t amount to a full retention policy on its own.

  • response.usage counts the tokens the call used. The deployment and cost lesson turns those counts into cost.

Below is the output from one run. The answer’s wording changes between runs.

Status: completed
Output item types: ['message']
Answer: I can compare Northstar support tickets, but I can’t change tickets or contact anyone.
Tokens: 39 in, 22 out
Output from one run

The Playground is the fastest place to try instructions and schemas against real examples. Once a request works there, it belongs in code, where the model settings, tool definitions, and checks live in version control and tests can rerun them.

How does conversation state carry between calls?

Each call needs the earlier turns from somewhere. OpenAI’s conversation ...