Get Started

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.

45 minutesLearnPython, TypeScriptFree lesson

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:

Code
python3 code/main.py

Two 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

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

Key Terms

TermWhat people sayWhat 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

Check what you learned

7 questions. Answer each one to see why.

Question 1 of 70 correct

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.

main.py
"""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()