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

/migrating-claude-agent-sdk-to-pydantic-ai

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

Migrate Python applications from the Claude Agent SDK to Pydantic AI and, only when needed, Pydantic AI Harness. Use when source code imports `claude_agent_sdk` or relies on Claude Code's agent loop, sessions, built-in tools, hooks, permissions, skills, or subagents. Do not use for the Anthropic Messages SDK or Claude Managed Agents.

  • 4 files
  • 18.6 KB
  • Updated 2 months ago
  • GitHub
Use this Skill: https://skilld.dev/gh/pydantic/pydantic-ai/migrating-claude-agent-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.

referencesRESEARCH-AND-MAPPING.md

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

Research and concept mapping

Use this reference conditionally after tracing the source path. It is a decision guide, not a requirement to reproduce every Claude Code feature.

Primary documentation

Inspect the installed versions before migrating because the Claude Agent SDK, Pydantic AI, and Harness continue to evolve.

The source SDK launches a bundled Claude Code process, passes configuration through CLI flags and a control protocol, and parses stream-JSON frames into Python message classes. That subprocess architecture is not a caller contract by itself. Preserve configured behavior, ordered outputs/events, errors, state, and external effects.

Ownership map

Observed Claude Agent SDK behavior Target owner and likely seam Focused proof
query() model/tool loop and ResultMessage.result Core: Agent.run() / run_sync(), AgentRunResult.output Assert caller output, errors, required usage data, and side effects without preserving the subprocess envelope.
ClaudeAgentOptions.system_prompt, model, thinking, limits Core: instructions, model/provider settings, UsageLimits(request_limit=..., cost_limit=...); Harness: SpendLimits only for observed cross-run spend policy Assert that limit exhaustion raises UsageLimitExceeded and translate it if callers expect a Claude result subtype. Core cost limits are best-effort, depend on available pricing, and may be checked after a billed response; retain provider/application spend controls when the source promises a hard cap.
Custom @tool and in-process SDK MCP server Core: @agent.tool, @agent.tool_plain, Tool, toolsets; MCP only for protocol interoperability Assert schema validation, retry/error behavior, concurrency, output content, and side effects.
Built-in Read/Write/Edit/Glob/Grep/Bash Harness: FileSystem, Shell, RepoContext, or Coder; Application/infrastructure: ModalSandbox or existing isolation Assert file/process outcomes, path escape resistance, command containment, and output limits.
Built-in web tools Core: WebSearch and WebFetch capabilities, backed by WebSearchTool and WebFetchTool where the provider supports them; otherwise retain the application integration Assert result shape, citations/events consumed by callers, credentials, and egress policy.
External MCP servers Core: MCPToolset, load_mcp_toolsets() Assert discovery, collisions/prefixes, transport, credentials, errors, lifecycle, and any required live control.
allowed_tools, disallowed_tools, permission modes, can_use_tool Core: tool preparation; requires_approval or ApprovalRequiredToolset to gate the tool; resolve inline with HandleDeferredToolCalls, or return DeferredToolRequests and resume a later run with DeferredToolResults; optional Harness policy; Application: authorization/UI/audit Assert availability and each pre-effect allow, deny, or ask outcome independently, including source callback precedence.
Structured output_format and structured_output Core: typed output_type, Pydantic models, output validators and modes Assert validated values and invalid-output retry exhaustion; do not silently parse fallback text.
Completed assistant/tool/result messages Core: normalized messages and agent stream events; Application: retained event adapter Compare a stable-field golden trace and include trailing source events.
Raw partial StreamEvents Core: run_stream(), run_stream_events(), event_stream_handler, or agent.iter() according to consumer intent Assert reconstruction, order, terminal detection, no duplicate final text, and cancellation.
Live multi-turn client Core: repeated Agent.run(..., message_history=...); Application: connection/UI loop Assert next-turn context plus observed mid-run input or interrupt behavior.
Disk resume, SessionStore, transcript list/read/rename/tag Core: serialized normalized messages; Application: storage, indexing, tenancy, metadata Round-trip through the real store and continue in a fresh process.
Session fork/truncating resume Application + Core: copy validated history and start a correlated conversation; optional Harness: StepPersistence for settled snapshots Assert branch point, source immutability, new lineage, tool-call pairing, and side-effect safety.
File checkpoint rewind Application/infrastructure: VCS, overlay, snapshot, or workspace owner Assert filesystem state independently of message history; otherwise record a tested gap.
Hooks and matchers Core: Hooks or a custom capability; Application: audit/integration effects Golden-test firing, stable inputs, decisions, mutation, errors, ordering, retry, and streaming behavior.
Model-directed AgentDefinition subagents Harness: SubAgents; Core: agent-as-tool for a fixed handoff Assert task-only input, isolated history, dependencies, budgets, handback, events, and recursion policy.
Agent Skills Harness: Skills Assert SKILL.md discovery/loading and test any resources, scripts, or setting-source behavior separately.
Local plugins Decompose used skills, agents, hooks, commands, and MCP servers across Core, Harness, and Application Assert each used feature; record packaging or namespace parity as a gap only when caller-visible.
Planning/task tracking Harness: Planning only for an observed model-owned plan Assert persistence and tenant/session keys only when required.
Cross-run model memory Harness: Memory for its notebook semantics; otherwise retain application storage/retrieval Assert restart, namespace isolation, concurrency, and bounded injection.
Compaction/context management Core: history processors/provider compaction; optional Harness: compaction, output limits, conversation search Assert retained facts, tool pairing, thresholds, cache behavior, and retrieval of omitted history.
Interrupts and cancellation Core: cancellation token/task cancellation; Application: transport semantics Assert stopped work, terminal shape, cleanup, and next-turn continuation.
Durable restart/replay Core: durable runtime integration; optional Harness durability capabilities Kill and restart at each promised boundary; assert external effects are idempotent.
Cost, usage, rate-limit and telemetry events Core: run usage and OTel; optional Harness: spend policy; Application: billing and retained adapters Assert required metrics, event/trace mapping, and privacy settings; do not treat estimated cost as billing.
HTTP, WebSocket, queues, deployment and auth Application/infrastructure Exercise the retained production boundary, including tenancy, scheduling, secrets, scaling, and isolation.

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-claude-agent-sdk-to-pydantic-ai