Agent-to-agent communication
AgentX offers mesh task routing between configured daemons and a standalone A2A protocol server for external clients. Choose the interface that matches your caller.
Send work to an AgentX peer
First pair your machines. The peer name comes from agentx mesh list; the agent ID belongs to that peer:
agentx daemon send helper "Reply with a short hello" --peer work-machineThis sends a task through your local daemon to the named peer. It runs the remote agent with that agent's configured tools and provider. On the Hub, Live shows the work while it runs and Activity lists it once it ends.
The corresponding local HTTP request is:
curl http://127.0.0.1:18800/mesh/task \
-H 'Content-Type: application/json' \
-d '{"peer":"work-machine","agent":"helper","message":"Reply with a short hello"}'Remote protected daemon requests need Authorization: Bearer <mesh-token>. Reads that expose task content are protected the same way: task traces (/traces, /traces/<id>), which hold each task's full prompt and answer, recent events and agent memory. On the daemon's own machine they need no token. The daemon's /mesh/task endpoint also supports stream: true. Asynchronous delivery requires an originating context.channel and context.chatId so the result has a return destination.
When an agent sends work from a conversation a person started, the request returns at once and the answer comes back to that agent as a new message. See When an agent asks another agent.
Send work to an agent on this machine
A script on the same machine can give work to one of its agents with POST /task:
curl http://127.0.0.1:18800/task \
-H 'Content-Type: application/json' \
-d '{"agent":"helper","message":"Reply with a short hello"}'The request stays open until the agent answers. If the agent is busy with other work, the request first waits for it to be free, for up to 25 minutes.
Keep the connection open if the message must run. A caller that disconnects (for example curl -m 30 timing out) before the agent is free has its request dropped: it never runs, and nothing is sent back. Once the agent has started the work, a disconnect no longer stops it. There is no fire-and-forget mode for scripts: only an agent asking from a conversation a person started gets an early answer and its reply later (When an agent asks another agent). So set your client's timeout to more than 25 minutes plus the time the work takes, and don't treat a timeout as "delivered". If you resend after a timeout, the message may run twice when the first attempt had already started.
Serve the standalone A2A protocol
The standalone command starts a separate provider-backed server. It does not select a named daemon agent. Configure and authenticate the chosen provider first:
agentx a2a --host 127.0.0.1 --port 3171 --provider claude-codeIts agent card is available at GET /.well-known/agent-card.json. Send JSON-RPC requests to POST /:
curl http://127.0.0.1:3171/ \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"tasks/send","params":{"id":"hello-1","message":{"role":"user","parts":[{"type":"text","text":"Reply with a short hello"}]}}}'| Implemented method | Purpose |
|---|---|
tasks/send | Run a task and return its result |
tasks/sendSubscribe | Stream task updates over SSE |
tasks/get | Read a task's state |
tasks/cancel | Request cancellation |
These are the method names implemented by this checkout; check external clients for protocol compatibility. Task state lives in memory and is lost when the standalone server stops. It does not implement mesh bearer authentication, so keep it on loopback or provide an authenticated gateway for remote use. The command's default host is 0.0.0.0; the example deliberately sets loopback.
For source installations, use node dist/cli.js in place of agentx in these commands.
Check it worked
- Terminal: run
agentx mesh list. The peer you send to is listed. - Terminal: send the hello task above. The reply prints in the terminal, and the work shows on the Hub's Activity page.
- Terminal: send the
POST /taskrequest above. It prints the agent's answer as JSON. - For the standalone server:
curl http://127.0.0.1:3171/.well-known/agent-card.jsonreturns the agent card.
If something is wrong
Mesh not enabled: this daemon has no mesh set up. Pair your machines first.401from the peer: the two machines don't share the same mesh token. See Add a second machine.- The peer can't find the agent: the agent ID must be one configured on that peer, not on this machine.
- A
POST /taskmessage never ran: the caller probably disconnected while the agent was busy. The daemon log showscaller gone during slot wait — not starting. Keep the connection open longer and send it again. - The standalone server doesn't answer: check that the chosen
--provideris installed and signed in on that machine.
