version: "1.0.0" name: agents-openai description: Build agents on OpenAI's platform patterns — assistants-style threads, function calling, structured outputs, and multi-step tool workflows. Use when working with OpenAI models as the agent engine. category: ai-research

Agents on OpenAI Platform Patterns

OpenAI's agent-building surface centers on a few primitives: chat models with native function calling, structured outputs, persistent threads for conversation state, and file/code-interpreter tools. This skill covers using them as an agent substrate.

Overview

The core loop: the model reasons, emits function calls with structured arguments, your code executes them, results go back into the conversation, repeat. Structured outputs (JSON schema mode) make the model's responses machine-readable. Threads persist conversation state server-side so you don't manage history yourself. Built-in tools — code execution, file search — cover common needs without custom tooling. Your architecture decisions sit on top: when to call functions vs. answer, how to manage the loop, where humans intervene.

When to use

• Building an agent or assistant powered by OpenAI models.
• Needing reliable function calling with validated arguments.
• Prototyping quickly with managed threads and built-in tools before custom infrastructure.
• Migrating from raw chat completions to a structured agent loop.

Core concepts

• Function calling: the model emits structured calls to your functions; you execute and return

results. Define functions with clear names, descriptions, and JSON schemas.

• Structured outputs: schema-constrained generation — the model must return valid JSON

matching your schema. Eliminates parsing hacks for data extraction and tool args.

• Threads: server-side conversation state — messages, tool outputs, file attachments persist

across calls. Simplifies long sessions; know the retention and cost implications.

• Built-in tools: code interpreter (run code, analyze files), file search (retrieval over your

documents). Evaluate them before building custom equivalents.

• The run loop: create a run, poll for status, handle required actions (tool calls), submit

outputs, repeat. Manage timeouts and step budgets yourself.

• Instructions hierarchy: system-level instructions steer behavior across the thread;

per-message instructions handle the immediate turn. Keep the persistent instructions lean.

Practical workflow

1. Define functions with precise schemas; test them standalone before the model ever calls them.
2. Write thread-level instructions covering role, scope, and guardrails — short and durable.
3. Implement the run loop with a step cap, timeout, and handling for every terminal state

(completed, failed, expired, cancelled).

1. Use structured outputs wherever your code consumes the result — never parse free text you

could have schematized.

1. Evaluate built-in tools on your data before building custom retrieval or execution.
2. Log every run: inputs, tool calls, outputs, tokens. Debug from the trace, not from memory.

Run loop checklist:
[ ] Functions defined + tested standalone
[ ] Step budget and timeout set
[ ] All terminal states handled (completed/failed/expired/cancelled)
[ ] Structured output schemas for machine-consumed results
[ ] Run logging: messages, tool calls, tokens
[ ] Human gate before irreversible tool actions

Common pitfalls

• Unbounded runs: polling forever on a stuck run. Cap steps and time; handle expiry explicitly.
• Bloated instructions: thread instructions that grow into mega-prompts. Keep them minimal; put

task context in messages.

• Trusting tool args blindly: the model can emit plausible-but-wrong arguments. Validate before

executing, especially writes.

• No state hygiene: threads growing unboundedly. Summarize or truncate old turns; know

retention limits.

• Built-in tool assumptions: file search or code execution behaving differently than expected

on your data. Test on your corpus first.

• Ignoring cost: threads + tool calls + long contexts add up. Track per-thread spend and set

budgets.