# 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: [agents](https://mastra.ai/docs/agents/overview), [workflows](https://mastra.ai/docs/workflows/overview), [memory](https://mastra.ai/docs/memory/overview), [processors](https://mastra.ai/docs/agents/processors), and [streaming](https://mastra.ai/docs/guides/streaming).
- Pydantic AI: [agents](https://pydantic.dev/docs/ai/core-concepts/agent/), [message history](https://pydantic.dev/docs/ai/core-concepts/message-history/), [hooks](https://pydantic.dev/docs/ai/core-concepts/hooks/), [graphs](https://pydantic.dev/docs/ai/graph/graph/), and [deferred tools](https://pydantic.dev/docs/ai/tools-toolsets/deferred-tools/).
- Pydantic AI Harness: [overview](https://pydantic.dev/docs/ai/harness/), [memory](https://pydantic.dev/docs/ai/harness/memory/), [guardrails](https://pydantic.dev/docs/ai/harness/guardrails/), [skills](https://pydantic.dev/docs/ai/harness/skills/), [subagents](https://pydantic.dev/docs/ai/harness/subagents/), and [step persistence](https://pydantic.dev/docs/ai/harness/step-persistence/).

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. |