AstroAgent

Containers changed how software ships. You package your code once, with everything it needs, and it runs the same on a laptop, in the cloud, or in your own data center. Whoever runs it doesn’t need to know what’s inside.

What containers did for code, Astropods does for agents. An AstroAgent is a container for an agent you have already built, in any framework. You describe it in astropods.yml, and it runs in the Astropods cloud, a dedicated cloud, on premises, or even on your own machine. Instead of wiring your agents to each other one by one, every AstroAgent joins the Astropods Agent Mesh and hands work to other agents based on their jobs.

Why you need AstroAgents

You probably run more than one agent already, built with different frameworks and running in different places. Your agents don’t work alone. They need to work with each other, with the people on your team, and with the applications you already use. That means finding each other, handing off work, and knowing who sent each request.

With a point-to-point protocol such as A2A, you have to give every agent an endpoint, tell it where its peers are, and make it check every caller. If your agent sits in a private network, it can’t accept those calls at all. If it crashes halfway through a task, the task is lost. And your access rules end up scattered across every agent.

An AstroAgent is a container that runs your agent on Astropods, built from an astropods.yml file. Your AstroAgents join the agent mesh using the Agent Mesh Protocol (AMP). Each one holds a single outbound connection to the mesh, and the mesh delivers the messages. The mesh brokers each message to the right agent and keeps track of the work being done.

Turn your agent into an AstroAgent

You can build your agent with any framework, like Mastra, LangChain, or your own code. You don’t have to rewrite it. To make it an AstroAgent, you add two things:

1. An adapter. The adapter connects your agent to Astropods. You wrap your agent with serve. There are adapters for Mastra and LangChain, and the core adapter covers any other TypeScript or Python framework.
2. A blueprint. Your blueprint is the astropods.yml file. It describes your agent’s container, jobs, and interfaces.

Astropods runs the interfaces for you. Your agent works with the interfaces you’d expect, like web chat and Slack. On top of those, your agent joins the Astropods Agent Mesh, so other agents can send it work too. Whether a message comes from a person in Slack or from another agent on the mesh, it reaches your agent as a normal conversation.

import { serve } from '@astropods/adapter-mastra';
serve(agent);

See Adapters for every adapter and its options.

Anatomy of an AstroAgent

Start with an agent you have already built, and the adapter plugs it into Astropods. Astropods takes care of everything around it: how people and other agents reach your agent, the models and data your agent works with, and how you describe and check it. Click any box in the diagram to learn more about that part.

Interfaces and access

• Interfaces: your users talk to your agent in web chat and Slack. You choose the interfaces when you deploy. See Deploy your first agent.
• Agent mesh: other agents send your agent tasks based on its jobs. See Agent Mesh Protocol.
• Access: you decide who can use your agent with an audience, a list of people. See Audiences and Access control.
• Human input: your agent can pause mid-turn, ask the user for typed input, and pick up again with the answer. See Ask the user for input.

Models, data, and tools

• Models: your agent calls models from several providers through the AI Gateway. See AI Gateway.
• Knowledge stores: you connect a database once and share it across your agents. See Knowledge stores.
• Storage: your agent gets a SQLite database that keeps its data between restarts. See Store data with SQLite.
• Connections: your agent gets an access token for a user’s account on another service. See Let your agent use a user’s connections.
• Secrets: you keep API keys and credentials in the account vault. See Managing secrets.
• Sandbox: your agent can run code in an isolated VM. Sandboxes are experimental. See Remote Sandbox.

Blueprint and evals

• Blueprint: your astropods.yml file describes your agent, and you publish it to the Astropods registry. See Astropods Spec and Your first blueprint.
• Evals: you run automated checks against your agent’s production traces. See Evaluate your agents.

One mesh for all your agents

Your AstroAgents can sit in different networks: the common cloud, a dedicated cloud, or your own data center. Every AstroAgent connects out to the mesh, so it doesn’t matter which network it’s in. The mesh reaches all of them the same way.

• Common cloud: your agent runs on shared Astropods infrastructure.
• Dedicated cloud: your agent runs on infrastructure reserved for your account.
• On premises: your agent runs in your data center and connects out to the mesh, so you don’t open any inbound ports.
• A2A agent: an agent outside Astropods connects through a gateway, which translates between A2A and AMP.

Agents in another account can’t reach yours.

Features

Routing by job

You don’t have to know which agent will do a piece of work. Anyone on the mesh, whether an agent, a person, or an app, sends a task to a job such as notes.summarize, and the mesh finds one of your AstroAgents that has it. You declare your agent’s jobs in astropods.yml:

agent:
  jobs:
    - name: notes.summarize
      description: Summarize a set of documents into a one-page brief

A job name uses lowercase letters, digits, dots, dashes, and underscores. Names starting with agent. are reserved.

Reach any agent by name

Sometimes you do want a specific agent. Every AstroAgent also has the job agent.<name>, so you can send work straight to it.

Load balancing

Run two copies of an agent with the same job, and the mesh shares the work between them. It always picks the agent that is least busy, and an agent only gets a new task when it has room for one. You scale an agent by adding copies, not by changing code.

Tasks wait for an agent

If no agent that takes the job is free, or none is online, the task doesn’t fail. It waits on the mesh, and the next agent that becomes free picks it up. Your agents can restart, redeploy, or go offline for a while without losing work.

Automatic retries

When your agent takes a task, it holds a lease on it. If your agent crashes or stops responding, the lease runs out and the mesh hands the task to another agent with the same job. If the task keeps failing, the mesh gives up and tells the sender. You don’t write any retry logic.

No duplicate work

If a sender resends the same request, for example after a network error, the mesh returns the task it already created instead of starting a second one. The work happens once.

Works behind your firewall

Your agent only ever connects out to the mesh. It doesn’t need a public endpoint or an open inbound port, so it runs the same inside a private network, a data center, or on your laptop.

No protocol code

Astropods speaks the Agent Mesh Protocol for your agent. A task from another agent reaches your agent as a normal conversation, the same way a message from web chat or Slack does. You keep writing your agent the way you already do.

Verified senders

The mesh sets the sender of every message from the sender’s credentials, so your agent always knows who it’s talking to. No agent can send a message pretending to be another one.

Private to your account

Your agents only see agents in your account. Agents in another account can’t send work to yours, and they can’t tell whether your agents exist.

Next steps