Agent runtimes: Agno & Mastra

It is 3 a.m. Your support agent has found the customer’s order, searched the refund policy, remembered the previous conversation, called the billing API, and then failed because the tracing package expects a different model-client object.

The model was not the difficult part.

The difficult part was the plumbing:

• six packages;
• four configuration formats;
• two incompatible representations of a message; and
• a deployment script nobody touched after the original author changed teams.

That is the problem agent runtimes try to solve. An agent runtime owns the path from incoming request to model call, tool execution, state, and operational output. It gives those pieces one language-native API and sensible defaults.

Two prominent examples are Agno for Python and Mastra for TypeScript. They do not remove the need for databases, secrets, tests, or security reviews. They make the ordinary path easier to build.

Runtime versus orchestration library

These categories overlap. LangGraph is orchestration-first: it gives you control over stateful execution. LangChain, AutoGen, and CrewAI bundle varying amounts of model clients, tools, memory, knowledge, workflows, and observability. Compare the actual abstractions and integrations in the version you plan to use.

An orchestration library gives you control primitives:

• a graph;
• a message loop;
• a supervisor;
• a role system; or
• a state machine.

You assemble more of the model client, tool definitions, memory, retrieval, logging, evaluation, and deployment yourself.

An agent runtime starts from the other end. It gives you an agent object and bundles common surrounding capabilities:

• model adapters and tools;
• memory and knowledge retrieval;
• deterministic workflows and structured output;
• evaluation, observability, and serving integrations.

The difference is not capability. A determined team can build the same refund agent with either approach. The difference is who assembles and maintains the seams:

A library says, “Here are the parts. Decide how they connect.”
A runtime says, “Here is the common connection. Replace it when you have a reason.”

Treat “runtime” as a packaging and product-shape description, not a scientific category.

Why bundling can help

A refund agent might:

1. Load conversation and account context.
2. Retrieve the applicable policy and check the order.
3. Request human approval for amounts above 100 dollars.
4. Call the refund API with a duplicate-safe key.
5. Save the decision and emit a trace.

Every step has a boundary:

• The model uses messages.
• The order API uses JSON.
• Policy search uses documents.
• Approval uses a pending task.
• Tracing wants spans and token counts.

When you assemble this yourself, every boundary needs an adapter. If one package calls a tool result content, another calls it output, and a third expects a typed object, your application becomes a translation service with a chatbot attached.

A runtime reduces this glue by choosing a common internal representation. One agent object can pass a tool result to the model, write a memory record, attach metadata to a trace, and validate structured output.

Fewer translations mean fewer opportunities to lose a customer identifier, tool error, or trace relationship.

The benefit is strongest on the runtime’s happy path. It weakens when you need unusual scheduling, a proprietary model protocol, a specialized event store, or control over every network call.

The mechanism: what you gain, and what you trade

A runtime improves developer speed by moving decisions from application code into tested defaults.

For a hand-built agent, you must decide:

• how tool calls are represented;
• where state is stored;
• how retries are recorded;
• which identifiers appear in logs; and
• how failed tools return to the model.

A runtime has made those decisions for its standard path. You configure behavior instead of writing connecting code.

That also lets features compose. A memory record can carry the same user and session identifiers as a tool call. A workflow step can appear in the same trace as a model invocation. An evaluator can inspect structured output without learning a private representation invented by your team.

The cost is coupling. You inherit the runtime’s dependency graph, release schedule, abstractions, and bugs. A provider feature may arrive late; a prototype database may become awkward at scale; an upgrade may change retry or message-format defaults.

Agent construction is also not agent execution. Agno describes agent instantiation in microseconds and emphasizes a small per-agent footprint. That can matter when a service creates many short-lived agents. It does not make a customer request finish in microseconds.

A useful model is:

request latency = model time + tool time + retrieval time + waiting time + runtime overhead

A runtime mainly attacks the last term and the engineering work around the others. Parallel or durable workflows may help, but they are design choices, not free speed.

A worked refund-agent calculation

Assume one refund request uses:

• 1,500 input tokens;
• 500 output tokens;
• 120 milliseconds for policy retrieval;
• 180 milliseconds for the order API;
• 800 milliseconds for the model.

At an illustrative provider price of 3 dollars per million input tokens and 15 dollars per million output tokens:

1,500 / 1,000,000 × 3 = 0.0045 dollars

500 / 1,000,000 × 15 = 0.0075 dollars

The model portion costs 0.012 dollars per request. At 10,000 requests per month, the illustrative model bill is 120 dollars, before retrieval, hosting, observability, and retries.

The single-model-call path with retrieval and order lookup takes about 1.1 seconds: 120 + 180 + 800 milliseconds. The real request also includes the refund API, persistence, additional model calls, and possibly unbounded human-approval latency.

Choosing Agno or Mastra does not change provider prices or remove the order API. It can reduce the code needed to connect them and make concurrent independent work easier where workflow semantics permit it.

A runtime is primarily a complexity and integration choice, not an automatic latency or token-cost optimization. For cost and latency work, see cost and latency control.

Agno: a fast, Python-native runtime

Agno is a Python-native runtime built around a compact agent abstraction. Define an agent, attach a model and tools, and use built-in support for memory, knowledge, structured output, multimodal inputs, and teams instead of assembling separate layers.

It is model-agnostic in that the abstraction is not tied to one provider. You still need a provider integration, credentials, and model identifier. Provider behavior—tool calling, context limits, structured output, and refusals—still requires testing.

