> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# 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) (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.

> **Note**
>
> The agent mesh is in preview. You see the **Agent mesh** interface in the deploy form only where it is enabled.

## 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.

<defs>
  <path d="M0,0 L10,5 L0,10 z" />
</defs>

<rect x="24" y="72" width="180" height="64" rx="10" />

Web chat

<rect x="24" y="164" width="180" height="64" rx="10" />

Slack

<rect x="24" y="256" width="180" height="64" rx="10" />

Agent mesh

<rect x="260" y="24" width="676" height="392" rx="16" />

<text x="284" y="54">
  Astropods runs
</text>

<text x="284" y="78">
  Interfaces and the mesh connection
</text>

<rect x="300" y="98" width="596" height="294" rx="14" />

<text x="324" y="128">
  Blueprint
</text>

<text x="324" y="150">
  astropods.yml
</text>

You bring

<rect x="340" y="168" width="516" height="200" rx="12" />

<text x="364" y="198">
  Adapter
</text>

serve(agent)

<rect x="380" y="232" width="436" height="112" rx="10" />

Your agent

Mastra · LangChain · your own code, unchanged

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.

**`Mastra`**

```typescript title="Mastra"
import { serve } from '@astropods/adapter-mastra';

serve(agent);
```

**`LangChain`**

```python title="LangChain"
from astropods_adapter_langchain import LangChainAdapter, serve

serve(LangChainAdapter(agent, name="My Agent"))
```

See [Adapters](/adapters/overview) 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.

<defs>
  <path d="M0,0 L10,5 L0,10 z" />

  <path d="M0,0 L10,5 L0,10 z" />
</defs>

<text x="24" y="114">
  Reaches the agent
</text>

The agent uses

[<rect x="24" y="128" width="264" height="44" rx="8" /><text x="40" y="155">
  Interfaces
</text>](/deploy-agent)

Web chat, Slack

[<rect x="24" y="200" width="264" height="44" rx="8" /><text x="40" y="227">
  Agent mesh
</text>](/amp)

Tasks by job

[<rect x="24" y="272" width="264" height="44" rx="8" /><text x="40" y="299">
  Access
</text>](/audiences)

Who can use it

[<rect x="24" y="344" width="264" height="44" rx="8" /><text x="40" y="371">
  Human input
</text>](/ask-for-input)

Forms mid-turn

[<rect x="672" y="112" width="264" height="44" rx="8" /><text x="688" y="139">
  Models
</text>](/ai-gateway)

AI Gateway

[<rect x="672" y="160" width="264" height="44" rx="8" /><text x="688" y="187">
  Knowledge stores
</text>](/knowledge-stores)

Shared data

[<rect x="672" y="208" width="264" height="44" rx="8" /><text x="688" y="235">
  Storage
</text>](/agent-sqlite)

SQLite

[<rect x="672" y="256" width="264" height="44" rx="8" /><text x="688" y="283">
  Connections
</text>](/agent-connections)

User accounts

[<rect x="672" y="304" width="264" height="44" rx="8" /><text x="688" y="331">
  Secrets
</text>](/secrets)

Account vault

[<rect x="672" y="352" width="264" height="44" rx="8" /><text x="688" y="379">
  Sandbox
</text>](/remote-sandbox)

Isolated code

<rect x="348" y="104" width="264" height="300" rx="14" />

<text x="370" y="132">
  AstroAgent
</text>

[<rect x="376" y="150" width="208" height="100" rx="10" />](/adapters/overview)

Your agent

Any framework

[<rect x="376" y="266" width="208" height="86" rx="10" />](/adapters/overview)

Adapter

serve(agent)

[<rect x="348" y="24" width="264" height="44" rx="8" /><text x="364" y="51">
  Evals
</text>](/evals)

Checks on traces

[<rect x="348" y="444" width="264" height="44" rx="8" /><text x="364" y="471">
  Blueprint
</text>](/astropods-package-spec)

astropods.yml

