LearnPython

Agno and Mastra: Production Runtimes

Agno (Python) and Mastra (TypeScript) are the 2026 production-runtime pairing. Agno aims at microsecond agent instantiation and stateless FastAPI backends. Mastra ships agents, tools, workflows, unified model routing, and composite storage on top of the Vercel AI SDK.

TIME: ~45 minutesPREREQUISITES: Phase 14 · 01 (Agent Loop), Phase 14 · 13 (LangGraph)

Learning Objectives

Identify Agno's performance targets and when they matter.
Name Mastra's three primitives — Agents, Tools, Workflows — and the supported server adapters.
Explain why a stateless session-scoped FastAPI backend is the recommended Agno production path.
Pick Agno vs Mastra for a given stack (Python-first vs TypeScript-first).

The Problem

Agno and Mastra are agent runtimes that keep the loop and drop most of the framework around it. Agno is Python, Mastra is TypeScript.

LangGraph, AutoGen, and CrewAI are framework-heavy: they own state, graphs, roles, and message passing for you. Plenty of teams don't want that. They want the agent loop, fast, inside the runtime they already deploy. Both of these give up some framework-owned primitives in exchange for speed and a tighter fit with the surrounding stack.

Warm-up0/3

1. In a basic agent loop, what happens after the model requests a tool call?Warm-up

2. A web backend serves many users across several server instances. Where should per-conversation state live so any instance can handle the next request?Warm-up

3. A function receives its arguments from an LLM as JSON. Why declare the expected argument types and check them before running the function?Warm-up

Check: The Problem0/1

1. LangGraph, AutoGen, and CrewAI are framework-heavy. What do they own that Agno and Mastra largely drop?Explain

The Concept

Agno

Agno is a Python agent runtime, formerly Phi-data. Its pitch is "No graphs, chains, or convoluted patterns — just pure python."

Performance targets from their docs: ~2μs agent instantiation, ~3.75 KiB memory per agent, ~23 model providers.
Production path: a stateless, session-scoped FastAPI backend. Each request starts a fresh agent, and session state lives in a database.
Native multimodal (text, image, audio, video, file) and agentic RAG.

The speed targets pay off when you run thousands of short-lived agents per second, as in chat fan-in or evaluation pipelines. They barely register when one agent runs for 10 minutes.

Mastra

Mastra is a TypeScript agent runtime built on the Vercel AI SDK. It has three primitives: Agents, Tools (Zod-typed), and Workflows.

Unified Model Router: 3,300+ models across 94 providers (March 2026).
Composite storage sends memory, workflows, and observability to different backends. ClickHouse is the recommended choice for observability at scale.
Licensing is Apache 2.0, except the ee/ directories, which fall under a source-available enterprise license.
Server adapters for Express, Hono, Fastify, and Koa, plus first-class Next.js and Astro integration.
Mastra Studio (localhost:4111) ships for debugging.
22k+ GitHub stars and 300k+ weekly npm downloads at 1.0 (Jan 2026).

Positioning

Neither one is trying to be LangGraph. They compete on three things:

Language fit. Agno suits Python-first teams, Mastra suits TypeScript-first teams.
Runtime ergonomics. Agno is near-zero overhead. Mastra is integrated with the Vercel ecosystem.
Observability. Both integrate with Langfuse, Phoenix, and Opik (Lesson 24), but Mastra Studio is first-party.

When to pick each

Agno: Python backend, many short-lived agents, strong performance requirements, a FastAPI shop.
Mastra: TypeScript backend, Next.js or Vercel deploy, unified multi-provider model routing, Zod-typed tools.
LangGraph (Lesson 13): durable state and explicit graph reasoning matter more than raw speed.
OpenAI or Claude Agent SDK: you want the provider's productized shape (Lessons 16–17).

Where this pattern goes wrong

Perf for perf's sake. Picking Agno because "2μs" sounds good, when the workload is one slow agent call per request. Overhead isn't your bottleneck there.
Ecosystem lock-in. Mastra's Vercel-flavored integration is a plus on Vercel and a minus anywhere else.
Enterprise license confusion. Mastra's ee/ directories are source-available, not Apache 2.0. Read the licenses before you plan a fork.

Check: The Concept0/21

1. What is Agno?Define

2. What are Mastra's three primitives?Define

3. What does Mastra's Unified Model Router give?Define

4. What is Mastra's composite storage?Define

5. What is Mastra Studio?Define

6. What does it mean for code to be source-available?Define

7. Which language pairing does the lesson recommend for each runtime?Define

8. Roughly what agent-instantiation cost does Agno target per its docs?Define

9. Which comparison of model-provider coverage matches the figures the lesson cites?Define

10. Beyond raw performance, what does the lesson say Agno supports natively?Define