# Reference example for a local Python project.
# Install the package and configure provider credentials before running.
from agno.agent import Agent
from agno.models.anthropic import Claude
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    model=Claude(id="claude-sonnet-4-6"),
    tools=[DuckDuckGoTools()],
    markdown=True,
)

agent.print_response("Summarize this week's agent-framework news.")

The important boundary is that the model adapter and tool belong to the same agent, whose runtime handles the model-tool loop.

For a refund agent, replace web search with narrowly scoped order and policy tools. Validate the user and tenant server-side; do not expose a general database client and rely on a prompt for authorization.

Agno’s low overhead is most useful when an API creates many agents or specialist configurations. Remote model and service latency dominate when each request already takes seconds.

Mastra: the TypeScript runtime for web products

Mastra brings the batteries-included approach to TypeScript and JavaScript applications. It provides agents, deterministic graph workflows, RAG, memory, evaluations, and observability for Node, Next.js, and web deployments.

That language fit matters when the product already has:

• TypeScript request handlers;
• authentication middleware;
• schema validators;
• database clients; and
• frontend types.

The agent can use the same session identity and validation rules instead of requiring a separate Python service.

// Reference example for a TypeScript/Node project.
import { Agent } from "@mastra/core/agent";
import { anthropic } from "@ai-sdk/anthropic";

export const researchAgent = new Agent({
  name: "research-agent",
  instructions: "Research a topic and summarize the findings.",
  model: anthropic("claude-sonnet-4-6"),
  tools: {
    // Add narrowly scoped, server-side tools here.
  },
});

Provider packages and model identifiers depend on project versions, so check current documentation before copying imports. The stable boundary is an agent with instructions, a model, and typed tools.

Mastra’s workflow model suits a refund process that must:

• retrieve the order;
• check policy;
• branch on amount;
• pause for approval;
• issue the refund; and
• write an audit record.

The model can interpret the request; the workflow should own the irreversible sequence.

Choosing by the real constraint

Choose by the constraint that will remain after the demo:

Keep domain logic behind ordinary interfaces so changing runtimes remains possible. refund_order should be a business operation with authorization and an idempotency key, not a function that depends on a framework’s private message type.

Policy search should return an application type rather than leaking runtime-specific document objects through every service.

What runtimes do not solve

A runtime can make a dangerous tool easy to call. It cannot make the tool safe.

It does not decide:

• whether the current user owns order A-1842;
• whether a refund is idempotent;
• whether an employee approval is genuine; or
• whether a retrieved policy is current.

Use:

• least privilege;
• server-side authorization;
• approval gates; and
• audit records.

See agent security and reliability for agent side effects.

Memory needs explicit boundaries. Working context, episodic records, and durable semantic facts are different things. A customer’s old delivery address should not silently become the address used for a financial action.

Define:

• what may be written;
• who may read it;
• how long it lasts; and
• which tenant namespace it uses.

The runtime can provide storage hooks, not your retention policy.

RAG has the same limitation. Document loading, chunking, embeddings, and retrieval do not establish that a policy applies to California orders in 2026 rather than a superseded global policy from 2023.

Enforce tenant, region, product, and effective-date filters before retrieval. Reject documents outside the valid window. Require the answer to identify the selected policy version. Test cases where the correct answer is “no applicable policy found.”

Failure modes you will actually see

Missing provider key. A batteries-included package still needs credentials and optional provider integrations. Load secrets through the deployment environment, validate configuration at startup, and keep provider-specific setup in one boundary.

Duplicate refunds after a timeout. The billing service accepted the request, but the response was lost and a retry sent the side effect again.

Generate a stable, server-controlled idempotency key for one refund operation. Scope it to:

• tenant;
• order;
• action; and
• amount.

Store it with the outcome. Never let the model invent it; retry helpers are not substitutes for an idempotent API.

Cross-customer memory. A missing session, user, or tenant key can make one customer’s data available to another. Log the namespace used for every read and write, test cross-tenant isolation, and enforce authorization at the data-access layer.

Unusable traces. A tool wrapper or exporter may drop structured inputs and outputs.

Capture:

• request ID;
• agent ID;
• model;
• tool name;
• duration;
• outcome; and
• a redacted argument summary—never raw payment tokens or unrestricted customer records.

Observability and tracing covers the broader pattern.

Behavior changes after an upgrade. Defaults, model adapters, tool formatting, and memory write behavior can change without a prompt change. Pin versions, run representative evaluations in CI, and inspect traces before promotion. HTTP 200 is not an evaluation.

If the job is “extract three fields from a document and insert them into a database,” a model SDK plus schema validation may be clearer.

If it is a seven-step process with approvals, retries, and durable pauses, use an explicit workflow or orchestration layer even if a runtime hosts it.

In one breath

• An agent runtime bundles model access, tools, memory, retrieval, workflows, evaluation, and operational hooks behind a language-native API.
• An orchestration library supplies control primitives and leaves more assembly to you.
• Bundling reduces adapter code and improves composition, but couples your system to the runtime’s abstractions, releases, and integrations.
• Agno fits Python-first services; Mastra fits TypeScript web products.
• Neither supplies authorization, safe side effects, tenant isolation, fresh knowledge, or good evaluations.
• Choose by ecosystem and operational shape. For a small deterministic task, use less; for a growing agent stack, consistent bundling may be worth the coupling.

Quick check

Next

Agent runtimes are one corner of the framework landscape. Compare the conversational AutoGen, the graph-based LangGraph, and the role-based CrewAI, all sitting on the broader orchestration patterns.