Index of every page on this site: llms.txt
All skills
pydantic avatar

/migrating-openai-agents-sdk-to-pydantic-ai

@b2d64a3
by pydanticpydantic/pydantic-ai21k stars
3,221
Run it yourself

Migrate Python OpenAI Agents SDK applications to Pydantic AI and, when warranted, Pydantic AI Harness. Use for `agents.Agent`, `Runner`, function tools, handoffs, guardrails, sessions, human approval, streaming, or `SandboxAgent`. Do not use for applications built directly on the OpenAI Responses API without the Agents SDK runtime.

  • 4 files
  • 23.1 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/pydantic/pydantic-ai/migrating-openai-agents-sdk-to-pydantic-ai

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

referencesCONCEPT-MAPPING.md

≈2.5k tokens on demand. Your agent reads this file only when SKILL.md points to it.

Concept Mapping

Use this reference only for features present in the active source path. Confirm the source and target behavior against the installed versions before editing code.

Core agent and tools

OpenAI Agents SDK First Pydantic AI seam What to verify
Agent, Runner.run() / run_sync() reusable Agent, run() / run_sync() input, output, errors, model requests, and tool loop
static or callable instructions instructions or @agent.instructions dynamic values and what becomes model-visible
RunContextWrapper.context typed deps and RunContext.deps trusted identity and clients never become tool arguments
@function_tool / FunctionTool @agent.tool, @agent.tool_plain, Tool, or a toolset name, description, schema, validation, retries, error shape, and side effects
output_type output_type, optionally NativeOutput or ToolOutput provider transport, validation, retry, and public wire shape
tool_use_behavior terminal result output function or ToolOutput which call wins, whether sibling tools execute, and terminal value
ModelSettings and RunConfig agent/run model, model_settings, UsageLimits, and hooks precedence, provider support, retry/counting, and failure behavior
ModelBehaviorError / tool input correction Pydantic validation plus ModelRetry where the model can correct the call retry budget and caller-visible terminal error
Agent.clone(...) variants construct an explicit configured variant; use Agent.override(...) only for a scoped temporary override shared tool containers, concurrent isolation, and variant lifetime

OpenAI hosted tools do not all share one replacement:

  • Map web search, file search, code execution, image generation, and hosted MCP to Pydantic AI native tools only when the model profile supports them and their outputs/events are sufficient.
  • Map local function tools and local MCP servers to Pydantic AI tools or MCPToolset.
  • Treat OpenAI ComputerTool, ShellTool, ApplyPatchTool, and SandboxAgent as execution-boundary decisions. Harness FileSystem, Shell, Coder, and ModalSandbox are candidates, not drop-in equivalents. Preserve workspace, process, network, secret, and cleanup boundaries with real integration tests.
  • OpenAI hosted execution and skills may be provider-owned. Harness skills expose SKILL.md guidance to the model; they do not imply the same hosted container, file materialization, or provider tool behavior.

Orchestration

OpenAI exposes two distinct LLM-directed patterns:

Source behavior Candidate target Semantic difference
Agent.as_tool() a Pydantic AI tool that runs a specialist, or Harness SubAgents manager remains in control in both designs, but history, usage, limits, approval, and event propagation require explicit tests
handoff application router, a typed routing output followed by another agent run, or an explicit orchestration layer OpenAI changes the active agent inside the same run; a Pydantic AI tool call normally returns to the caller

Do not replace a handoff with a subagent merely because both invoke a specialist. Inventory these contracts first:

  • whether the specialist or manager writes the final answer;
  • whether the receiving agent sees full, filtered, or nested history;
  • whether handoff metadata is model-generated and validated;
  • which input/output guardrails run;
  • lifecycle event names and ordering;
  • whether last_agent selects the next conversational turn;
  • parent/child usage, limits, retries, and cancellation.

Use plain Python for deterministic routing. Use pydantic-graph only when explicit typed nodes, branching, or persisted workflow state remain useful.

Guardrails and hooks

Harness provides InputGuardrail, OutputGuardrail, and ToolGuardrail, but matching names are not parity evidence.

