Terminal
Terminal/Skill
Moves TypeScript Pi coding-agent apps, extensions, and packages to Python with Pydantic AI and Pydantic AI Harness.
By Pydantic
Works with
npx skills add pydantic/skills --skill migrating-pi-to-pydantic-aiPreserve observable behavior, not Pi's TypeScript API. Migrate the smallest complete caller path and keep product/host infrastructure in the application.
package.json, Pi settings, tests, extension/package manifests, and runtime entrypoints. Record the installed Pi, Pydantic AI, and Harness versions.createAgentSession().prompt() through resource discovery, system instructions, tools, extensions, model requests, messages, compaction/retry, events, session entries, UI/RPC output, and side effects. Establish a focused baseline or characterization test.pi.on(...), registerTool, registerCommand, provider registration, renderer/UI contribution, skill, prompt, and persisted entry, record its firing point, trusted inputs, mutations, output, state owner, and caller-visible effect.Read Research and concept mapping for the detected features. Read Verification and cutover before implementation.
A Pi extension is the closest source concept to a Pydantic AI capability, but it is broader. An extension can combine agent behavior with terminal UI, commands, provider registration, resource discovery, and host lifecycle. Port responsibilities, not the extension file:
Capability; subclass AbstractCapability only for reusable behavior that needs lifecycle hooks, adaptive models/settings, native tools, or typed capability events.ToolGuardrail or approval capability plus an application-owned approver UI; a coding package may become Coder plus host configuration; a provider extension remains a model/provider integration.pydantic_ai.Agent for the agent loop, typed dependencies, tools/toolsets, outputs, normalized messages, capabilities/hooks, streaming, approvals, usage limits, instrumentation, MCP, and provider/model integration.Coder for Pi's ordinary coding tools only when its exact composition fits. Add focused capabilities such as FileSystem, Shell, Skills, Planning, SubAgents, guardrails, compaction, tool-output limits, or step persistence only for observed behavior.pydantic_graph for deterministic workflows; do not encode them in prompts or subagents.The normal embedded migration is one reusable Agent, Coder or a smaller capability composition, application services in typed dependencies, an application-owned message/session store, and a thin adapter at the existing RPC or UI boundary.
ctx, project trust, credentials, session managers, and service handles are trusted host context. Put equivalents in typed dependencies or application services, never model-chosen tool arguments.result.all_messages() preserves model history, not tree navigation, labels, extension entries, compaction records, model changes, queues, or abandoned branches. Choose and test conversion, a compatibility store, or an accepted fresh start.tool_call permission gates by effect. Use guardrails for validation/block/redaction and deferred tools for an action that must await approval. Keep identity, authorization, UI, audit, persistence, and idempotency in the application.Skills loads configured SKILL.md instructions on demand but does not reproduce Pi's discovery roots, resource files, scripts, reload, package installation, or behavioral frontmatter. Preserve those separately when observed.SubAgents only for model-directed isolated tasks. Keep deterministic orchestration and Pi subprocess/tmux/package-specific semantics in application code.ToolSearch or on-demand capabilities only after testing load timing, schemas, prompt/cache changes, and provider fallback behavior.Explain consequential semantic changes before implementing them: state the Pi behavior, target behavior, caller impact, recommended choice, and remaining risk.
Apply the completion criterion in Verification and cutover. Label fake, recording, live-provider, terminal, restart, and sandbox evidence accurately.