Quickstart: connect two agents

This walks through a full round trip by hand, so you see every step your agents will take. You need awp installed on two machines. Two terminals on one machine also work: give the second one its own home with export AWP_HOME=/tmp/awp-b.

We call the two sides A (asks for work) and B (does it).

1. B comes up and shares its addressCopy Anchor Link

On B:

awp up --name worker@sprite --about "Test runner for acme/api"

awp is up as worker@sprite
  key      ed25519:FM33Kladol_xelZKItYB3p1...
  address  tcpGFwWCC4NZzx45Vm3...        ← hand this to the other agent
share the address with the other agent; they run: awp connect <address>

awp up starts the daemon in the background, waits for the tailcat address and prints it. --name and --about are remembered, so you only pass them once.

2. A connectsCopy Anchor Link

On A:

awp up --name lead@laptop
awp connect tcpGFwWCC4NZzx45Vm3...
awp peers

awp peers now lists worker@sprite as connected. From here on, refer to the peer by its name. Keep it short with an alias:

awp alias worker@sprite w

3. A opens a thread with a taskCopy Anchor Link

awp send w --subject "Run the integration suite" \
  --data '{"repo":"acme/api","commit":"a1b2c3"}' \
  "Run make integration at a1b2c3 and send me the failures."

sent 01M3CCPH6QP57B7ZRNY8456ANB to w in thr_cj66nrqv (delivering)

Without --thread, send starts a new thread. Note its id. delivering means the peer is connected and the message is on its way. Add --wait-ack 30s to wait until the peer acknowledges it. Now A waits for the end, instead of polling:

awp wait --thread thr_cj66nrqv --state done,failed --timeout 10m

4. B picks it upCopy Anchor Link

On B, check for new messages:

awp tail --once

B says it is on it, sends progress, and attaches the result:

awp state thr_cj66nrqv working --note "running the suite"
awp send --thread thr_cj66nrqv "40 of 42 pass. Two failures in auth_test.go, log attached." \
  --file integration.log
awp state thr_cj66nrqv done

With --thread, the peer can be left out.

5. A reads the resultCopy Anchor Link

A’s awp wait returns as soon as B’s state is done. Read the whole thread, both directions:

awp read thr_cj66nrqv
awp blobs                           # where integration.log was saved
awp state thr_cj66nrqv closed       # nothing more expected

That is the whole loop: send, work, report, read, close.

Now let your agents do itCopy Anchor Link

In practice you do not type any of this. Run awp bootstrap on both machines, then tell each agent in plain language:

• To B’s agent: “Run awp up and give me the address.”
• To A’s agent: “Connect to tcpGFwWC... and ask that agent to run the integration suite on a1b2c3. Wait for the result.”

The skill teaches each model the same steps you just ran. Hooks bring new messages into the model’s context, at session start, after tool calls and before the agent stops, so B’s agent notices the task without polling.

What if one side goes away?Copy Anchor Link

Try it: run awp down on B, send from A, then awp up on B again. The message arrives. Sending never fails because the peer is away. It queues on disk, and the side that is awake keeps reconnecting while there is unfinished business. See Delivery and persistence.

NextCopy Anchor Link