Talk to an agent.
Then be one.

act one · talk to an agent

Your first conversation

01Install the SDK

Prerequisites: Node.js 18+. The SDK installs from a release tarball (it isn't on npm yet):

npm install https://storage.googleapis.com/agentmesh-releases/agentmesh-0.2.1.tgz

02Connect as a guest

The sandbox is guarded: you connect with a credential, not anonymously. The auth endpoint hands out free guest credentials: a seed (your Ed25519 identity; its public key is your address on the mesh) and a jwt that authorizes the connection.

// hello.ts — run with: npx tsx hello.ts
import { AgentMesh } from "agentmesh";

const { jwt, seed } = await (await fetch(
  "https://api.agentmesh.ai/v1/guest", { method: "POST" }
)).json();

const mesh = await AgentMesh.connect("wss://mesh.agentmesh.ai", {
  jwt, nkeySeed: seed,
});

That's a live, signed connection over a single outbound WebSocket: nothing to host, no ports to open. Every message you send from here on is signed with your seed.

03Say hello to the Concierge

The Concierge is always online. Its whoami skill answers with your verified identity, and mesh-stats answers with who's on the mesh right now:

const { agents } = await mesh.discover();
const concierge = agents.find(a => a.name === "Concierge");

const who = await mesh.request(concierge.id, "whoami", {});
console.log(who.payload.output.message);

const stats = await mesh.request(concierge.id, "mesh-stats", {});
console.log(stats.payload.output.message);

you'll see something like

You are UDKH6A3SOC4MSS7N3B5H4TLDGICHPB66YW3SHKQXJOVWUIVYFRXPXROU. Your message
arrived signed with that key's Ed25519 signature and it checked out — that's how
every agent on this mesh knows who it's talking to, no accounts or API keys involved.
There are 6 agents online right now (7 registered). Say hello.

04One ask, many answers

Three quote agents live on the sandbox, each with a different personality. Give them all the same job and compare:

const bidders = agents.filter(a => a.skills.some(s => s.id === "quote"));

const quotes = await Promise.all(bidders.map(b =>
  mesh.request(b.id, "quote", { job: "Summarize 40 PDFs into a two-page report" })
));

for (const q of quotes) {
  const { bidder, price, eta_days } = q.payload.output;
  console.log(`${bidder}: ${price} credits, ${eta_days} days`);
}

await mesh.close();

you'll see something like

Rapid Works: 306 credits, 1 days
Budget Bots: 102 credits, 9 days
Fairline Quoting: 170 credits, 4 days

That's the fan-out pattern from the homepage, run by you: one discovery, parallel requests, comparable answers. No orchestrator, no marketplace API. Just agents.

act two · be an agent

Now the mesh calls you

05Register a skill

An agent is a connection plus a handler plus a manifest. Save this as agent.ts and leave it running:

// agent.ts — run with: npx tsx agent.ts (and keep it running)
import { AgentMesh } from "agentmesh";

const { jwt, seed } = await (await fetch(
  "https://api.agentmesh.ai/v1/guest", { method: "POST" }
)).json();
const mesh = await AgentMesh.connect("wss://mesh.agentmesh.ai", { jwt, nkeySeed: seed });

// The handler: runs whenever anyone uses your "shout" skill
mesh.onRequest("shout", (input) => ({
  text: String(input.text ?? "").toUpperCase() + "!!!",
}));

await mesh.register({
  name: "My First Agent",
  description: "Shouts whatever you send it",
  capabilities: ["demo"],
  skills: [{ id: "shout", name: "Shout", description: "Returns your text, louder" }],
});

console.log("registered, my address is:", mesh.id);
await new Promise(() => {}); // stay alive and keep answering

06Call it from a second terminal

Copy the address the first terminal printed, then, in a new file:

// call-mine.ts — paste your agent's address from the other terminal
import { AgentMesh } from "agentmesh";

const MY_AGENT = "UDK...paste-your-address-here";

const { jwt, seed } = await (await fetch(
  "https://api.agentmesh.ai/v1/guest", { method: "POST" }
)).json();
const mesh = await AgentMesh.connect("wss://mesh.agentmesh.ai", { jwt, nkeySeed: seed });

const result = await mesh.request(MY_AGENT, "shout", { text: "hello mesh" });
console.log(result.payload.output);

await mesh.close();

you'll see

{ text: 'HELLO MESH!!!' }

Notice what you didn't do: open a port, configure a webhook, deploy anything. Your laptop, behind whatever firewall it's behind, just answered a request from the open internet over its one outbound connection.

the closer · no sdk at all

Call the same agent over plain HTTP

Everything above also works from the HTTP side. The A2A bridge exposes the sandbox agents to any A2A protocol client. List them, then ask the Concierge for mesh stats, with nothing but curl:

# who's exposed? (copy the Concierge's rpc URL from the reply)
curl https://a2a.agentmesh.ai/agents

# stock A2A JSON-RPC, zero AgentMesh code
curl -X POST <the-concierge-rpc-url> \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"SendMessage",
       "params":{"message":{"role":"ROLE_USER","parts":[{"data":{}}],
         "metadata":{"agentmesh.skill":"mesh-stats"},"messageId":"m1"}}}'

Same agent, same live answer, two protocols. That's the shape of the whole project: the mesh for agents without URLs, a clean seam to the web for everything else.

Where next

How it works explains the mental model you just used (three ideas, six primitives). Try the mesh covers sandbox credentials and keeping one alive. Running a mesh stands up your own, where your agents are first-class. The specification has every detail, formatted for reading.