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

/migrating-mastra-to-pydantic-ai

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

Migrate TypeScript Mastra applications to Python with Pydantic AI and, only when needed, Pydantic AI Harness. Use when source code imports `@mastra/*` or relies on Mastra agents, tools, workflows, memory, processors, streaming, approvals, skills, or subagents.

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

≈2.3k 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 the entire Mastra platform.

Primary documentation

Inspect installed versions before migrating because Mastra, Pydantic AI, and Harness continue to evolve.

Mastra is a TypeScript framework and Pydantic AI is Python. Capture each existing transport or storage boundary with language-neutral fixtures and keep its field names, using Pydantic aliases where needed.

Ownership map

Observed Mastra behavior Target owner and likely seam Focused proof
Agent.generate() and response text, toolCalls, toolResults, steps, or usage Core: Agent.run() / run_sync(), AgentRunResult; Application: response adapter Assert caller-visible output, required trajectory fields, usage, errors, and side effects.
Agent.stream(), textStream, object, and fullStream Core: run_stream(), run_stream_events(), event_stream_handler, or iter(); Application: event adapter Assert reconstruction, order, terminal detection, trailing events, cancellation, and no duplicate final output.
Agent instructions, model, maxSteps, and call options Core: instructions, model/provider settings, UsageLimits; Application: configuration mapping Construct every configured provider branch and assert step-limit behavior without assuming identical defaults.
RequestContext and dynamic configuration functions Core: typed deps_type, RunContext.deps, dynamic instructions/tool preparation; Application: authenticated context construction Inspect tool schemas and prove that tenant identity, credentials, and services cannot be model-selected.
createTool() with Zod/JSON schemas and execute() Core: typed functions, Tool, Tool.from_schema, function toolsets Assert schema, return shape, retry/error behavior, timeout, concurrency, approval, and effects.
structuredOutput.schema, response.object Core: Pydantic output type and explicit NativeOutput, ToolOutput, or PromptedOutput when transport matters Assert valid output and invalid-output behavior; preserve a second structuring-model pass explicitly if the source uses one.
Input/output processors and processor workflows Core: history processors, output validators, Hooks; Harness: InputGuardrail, OutputGuardrail, or ToolGuardrail for matching block/replace/retry policy; Application: public error/event adapter Golden-test firing point, mutation, order, tripwire/error shape, retries, persistence, and streaming.
Memory thread/resource message history Core: normalized messages; Application: existing store, ownership, indexing, retention, and record migration Assert the selected cutover strategy against real records, continue in a fresh process, and reject cross-tenant access.
Semantic recall across messages/threads Application: existing vector/retrieval service behind typed dependencies or a tool Assert scope, ranking/filtering, context placement, limits, and behavior when retrieval fails.
Working memory Harness: Memory only when a model-owned Markdown notebook fits; otherwise Application: retain structured profile storage Assert schema/format, update ownership, namespace isolation, bounded injection, restart, and concurrency.
Observational memory Application: retain observation/reflection service; optionally combine explicit retrieval with core history processing Assert when raw history is replaced, facts retained, background failure behavior, and fresh-process continuation. Do not label generic compaction equivalent.
createWorkflow().then() fixed steps Application: plain typed async functions; pydantic_graph when explicit graph inspection adds value Assert step inputs/outputs, order, error propagation, and public terminal status.
.branch(), .parallel(), .foreach(), loops, nested workflows Application: explicit Python control flow; Graph: pydantic_graph for typed branches/joins Assert chosen branch, join shape, source ordering, concurrency limit, cancellation, partial failure, and retry.
Workflow stateSchema, state, setState Application/Graph: separate typed workflow state from dependencies and messages Serialize and resume state independently; assert updates, versioning, and nested-flow propagation actually used. Graph state alone does not provide persisted snapshots.
Workflow suspend(), resume(), snapshots, time travel Application or underlying durable engine: workflow state, branch progress, snapshots, and resume correlation; Core durable integration: agent model, tool, and MCP operations inside that workflow only Kill and restart at each promised boundary; assert resume payload validation, step identity, lineage, branch progress, and exactly-once effects.
Durable or evented agents Harness: StepPersistence for continuable agent snapshots; Core: Temporal, DBOS, or Prefect integration for durable execution Kill and restart during model, tool, and external-effect boundaries; assert continuation, replay behavior, and idempotency.
Tool requireApproval, request-wide approval, tool suspension Core: requires_approval, ApprovalRequired, or ApprovalRequiredToolset to gate the tool; resolve inline with HandleDeferredToolCalls, or return DeferredToolRequests and resume a later run with DeferredToolResults; Application: auth, policy, UI, audit, persistence Exercise deny and approve; bind the decision to call ID and validated arguments; assert zero effects before resolution and after denial, and exactly one after approval.
Registered subagents / supervisor delegation Harness: SubAgents; Core: agent-as-tool or programmatic handoff when fixed Assert task-only input, isolated history, dependency and budget propagation, result handback, cancellation, errors, events, and recursion policy.
Agent Skills and workspace skills Harness: Skills for SKILL.md instructions; FileSystem or an Application tool for references/resources; Application: dynamic selection and scripts Assert configured-root discovery, loading, request-scoped selection, and every used reference, resource, or script separately. Harness does not automatically scan .agents or .claude.
MCP clients Core: MCPToolset Assert discovery, name collisions, transport, credentials, errors, lifecycle, and approvals.
MCP servers exposing tools or agents Application: MCP Python SDK around the migrated public boundary Assert advertised schemas, transport lifecycle, auth, errors, and client compatibility.
Scorers, datasets, and experiments Evals (pydantic_evals): cases, datasets, evaluators; Application: live sampling, scheduling, and score storage Add the separate pydantic-evals dependency, compare the same dataset and essential metrics, and separately prove sampling, trace correlation, and persistence when retained.
OpenTelemetry and Mastra observability Core: instrumentation/OpenTelemetry; optional Logfire; Application: existing backend and trace/event adapters Assert trace correlation, content/privacy policy, required spans, logs, feedback, retention, and dashboards before switching.
Mastra registry, server, client SDK, Studio, auth, storage adapters, queues, schedules, and deployment Application/infrastructure Exercise the retained public endpoint or job boundary, including auth, tenancy, configuration, secrets, scaling, and failure behavior.
Mastra Code, filesystem/shell/browser, and workspace sandboxes Harness: Coder, FileSystem, Shell, browser capabilities, or ModalSandbox; Application: existing isolation Assert tools and workspace effects. Treat command allowlists as policy, not isolation; test the real sandbox for untrusted execution.
Realtime voice Core: realtime agent/session APIs where the provider and media contract fit; otherwise retain the integration Test media formats, interruption, event ordering, tool calls, session lifetime, and transport errors.

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-mastra-to-pydantic-ai