### 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](/deploy-agent).
* **Agent mesh:** other agents send your agent tasks based on its jobs. See [Agent Mesh Protocol](/amp).
* **Access:** you decide who can use your agent with an audience, a list of people. See [Audiences](/audiences) and [Access control](/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](/ask-for-input).

### Models, data, and tools

* **Models:** your agent calls models from several providers through the AI Gateway. See [AI Gateway](/ai-gateway).
* **Knowledge stores:** you connect a database once and share it across your agents. See [Knowledge stores](/knowledge-stores).
* **Storage:** your agent gets a SQLite database that keeps its data between restarts. See [Store data with SQLite](/agent-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](/agent-connections).
* **Secrets:** you keep API keys and credentials in the account vault. See [Managing secrets](/secrets).
* **Sandbox:** your agent can run code in an isolated VM. Sandboxes are experimental. See [Remote Sandbox](/remote-sandbox).

### Blueprint and evals

* **Blueprint:** your `astropods.yml` file describes your agent, and you publish it to the Astropods registry. See [Astropods Spec](/astropods-package-spec) and [Your first blueprint](/blueprints).
* **Evals:** you run automated checks against your agent's production traces. See [Evaluate your agents](/evals).

## 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.

<defs>
  <path d="M0,0 L10,5 L0,10 z" />

  <path d="M0,0 L10,5 L0,10 z" />
</defs>

<rect x="16" y="16" width="660" height="480" rx="16" />

<text x="36" y="46">
  Astropods
</text>

<rect x="36" y="64" width="196" height="200" rx="12" />

<text x="50" y="90">
  Common cloud
</text>

<text x="50" y="112">
  Shared infrastructure
</text>

<rect x="48" y="128" width="172" height="96" rx="10" />

Writer agent

notes.summarize

<rect x="248" y="64" width="196" height="200" rx="12" />

<text x="262" y="90">
  Dedicated cloud
</text>

<text x="262" y="112">
  Reserved for your account
</text>

<rect x="260" y="128" width="172" height="96" rx="10" />

Analyst agent

sales.forecast

<rect x="460" y="64" width="196" height="200" rx="12" />

<text x="474" y="90">
  On premises
</text>

<text x="474" y="112">
  In your data center
</text>

<rect x="472" y="128" width="172" height="96" rx="10" />

Data agent

sql.query

<rect x="236" y="334" width="220" height="130" rx="12" />

Agent mesh

Routes by job

Leases and policy

<rect x="700" y="196" width="244" height="300" rx="14" />

<text x="718" y="224">
  Public internet
</text>

<rect x="749" y="246" width="146" height="84" rx="10" />

A2A gateway

A2A to AMP

<rect x="749" y="386" width="146" height="84" rx="10" />

A2A agent

Any vendor

<rect x="740" y="34" width="164" height="84" rx="10" />

Other account

Blocked

<line x1="740" y1="76" x2="678" y2="76" />

<circle cx="709" cy="76" r="12" />

<path d="M703.5,70.5 L714.5,81.5 M714.5,70.5 L703.5,81.5" />

<text x="96" y="537">
  Outbound AMP connection
</text>

<text x="386" y="537">
  A2A over HTTPS
</text>

<rect x="560" y="520" width="44" height="24" rx="6" />

<text x="616" y="537">
  Network boundary
</text>

<line x1="790" y1="532" x2="834" y2="532" />

<text x="846" y="537">
  Blocked
</text>

* **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`:

**`astropods.yml`**

```yaml title="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

#### [Get started](/get-started)

Create and run your first agent locally

#### [Blueprints](/blueprints)

Build and publish your agent to the Astropods registry

#### [Agent Mesh Protocol](/amp)

The protocol that AstroAgents use

#### [Life of a task](/amp/life-of-a-task)

Each step of one task, from send to result

#### [AMP and A2A](/amp/a2a)

How AstroAgents work with A2A agents

#### [Specification](/amp/specification)

The normative protocol