Agents SDK & Apps SDK

Last updated：2026-08-12· 16 min read

🚀 Quick access

ChatGPT Domestic：Open entry↗
Mirror site：Open mirror↗
Official ChatGPT：chatgpt.com ↗

Last updated: 2026-08-12

Overview

A single responses.create suffices for FAQ; when flows become “detect intent → query DB → call HTTP → escalate → output JSON,” hand-written tool loops get brittle. Agents SDK wraps Agent, Tool, Handoff, and Guardrail into testable orchestration—still backed by Responses API. Apps SDK targets interactive apps inside the ChatGPT client. Class names, package names, and supported languages follow Agents docs and official GitHub—verify imports before production.

Core concepts

Runner.run(Agent, user_input)
  → LLM: answer directly | call Tool | Handoff to another Agent
  → Guardrail blocks non-compliant input / output
  → trace records each step → final_output

Concept	Role
Agent	Bundle of instructions + model + tools
Tool	Callable capability—functions, retrieval, MCP, etc.
Handoff	Dynamically delegate session to a specialist Agent
Guardrail	PII, jailbreak, format validation
Runner	Drives multi-turn reason–execute loop

The SDK is an orchestration layer, not a new model; cost still comes from Responses tokens and tool usage.

Agents SDK vs plain Responses?

No tools, single turn? ──yes──→ responses.create is enough
       │
       no
       ↓
Fixed 1–2 tools, ≤3 steps? ──yes──→ hand-written tool loop (simpler)
       │
       no
       ↓
Multi-agent routing / need trace? ──yes──→ Agents SDK

Scenario	Recommendation
FAQ, one-shot summary	Plain Responses
Fixed order lookup + reply	One function loop
Support triage, specialist agents	Agents SDK + Handoff
Debug/audit every step	Agents SDK trace
Public ChatGPT distribution	Apps SDK

Principle: MVP on Responses first; add Agents SDK when complexity warrants—avoid over-engineering.

Minimal Python example

Import paths per official repo—conceptual code:

from agents import Agent, Runner, function_tool

@function_tool
def get_order_status(order_id: str) -> str:
    """Look up order status (example—wire to real DB)"""
    return f"Order {order_id}: shipped"

agent = Agent(
    name="OrderBot",
    instructions="You are an e-commerce assistant. Use get_order_status for lookups. Be concise.",
    tools=[get_order_status],
    model="gpt-4o",  # verify current ID on Models page
)

result = Runner.run_sync(agent, "Where is order 8821?")
print(result.final_output)

Handoff routing

billing = Agent(name="Billing", instructions="Handle invoices and refunds only")
general = Agent(
    name="General",
    instructions="Answer general questions; hand off billing topics to Billing",
    handoffs=[billing],
)

Handoffs keep each Agent’s instructions short—easier independent eval and iteration.

Guardrails and side-effect safety

Layer	Examples
Input guardrail	Block PII, jailbreak, oversized payload
Output guardrail	JSON schema, no system leak
Tool layer	Order id format, rate limits, permission checks

Non-negotiable: transfers, deletes, emails must be re-validated server-side; guardrails assist, not replace authorization.

Observability and evaluation

SDK trace / span: see each model and tool step—faster incident response
Per-Agent eval sets (official evals docs)
Subtasks may use Fine-tuning for classification/format; orchestration stays Agents

Apps SDK: ChatGPT ecosystem

	Agents SDK	Apps SDK
Runs on	Your servers	ChatGPT client surface
Audience	Internal copilot, backend automation	End users, platform discovery
Auth	Your API key / OAuth	Platform review + connection spec
Typical	Support orchestration, ETL	SaaS entry inside ChatGPT

Manifest, OAuth, review flow: OpenAI Apps developer docs; may separate from Platform project config.

Relationship to Assistants

Assistants (Thread / Run / Vector Store) is an earlier hosted shape; official direction converges on Responses + Agents SDK. Legacy: Assistants guide; don’t invest in Thread model for greenfield.

Reference architecture

User → ChatGPT App (Apps SDK) or your API
         → Agents SDK (handoff / guardrails)
           → Responses API
             → business DB | [Embeddings RAG](/en/guides/openai-dev/embeddings/) | HTTP

Multimodal input: Vision guide.

Frequently asked questions

Does Agents SDK cost extra?

SDK is open source; charges come from underlying model and hosted tools. See pricing page.

Python only?

Official support is typically multi-language; concepts transfer—check repos.

Handoff vs fine-tuning for routing?

Handoff is runtime routing; fine-tuning changes weights. Stable intents often work with handoff + small model.

Apps SDK availability?

Subject to platform policy, OAuth, and network; complete OpenAI developer registration and compliance.

Agent loops tools forever?

Set max_turns; per-tool timeout, idempotency, and call caps.

Official resources

Next reading

Action path

Today: Read Agents Quickstart; run single Agent + single tool. Tomorrow: Add Handoff second Agent; test 5 multi-intent queries. This week: Server-side validation on dangerous tools + enable trace; evaluate Apps SDK registration if ChatGPT distribution is a goal.