OpenAI behavior Required decision or proof
input guardrails apply to the first agent only identify the actual public input boundary and test handoff/subagent paths
input guardrails run in parallel by default choose sequential blocking when no model/tool work may start, or accept and test speculative work
output guardrails apply to the final agent only prove the same terminal boundary and sanitization/error contract
tool guardrails wrap eligible local tools, not all hosted tools or handoffs enumerate tools actually covered and enforce security below the model layer
tripwires raise SDK-specific exceptions preserve the API error shape with an adapter or accept a documented change
RunHooks span a run and AgentHooks scope to one agent map observations to Pydantic AI hooks/capabilities and test order across delegation
call_model_input_filter replaces model input immediately before a request use a focused model-request hook or message-history processor and prove every request shape

Guardrails are policy, not authentication or isolation. Authorization belongs inside application services and protected tools, using authenticated dependencies.

State, sessions, and approval

Choose one state strategy per observed contract:

OpenAI source Meaning Target owner
result.to_input_list() caller-managed replay-ready conversation input core message_history, serialized with ModelMessagesTypeAdapter; application owns storage
Session SDK loads, merges, and persists client-managed history Core ConversationStore or an application history repository; add Harness StepPersistence only when its settled snapshots/event/effect semantics are wanted
previous_response_id OpenAI Responses server-side chain OpenAIResponsesModelSettings.openai_previous_response_id; verify storage/ZDR and reasoning continuity
OpenAI conversation_id OpenAI Conversations API state OpenAIResponsesModelSettings.openai_conversation_id; do not confuse it with Pydantic AI's correlation conversation_id
RunState plus interruptions resumable paused execution with approval decisions core deferred tools with inline HandleDeferredToolCalls or stored DeferredToolRequests/DeferredToolResults, Harness step persistence, or a durable integration according to crash/replay requirements

Pydantic AI's conversation_id groups runs and traces; it is not itself a message store. Message history preserves conversation context, not arbitrary workflow/checkpoint state.

For human approval:

  1. Use deferred tools or raise ApprovalRequired based on the call and trusted dependencies.
  2. Choose the flow per pending call: resolve with HandleDeferredToolCalls when the decision is available during the same call; otherwise include DeferredToolRequests in output_type, store the paused messages and complete request—or an equivalent pending-action record with category, validated arguments, and metadata—at an authenticated server-side boundary, and resume in a later run with DeferredToolResults, a new run ID, and the same conversation ID. A handler may resolve some calls and let the rest bubble up.
  3. Re-check authorization and idempotency inside the tool before the side effect.
  4. Test approve, deny, foreign/unknown ID, stale schema, and duplicate decisions. For the later-run flow, also test duplicate resume and process restart to the extent the source promised them.

Use a Pydantic AI durable integration when the source path promises replay or crash recovery across model/tool steps. Use Harness StepPersistence when its snapshot, event-log, continuation/fork, and effect-ledger contract fits. Neither follows merely from the word "session."

Streaming and observability

OpenAI run_streamed().stream_events() can expose raw Responses events, run-item events, and agent lifecycle events. Pydantic AI exposes model deltas, tool/lifecycle events, and final results through several APIs; raw event types and completion timing differ.

Choose the smallest Pydantic AI streaming surface that includes the required lifecycle, then adapt it to the existing public schema. run_stream() commits the first matching output and may skip tool calls emitted alongside or after it; use a loop-completing event or graph surface unless that terminal behavior is part of the source contract. Test incremental delivery, order, IDs, tool and final events, approval interruption, cancellation, early consumer exit, and terminal errors with the real client boundary.

OpenAI tracing is enabled by default and has OpenAI-specific span/export behavior. Pydantic AI uses OpenTelemetry and integrates directly with Logfire. Retaining an existing exporter, dual-running temporarily, and switching to Logfire have different dashboard, alert, privacy, retention, and cost consequences. Trace similarity can corroborate a test, but cannot prove state, authorization, exactly-once side effects, or public streaming delivery.

Primary references: OpenAI Agents SDK, agents, running agents, orchestration, sessions, guardrails, human-in-the-loop, streaming, and Pydantic AI comparisons.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No third-party reports yet.

Signed by skilld at b2d64a3. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 months ago

README badge

README badge for pydantic/pydantic-ai/migrating-openai-agents-sdk-to-pydantic-ai