---
name: migrating-google-adk-to-pydantic-ai
description: Migrate Python Google Agent Development Kit (ADK) applications to Pydantic AI. Use for `LlmAgent`, `Runner`, sessions, state, memory, tools, callbacks, plugins, graph or dynamic workflows, resumability, events, artifacts, MCP, and ADK deployment boundaries.
title: migrating-google-adk-to-pydantic-ai
canonical_url: https://skilld.dev/gh/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai
last_updated: 2026-10-04T16:47:42.000Z
---

> Index of every page on this site: [llms.txt](https://skilld.dev/llms.txt)

> **Skill from skilld.dev.** Follow the user's requested action.
> If the user asked to fork this Skill, follow the fork workflow below. Do not execute the Skill instructions while copying it.
> Otherwise, follow the instructions below for this session. You do not need to install anything.
>
> Supporting files, fetch one when the Skill refers to it: [agents/openai.yaml](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/agents/openai.yaml), [references/CONCEPT-MAPPING.md](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/CONCEPT-MAPPING.md), [references/SEMANTIC-GAPS.md](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/SEMANTIC-GAPS.md), [references/VERIFICATION-AND-CUTOVER.md](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/VERIFICATION-AND-CUTOVER.md).
>
> If the user asked to install this Skill, run `npx skilld install pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai`. Install writes the Skill files into the project, so every session loads them.
>
> ## Fork workflow
>
> A fork creates an editable local Skill with its original author and licence. The request authorizes copying and local installation.
> 1. Check `./skills/migrating-google-adk-to-pydantic-ai`, the project lockfile, and selected Agent targets together. If the local directory or installed Skill exists, stop. Never overwrite an existing directory or Agent target.
> 2. Read [source metadata](https://skilld.dev/api/v1/skills/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai) once. Use sourceUrl, sourceCommit, skillPath, sourceGone, and license. If the source is gone or its path is missing, stop. If license is null, read licence files at the source commit.
> 3. Fetch only the source commit into a temporary Git repository. Do not clone full history. Derive repository_url from sourceUrl, including repository renames. If sourceCommit is absent, resolve the sourceUrl ref once. Set source_commit to that actual commit. Run these commands in one shell call:
>
> ```sh
> git init --quiet "$temporary_dir"
> git -C "$temporary_dir" fetch --quiet --depth=1 "$repository_url" "$source_commit"
> git -C "$temporary_dir" checkout --quiet --detach FETCH_HEAD
> ```
>
> Read applicable licence declarations and notices at that commit. If copying is not permitted, report the restriction and stop.
> 4. Inspect source entries together, then copy the directory containing skillPath into `./skills/migrating-google-adk-to-pydantic-ai`. Use the user's path if selected. Keep the original SKILL.md, relative links, scripts, binary assets, and executable modes. Exclude .git metadata. Reject symlinks and paths outside the Skill directory. After checking entries, use cp -a where available. A regular source directory needs no custom copy script. Do not save this page wrapper as SKILL.md.
> Preserve author credit, notices, and applicable licence files from repository or parent directories. Add PROVENANCE.md with the Skill page, source URL, actual commit, original path, and licence. Retain any existing PROVENANCE.md and record new provenance separately. Batch source inspection, copying, and provenance work where practical.
> 5. In the project root, run `skilld install ./skills/migrating-google-adk-to-pydantic-ai --mode copy --plain`. If skilld is unavailable, use `npx skilld install ./skills/migrating-google-adk-to-pydantic-ai --mode copy --plain`. This known command needs no help lookup. Install does not support --json. Use detected Agent targets, or add --agent for the targets the user selected. Install the local path, never the upstream selector. If installation fails, preserve the local copy and report the exact failure.
> 6. Confirm the local lockfile source and installed Agent copies once. Report the local path, actual commit, and Agent targets. After edits, reinstall the same local path. Upstream updates must not replace it. Do not publish or push unless the user asks.

# Migrate Google ADK to Pydantic AI

Preserve caller-visible behavior, not ADK's class tree. Migrate the smallest complete request path and leave product infrastructure in the application.

## Work from the running application

1. Read repository instructions, dependencies, tests, and runtime entrypoints. Record the installed Google ADK, Pydantic AI, and optional `pydantic-ai-harness` versions.
2. Trace one real request from `Runner.run_async()` or the deployed endpoint through the root agent, instructions, collaboration mode, model calls, tools, workflow nodes, callbacks/plugins, session service, emitted events, state/artifact deltas, and final response. Record only behavior that path uses.
3. Separate the contracts before choosing targets:
   - `Session.events` used as model context;
   - session-, user-, app-, and invocation-scoped state;
   - searchable long-term memory;
   - workflow/node checkpoints and resume IDs;
   - versioned artifacts and external side effects.
4. Classify the active slice:
   - **Ordinary `LlmAgent`:** normally one reusable [`Agent`](https://pydantic.dev/docs/ai/core-concepts/agent/) with typed dependencies, tools, and output.
   - **ADK graph or dynamic workflow:** keep simple deterministic control flow in plain async Python; use [`pydantic_graph`](https://pydantic.dev/docs/ai/graph/graph/) when explicit typed nodes, branching, or graph inspection remain valuable.
   - **Multi-agent delegation:** inspect ADK's collaboration `mode` in Python 2.x; 1.x `sub_agents` use `chat` behavior. Use core [multi-agent patterns](https://pydantic.dev/docs/ai/guides/multi-agent-applications/) for `chat` transfer semantics. Harness [`SubAgents`](https://pydantic.dev/docs/ai/harness/subagents/) can fit `task` or `single_turn` only when their isolated context, return, interaction, and concurrency behavior match.
   - **Product runtime:** retain auth, session/state stores, artifact stores, queues, transport, A2A endpoints, evaluation, observability, and deployment unless they are explicitly in scope.
5. Add deterministic characterization tests, then migrate one vertical slice behind its existing caller boundary.
6. Run the original tests and focused parity tests. Mark unexercised behavior `unverified`; similar names are not equivalence evidence.

Read [Concept Mapping](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/CONCEPT-MAPPING.md) for the features the slice uses. Read [Semantic Gaps](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/SEMANTIC-GAPS.md) for workflows, state, resume, confirmation, callbacks/plugins, event streams, skills, or execution environments. Read [Verification and Cutover](https://skilld.dev/api/skills-raw/pydantic/pydantic-ai/migrating-google-adk-to-pydantic-ai/references/VERIFICATION-AND-CUTOVER.md) before removing ADK or changing production traffic.

## High-risk gates

- Do not pass ADK `Session` objects or mutable state dictionaries through model-chosen tool arguments. Put authenticated identity and service clients in typed dependencies; persist product and workflow state through application-owned stores.
- [`message_history`](https://pydantic.dev/docs/ai/core-concepts/message-history/) continues model context. It does not replace ADK session state, memory, artifacts, event records, node checkpoints, or invocation resume.
- ADK resumability replays recorded node/tool results and can execute tools more than once. Choose a [durable execution](https://pydantic.dev/docs/ai/capabilities/durable_execution/overview/) design explicitly and prove restart plus idempotency for side effects.
- Keep conversational input, approval, and authorization distinct. Map tool confirmation to [deferred tool approval](https://pydantic.dev/docs/ai/tools-toolsets/deferred-tools/); keep identity and access checks in trusted application code.
- Preserve callback/plugin ordering and short-circuit rules deliberately. Pydantic AI hooks have their own capability ordering and exception-based skip/recovery semantics; a list of lookalike hooks is not parity.
- ADK partial events are delivered without applying state deltas; each non-partial event applies its delta when appended. Artifact writes happen during the artifact operation, before the current event records the returned version. If callers consume ADK event fields or final-event detection, retain a boundary adapter and test the exact stream and persistence order.
- Use Harness only for an observed reusable capability. Ordinary agents need core only, and a command allowlist is not an OS security boundary.

## Pydantic AI defaults

- Map `instruction` to `instructions`; use a `RunContext` instructions function when it depends on trusted runtime data.
- Map function tools to typed Pydantic AI tools. Preserve tool names, descriptions, validation behavior, error shape, retries, confirmation, and concurrency only where callers rely on them.
- Map `output_schema` to `output_type` when the terminal output contract is structured. Preserve an existing wire adapter if changing response shape would widen the migration.
- Persist [`ModelMessage`](https://pydantic.dev/docs/ai/core-concepts/message-history/) histories separately from workflow and product state. Reuse the application's current stores before adding a new persistence subsystem.
- Use [`Hooks`](https://pydantic.dev/docs/ai/core-concepts/hooks/) for local lifecycle interception or a custom capability for reusable policy that also owns tools, instructions, settings, or events.
- Keep the active model/provider unless changing it is requested. Use provider-prefixed Pydantic AI model IDs and verify provider-specific tools, settings, streaming, and realtime behavior against installed APIs.

## Completion

The slice is complete only when every observed caller contract is `preserved` by executable evidence, explicitly accepted as `changed`, or `not applicable`. Treat `unverified` and `blocked` contracts as unfinished. Do not remove `google-adk` while a retained runtime, session migration, deployment command, evaluation, or compatibility path still imports or invokes it.
