Production Agent Runtimes, Fast Instantiation and Typed Workflows
A production agent runtime optimizes what prototyping frameworks ignore: instantiation cost, typed workflow surfaces, and a serving-ready backend. The 2026 pairing: Agno (Python) aims at microsecond agent instantiation and stateless FastAPI backends. Mastra ships agents, tools, workflows, unified model routing, and composite storage on the Vercel AI SDK substrate.
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
LangGraph, AutoGen, CrewAI are framework-heavy. Teams that want "just the agent loop, fast, in my runtime" reach for Agno (Python) or Mastra (TypeScript). Both trade some of the framework-owned primitives for raw speed and a tighter fit to the surrounding stack.
The Concept
Agno
- Python runtime, formerly Phi-data.
- "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: stateless session-scoped FastAPI backend. Each request starts a fresh agent; session state lives in a DB.
- Native multimodal (text, image, audio, video, file) and agentic RAG.
The speed targets matter when you have thousands of short-lived agents per second (chat fan-in, evaluation pipelines). They matter less when one agent runs for 10 minutes.
Mastra
- TypeScript, built on Vercel AI SDK.
- Three primitives: AgentsTools (Zod-typed), Workflows.
- Unified Model Router, 3,300+ models across 94 providers (March 2026).
- Composite storage: memory, workflows, observability to different backends; ClickHouse recommended for observability at scale.
- Apache 2.0 with
ee/directories under source-available enterprise license. - Server adapters for Express, Hono, Fastify, Koa; first-class Next.js and Astro integration.
- Ships Mastra Studio (localhost:4111) for debugging.
- 22k+ GitHub stars, 300k+ weekly npm downloads at 1.0 (Jan 2026).
Positioning
Neither is trying to be LangGraph. They compete on:
- Language fit. Agno for Python-first teams; Mastra for TypeScript-first.
- Runtime ergonomics. Agno = near-zero overhead; Mastra = integrated with the Vercel ecosystem.
- Observability. Both integrate with Langfuse/Phoenix/Opik (Lesson 24) but Mastra Studio is first-party.
When to pick each
- AgnoPython backend, many short-lived agents, strong perf requirements, FastAPI shop.
- MastraTypeScript backend, Next.js / Vercel deploy, unified multi-provider model routing, Zod-typed tools.
- LangGraph (Lesson 13), when durable state and explicit graph reasoning matter more than raw speed.
- OpenAI / Claude Agent SDKwhen you want the provider's productized shape (Lessons 16 to 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 is not the bottleneck.
- Ecosystem lock-in. Mastra's Vercel-flavored integration is a plus on Vercel, a minus elsewhere.
- Enterprise license confusion. Mastra's
ee/directories are source-available, not Apache 2.0. Read the licenses if you're planning to fork.
Build It
This lesson is primarily comparative, no single code artifact would do both frameworks justice. See code/main.py for a side-by-side toy: a minimal "run an agent, stream the output, persist session" flow implemented twice (once Agno-shaped, once Mastra-shaped).
Run it:
python3 code/main.pyTwo structurally different but functionally equivalent traces.
Use It
- AgnoPython backend that needs speed and FastAPI shape.
- MastraTypeScript backend with many providers and workflow primitives.
- Both ship first-party observability hooks. Both integrate with Langfuse.
Ship It
outputs/skill-runtime-picker.md picks Agno, Mastra, LangGraph, or a provider SDK based on stack, latency budget, and operational shape.
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 permits source reading but restricts commercial use |
Further Reading
- Agno Agent Framework docsperformance targets, FastAPI integration
- Mastra docsprimitives, server adapters, Model Router
- LangGraph overviewthe stateful-graph alternative
- Comet Opikobservability comparisons cited by Mastra integrations
Check what you learned
7 questions. Answer each one to see why.
Which language pairing does the lesson recommend for each runtime?
The full code
Every file for this lesson. Copy it, run it, then change it.
"""Side-by-side toys: Agno-shaped (stateless FastAPI) vs Mastra-shaped
(primitive-rich). Stdlib only; meant to show the structural difference.
"""
from __future__ import annotations
import time
from dataclasses import dataclass, field
from typing import Any, Callable
@dataclass
class AgnoAgent:
name: str
fn: Callable[[str], str]
def run(self, prompt: str) -> str:
return self.fn(prompt)
class AgnoSession:
def __init__(self) -> None:
self._turns: dict[str, list[str]] = {}
def append(self, session_id: str, turn: str) -> None:
self._turns.setdefault(session_id, []).append(turn)
def history(self, session_id: str) -> list[str]:
return list(self._turns.get(session_id, []))
def agno_request_handler(session: AgnoSession,
agent: AgnoAgent,
session_id: str,
prompt: str) -> str:
start = time.perf_counter_ns()
session.append(session_id, f"user: {prompt}")
output = agent.run(prompt)
session.append(session_id, f"assistant: {output}")
elapsed_us = (time.perf_counter_ns() - start) / 1000
return f"{output} (handler {elapsed_us:.1f} us)"
@dataclass
class MastraTool:
name: str
input_schema: dict[str, Any]
fn: Callable[..., str]
@dataclass
class MastraAgent:
name: str
instructions: str
tools: list[MastraTool] = field(default_factory=list)
def run(self, prompt: str, tool_calls: list[tuple[str, dict[str, Any]]]
) -> tuple[str, list[tuple[str, str]]]:
trace: list[tuple[str, str]] = []
for tool_name, args in tool_calls:
tool = next((t for t in self.tools if t.name == tool_name), None)
if tool is None:
trace.append((tool_name, "error: unknown"))
continue
result = tool.fn(**args)
trace.append((tool_name, result))
output = f"{self.name} processed {len(tool_calls)} tools"
return output, trace
@dataclass
class MastraWorkflow:
steps: list[tuple[str, Callable[[Any], Any]]]
def run(self, payload: Any) -> list[tuple[str, Any]]:
trace: list[tuple[str, Any]] = []
current = payload
for name, fn in self.steps:
current = fn(current)
trace.append((name, current))
return trace
def _agno_agent_fn(prompt: str) -> str:
return f"[agno reply] {prompt[:40]}"
def _mastra_tool_fn(query: str) -> str:
return f"[mastra search result for {query!r}]"
def main() -> None:
print("=" * 70)
print("AGNO vs MASTRA — Phase 14, Lesson 18")
print("=" * 70)
print("\n1. AGNO-shaped (stateless session-scoped FastAPI handler)")
session = AgnoSession()
agent = AgnoAgent(name="agno_a", fn=_agno_agent_fn)
for i in range(3):
out = agno_request_handler(session, agent, "s001",
f"query {i}: how do I ship an agent")
print(f" turn {i}: {out}")
print(f" session history length: {len(session.history('s001'))}")
print(" pattern: a fresh agent per request; session holds state; "
"FastAPI is stateless.")
print("\n2. MASTRA-shaped (Agents + Tools + Workflows)")
search_tool = MastraTool(
name="search",
input_schema={"type": "object",
"properties": {"query": {"type": "string"}}},
fn=_mastra_tool_fn,
)
mastra_agent = MastraAgent(
name="mastra_a",
instructions="search, summarize, cite",
tools=[search_tool],
)
output, trace = mastra_agent.run(
"research agent engineering",
[("search", {"query": "agent engineering 2026"}),
("search", {"query": "BFCL V4 benchmarks"})],
)
print(f" agent output: {output}")
for tool, result in trace:
print(f" tool {tool}: {result}")
workflow = MastraWorkflow(steps=[
("normalize", lambda p: p.strip().lower()),
("search", lambda p: f"found 3 results for {p}"),
("summarize", lambda p: f"summary: {p}"),
])
print("\n workflow run")
for name, out in workflow.run(" Agent Engineering 2026 "):
print(f" {name}: {out}")
print("\npick by stack: python+fastapi Agno; typescript+next/vercel Mastra.")
if __name__ == "__main__":
main()