Phase 14 - Lesson 18

Agno e Mastra: Runtimes de Produção

Agno (Python) e Mastra (TypeScript) são a dupla de runtimes de produção de 2026. O Agno foca na instanciação de agentes em microsegundos e em backends FastAPI stateless. O Mastra fornece agentes, ferramentas, fluxos de trabalho, roteamento unificado de modelos e armazenamento composto sobre o substrato do Vercel AI SDK.

Type: Learn Languages: Python, TypeScript Prerequisites: Phase 14 · 01 (Agent Loop), Phase 14 · 13 (LangGraph) Time: ~45 minutos

Learning Objectives

• Identificar as metas de desempenho do Agno e quando elas são importantes.
• Nomear as três primitivas do Mastra — Agents, Tools, Workflows — e os adaptadores de servidor suportados.
• Explicar por que um backend FastAPI stateless com escopo de sessão é o caminho de produção recomendado para o Agno.
• Escolher Agno vs Mastra para uma determinada stack (focada em Python vs focada em TypeScript).

The Problem

LangGraph, AutoGen e CrewAI são frameworks pesados. As equipes que desejam "apenas o loop do agente, rápido, no meu runtime" optam pelo Agno (Python) ou Mastra (TypeScript). Ambos trocam algumas das primitivas controladas pelo framework por velocidade bruta e um ajuste mais firme com a stack ao redor.

The Concept

Agno

• Runtime Python, anteriormente Phi-data.
• "Sem grafos, chains ou padrões complexos — apenas Python puro."
• Metas de desempenho de sua documentação: instanciação de agente em ~2μs, ~3,75 KiB de memória por agente, ~23 provedores de modelos.
• Caminho de produção: backend FastAPI stateless com escopo de sessão. Cada requisição inicia um agente do zero; o estado da sessão vive em um banco de dados.
• Multimodal nativo (texto, imagem, áudio, vídeo, arquivo) e RAG agente.

As metas de velocidade são importantes quando você tem milhares de agentes de curta duração por segundo (leitura paralela de chats, pipelines de avaliação). Elas importam menos quando um único agente é executado por 10 minutos.

Mastra

• TypeScript, construído sobre o Vercel AI SDK.
• Três primitivas: Agents, Tools (tipadas com Zod), Workflows.
• Unified Model Router — mais de 3.300 modelos em 94 provedores (março de 2026).
• Armazenamento composto: memória, fluxos de trabalho e observabilidade em diferentes backends; ClickHouse é o recomendado para observabilidade em escala.
• Apache 2.0 com diretórios ee/ sob uma licença empresarial de código disponível (source-available).
• Adaptadores de servidor para Express, Hono, Fastify, Koa; integração de primeira classe com Next.js e Astro.
• Acompanha o Mastra Studio (localhost:4111) para depuração.
• Mais de 22 mil estrelas no GitHub, mais de 300 mil downloads semanais no npm na versão 1.0 (janeiro de 2026).

Positioning

Nenhum dos dois tenta ser o LangGraph. Eles competem em:

• Compatibilidade de linguagem. Agno para equipes focadas em Python; Mastra para focadas em TypeScript.
• Ergonomia de runtime. Agno = overhead próximo de zero; Mastra = integrado com o ecossistema Vercel.
• Observabilidade. Ambos se integram com Langfuse/Phoenix/Opik (Lição 24), mas o Mastra Studio é nativo.

When to pick each

• Agno — backend Python, muitos agentes de curta duração, requisitos fortes de desempenho, infraestrutura baseada em FastAPI.
• Mastra — backend TypeScript, deploy no Next.js / Vercel, roteamento unificado de modelos multiprovedor, ferramentas tipadas com Zod.
• LangGraph (Lesson 13) — quando o estado durável e o raciocínio explícito em grafos importam mais do que a velocidade bruta.
• OpenAI / Claude Agent SDK — quando você deseja o formato empacotado do provedor (Lições 16–17).

Where this pattern goes wrong

• Desempenho pelo próprio desempenho. Escolher o Agno porque "2μs" parece bom quando a carga de trabalho é uma chamada lenta de agente por requisição. O overhead de inicialização não é o gargalo.
• Bloqueio de ecossistema (lock-in). A integração do Mastra com estilo Vercel é uma vantagem na Vercel, mas uma desvantagem em outros ambientes.
• Confusão com licenças empresariais. Os diretórios ee/ do Mastra são de código disponível (source-available), não Apache 2.0. Leia as licenças se planeja fazer um fork.

Build It

Esta lição é principalmente comparativa — nenhum artefato de código único faria justiça a ambos os frameworks. Veja code/main.py para um exemplo simples comparativo: um fluxo mínimo de "executar um agente, transmitir a saída, persistir a sessão" implementado duas vezes (uma no formato do Agno, outra no formato do Mastra).

Execute-o:

python3 code/main.py

Dois traces estruturalmente diferentes, mas funcionalmente equivalentes.

Use It

• Agno — backend Python que precisa de velocidade e do formato do FastAPI.
• Mastra — backend TypeScript com muitos provedores e primitivas de fluxo de trabalho.
• Ambos fornecem ganchos de observabilidade nativos. Ambos se integram com o Langfuse.

Ship It

O arquivo outputs/skill-runtime-picker.md seleciona Agno, Mastra, LangGraph ou o SDK de um provedor com base na stack, orçamento de latência e formato operacional.

Exercises

1. Leia a documentação do Agno. Faça a portabilidade do loop ReAct da stdlib (Lição 01) para o Agno. O que desapareceu? O que permaneceu?
2. Leia a documentação do Mastra. Faça a portabilidade do mesmo loop para o Mastra. O que mudou na tipagem de ferramentas (Zod vs nada)?
3. Benchmark: meça a latência de instanciação de agentes na sua stack. Os 2μs do Agno fazem diferença para a sua carga de trabalho?
4. Planeje uma migração: se você está executando o CrewAI em Python, o que quebra se você migrar para o Agno?
5. Leia os termos de licença do diretório ee/ do Mastra. Quais restrições afetariam um fork de código aberto?

Key Terms

Further Reading

• Agno Agent Framework docs — metas de desempenho, integração com FastAPI
• Mastra docs — primitivas, adaptadores de servidor, Model Router
• LangGraph overview — a alternativa de grafos com estado
• Comet Opik — comparações de observabilidade citadas pelas integrações do Mastra