11. What adoption numbers does the lesson cite for Mastra at its 1.0 release (January 2026)?Define

12. Which server adapters does the lesson say Mastra supports?Define

13. Why does an Agno request handler start a fresh agent per request and keep session state in a database?Explain

14. Why do Agno's microsecond targets pay off for chat fan-in or evaluation pipelines but barely register for one 10-minute agent?Explain

15. Both runtimes integrate with Langfuse, Phoenix, and Opik. What does Mastra add on the observability side?Explain

16. When is perf-for-perf's-sake the wrong reason to pick Agno?Analyze

17. A Python-first FastAPI team adopts Mastra for its 94-provider router and then struggles to fit it into their stack. Which assumption was wrong?Analyze

18. A team forks Mastra for an open-source project and copies code from an `ee/` directory, assuming it is Apache 2.0. What did they miss?Analyze

19. Your team runs a Python FastAPI service that starts thousands of short-lived agents per second for an evaluation pipeline. Which runtime fits best?Design

20. Your team is TypeScript-first, deploys a Next.js app on Vercel, and wants Zod-typed tools. Which runtime fits best?Design

21. A Python team runs one long research agent per request and needs durable state and explicit graph reasoning across steps. Which pick fits?Design

Build It

This lesson is comparative, so no single code artifact would do both frameworks justice. code/main.py is a side-by-side toy: one minimal flow (run an agent, stream the output, persist the session) implemented twice, once Agno-shaped and once Mastra-shaped.

Run it:

python3 code/main.py

You get two traces that are structurally different and functionally equivalent.

code/main.ts is the same comparison as a TypeScript port: a Mastra-shaped agent, tool registry, and workflow with a mocked LLM step, plus an Agno-shaped sketch for contrast.

Check: Build It0/9

1. In the Python demo, `agno_request_handler` runs three times with session id "s001". What does `len(session.history("s001"))` print?Apply

2. In `main.py`, what does `_agno_agent_fn("query 0: how do I ship an agent")` return?Apply

3. In `main.py`, `mastra_agent.run` is given two `search` tool calls. What is the returned `output` string?Apply

4. In `main.py`, the workflow runs on the input `" Agent Engineering 2026 "`. What does the final `summarize` step return?Apply

5. In `main.ts`, the Mastra-shaped agent is given a call to `unknown_tool`. What happens?Apply

6. In `main.ts`, `checkSchema({ query: "string" }, { query: 42 })` is called. What does it return?Apply

7. In `main.ts`, the workflow runs on `" Agent Engineering 2026 "`. What does the `search` step output?Apply

8. An Agno-shaped service keeps each user's history in a dict inside the process, like `AgnoSession`. After a second instance is added, users randomly lose their history. What went wrong?Analyze

9. A Mastra-shaped agent trace shows `error: missing field query` for a `search` call. Which part of the design produced it?Analyze

Use It

Agno: a Python backend that needs speed and a FastAPI shape.
Mastra: a TypeScript backend with many providers and workflow primitives.

Both integrate with Langfuse, Phoenix, and Opik for observability, and Mastra also ships its own debugger, Mastra Studio.

Ship It

outputs/skill-runtime-picker.md picks Agno, Mastra, LangGraph, or a provider SDK based on your stack, latency budget, and operational shape.

Author's Note

Choose by language and deployment target first. If your backend is Python and already speaks FastAPI, Agno fits. If it's TypeScript on Next.js or Vercel, Mastra fits. That decision settles most of the question before any benchmark does.

Be skeptical of leading with the microsecond numbers. They matter at chat fan-in scale and almost not at all when each request makes one slow agent call. Run exercise 3 on your own stack and let the measurement decide whether instantiation cost is even a factor for you. And if you're considering a Mastra fork, read the ee/ license terms before you write any code.

Exercises

Read Agno's docs. Port the stdlib ReAct loop (Lesson 01) to Agno. What disappeared? What stayed?
Read Mastra's docs. Port the same loop to Mastra. What changed in tool typing (Zod vs nothing)?
Benchmark: measure agent instantiation latency on your stack. Does Agno's 2μs matter to your workload?
Design a migration: if you've been running CrewAI in Python, what breaks if you move to Agno?
Read Mastra's ee/ license terms. What restrictions would affect an open-source fork?

Key Terms

Term	What people say	What it actually means
Agno	"Fast Python agents"	Stateless session-scoped agent runtime
Mastra	"TypeScript agents on Vercel AI SDK"	Agents + Tools + Workflows + Model Router
Unified Model Router	"Multi-provider access"	Single client for 3,300+ models across 94 providers
Composite storage	"Multiple backends"	Memory/workflows/observability each to a different store
Mastra Studio	"Local debugger"	localhost:4111 UI for introspecting agents
Source-available	"Not OSS"	License lets you read the source but is not an open-source license like Apache 2.0