inter-agent

Files (1)

• SKILL.md

SKILL.md (first lines)

# Inter-Agent Communication

You are part of a multi-agent team. Communicate with other agents via `curl` from the Bash tool. Do **NOT** use SendMessage, Agent, or any built-in Claude Code messaging tools — those are a different system and will not reach your team agents.

## The three patterns — copy these exactly

There are three ways to reach another agent. Copy the example for your case verbatim and change only `to` and `message`.

### 1. `/talk-to` — sync delegation (you need the reply)

```bash
curl -s -X POST http://localhost:$ID_AGENT_PORT/talk-to \
  -H "Content-Type: application/json" \
  -d '{"to":"agent-name","message":"what is your name?"}'
```

Blocks until the recipient replies. The reply is in the response body.

### 2. `/news-to` without `trigger` — passive notification (LLM is NOT woken)

```bash
curl -s -X POST http://localhost:$ID_AGENT_PORT/news-to \
  -H "Content-Type: application/json" \
  -d '{"to":"agent-name","message":"I am ready for work"}'
```

Returns 202 immediately. The message lands in the recipient's news feed but their LLM is **not** woken. They see it the next time they poll `/news` or are otherwise active. Use for status pings, "I claimed this task", "heads up — restarting in 5".

### 3. `/news-to` with `"trigger":true` — async delegation (LLM IS woken)

```bash
curl -s -X POST http://localhost:$ID_AGENT_PORT/news-to \
  -H "Content-Type: application/json" \
  -d '{"to":"agent-name","message":"I have a message, please pass it to the manager","trigger":true}'
```

Returns 202 immediately. The recipient's LLM **is** woken and processes the message as a new task. You do not get a reply on this HTTP call — the recipient can `/news-to` you back later with results. Use for telephone chains, long-running pipelines, and any handoff where holding a sync HTTP connection open would be wrong.

> ⚠️ **Critical: `trigger` is a literal boolean — copy the example above exactly.**
>
> When you want the recipient's LLM to actually process the message, the JSON body **MUST** include `"trigger":true` as a literal boolean (not a string, not omitted). Omitting the `trigger` field is a silent delivery failure: the message is stored in the recipient's news feed but the recipient **never processes it**. No error is returned — the call looks successful but the work never happens.
>
> If your intent is async delegation (pattern 3), the string `"trigger":true` **must** appear inside the JSON body. Copy the pattern-3 example above verbatim; do not reconstruct it from memory.

## When in doubt, use `/talk-to`

When you are not sure whether to use `/news-to` with `trigger:true` or `/talk-to`, **use `/talk-to`**. It blocks until the recipient replies, which is simpler to reason about for most cases — you get the answer back in-line and can continue your work. Only use `/news-to` with `trigger:true` when you specifically want async delegation: you don't need the reply in-line, but you do want the recipient to actually process the work.

Decision shortcut:
- Need the answer now to continue → `/talk-to` (pattern 1).
- Just telling somebody something → `/news-to` without `trigger` (pattern 2).
- Handing off work that may take minutes/hours and will be returned later → `/news-to` with `trigger:true` (pattern 3).

## Mandatory rule: when asked to "ask another agent"

If the user or manager says "ask coder …", "can you ask x …", or requests you to contact another agent:

1. You MUST use `/talk-to` (pattern 1) via curl and WAIT for their reply.
2. Include the reply in your response so the person who asked gets the answer.
3. Do NOT use SendMessage, Agent, or other built-in tools — use curl.

## Do not use `/message`

The old `/message` endpoint on the manager is **deprecated** — it responds with an `X-Deprecated` header and will be removed. Use `/talk-to` or `/news-to` on your local wrapper instead.

## How replies work (automatic)

**When someone sends you a message, your reply is sent automatically.** You do NOT need to run any curl command to reply.

1. Another agent sends you a message via `/talk-to` (which reaches you as `/talk`).
2. You process the message and generate your response.
3. Your response is automatically sent back to the sender.

**DO NOT** run curl against `/news` or `/news-to` to reply — your text output IS the reply.

## List available agents

```bash
curl -s $MANAGER_URL/agents -H "X-Id-Team: $ID_TEAM" | jq
```

The `name` field is the agent's full identifier (ENS domain after registration, or local name). Use this name as the `to` value when sending messages. The `url` field is the peer's REST-AP base URL — used by the catalog-aware selection flow below.

Both `/talk-to` and `/news-to` are exposed on your own local agent wrapper (`http://localhost:$ID_AGENT_PORT`). The wrapper looks up the target in the manager catalog and delivers the message.

## Choosing the right agent to delegate to

`/agents` only tells you **who exists**. It does not tell you who is the right peer for a given piece of work. Before `/talk-to` or `/news-to`, always run the catalog-aware selection flow.

### Step 1 — Enumerate peers

List candidates from the manager:

```bash
curl -s $MANAGER_URL/agents -H "X-Id-Team: $ID_TEAM" | jq '.agents[] | {name, alias, status, url}'
```

### Step 2 — BEFORE delegating, fetch each candidate's catalog

For every candidate from Step 1, GET `/catalog` and read `role`, `expertise`, `status`, `costTier`, and `notSuitableFor`. Do **not** rely on names or aliases alone:

```bash
# Single peer
curl -s http://localhost:<peer-port>/catalog | jq
```

```bash
# Manager-discovery substitution: resolve every peer's /catalog in one pass
for url in $(curl -s $MANAGER_URL/agents -H "X-Id-Team: $ID_TEAM" | jq -r '.agents[].url'); do
  echo "== $url =="
  curl -s "$url/catalog" | jq '{role, expertise, status, costTier, notSuitableFor}'
done
```

### Step 3 — Filter

Drop any candidate where:

- `status !== "available"` (e.g., `busy`, `offline`, `error`) — they cannot take new work.

From idchain-world/id-agents, MIT.

More from idchain-world/id-agents