references/RESEARCH-AND-MAPPING.md
references/RESEARCH-AND-MAPPING.mdBrowse 4 files
1,981 tokens
9,338 bytes
Token encoding: o200k_base
Snapshot 9e9fdc4
← Back to SKILL.md
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, workflows, memory, processors, and streaming.
- Pydantic AI: agents, message history, hooks, graphs, and deferred tools.
- Pydantic AI Harness: overview, memory, guardrails, skills, subagents, and 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. |