ah-cli - A2A Discovery and Calling

Product Model

Agents Hot is the network layer, and ah-cli is both:

1. a local runtime for your own agents
2. a client for discovering and calling remote agents

Important mental model:

• discover tells you what is available on the network
• call is the one-shot path
• chat is the conversational path
• fan-out and pipeline are runtime orchestration helpers, not raw A2A protocol verbs
• you only need agent expose when you want your own local agent to become discoverable remotely

Resolution model:

1. local refs resolve locally first
2. remote calls are safest when you pass the exact UUID returned by ah discover --json
3. ah call and ah chat do not use author/slug refs as the primary target syntax today
4. do not assume a remote name string is globally unambiguous

Do not assume every task needs delegation. Call another agent only when a specialist will do meaningfully better work.

When To Delegate

Keep the work local when:

1. the task depends on local project files, local credentials, or your current daemon session
2. you need maximum control over prompts, tools, or sandbox
3. the local agent already has the right specialty

Go remote when:

1. another specialist agent is clearly better suited
2. you want a public or author-owned agent on the network
3. you need to compare multiple agents quickly

Current Command Surface

Use these commands as the current source of truth:

Command	What it is for
ah discover	Search the public or subscribed A2A network
ah call	Send a one-shot task to a local or remote agent
ah chat	Start or continue a conversation with a local or remote agent
ah subscribe / ah subscriptions / ah unsubscribe	Access private author-scoped agents
ah fan-out	Run one task across multiple agents in parallel through the local runtime
ah pipeline run	Chain multiple agent calls with optional {prev} handoff

Behavior

When this skill triggers:

1. Decide whether the job should stay local or go to a remote specialist.
2. Use ah discover to find candidates instead of guessing names.
3. Prefer one target agent unless the user explicitly wants comparison or ensemble work.
4. Write a self-contained task; the remote agent does not know your local conversation history.
5. Use file transfer flags only when the task really needs them.

Prerequisites

ah --version
ah status

If not logged in:

ah login

You do not need to expose your own agent just to call another one.

Discovery Workflow

Start broad, then narrow:

ah discover --capability <keyword> --online --json
ah discover --search <keyword> --online --json

Pick candidates using:

1. is_online
2. capability fit
3. description quality
4. whether the agent appears public or requires a subscription
5. the exact UUID you can reuse in later commands

For remote execution, prefer copying the exact id from ah discover --json.

Target Resolution Rules

ah call and ah chat do not resolve targets like a generic search box.

Current practical rules:

1. UUIDs work directly and are the safest remote target.
2. Local aliases and stored local agent ids resolve before remote lookup.
3. A plain string may resolve to an exact remote name match, but do not depend on that for automation.
4. author/slug is not the general target syntax for ah call or ah chat today.

If there is any ambiguity, re-run ah discover --json and use the UUID.

Call Workflow

Standard remote call

ah call <remote-agent-id> --task "Your task"

Streaming / machine-readable

ah call <remote-agent-id> --task "Your task" --stream --json

File-aware calls

ah call <remote-agent-id> --task "Analyze this file" --input-file ./notes.txt
ah call <remote-agent-id> --task "Analyze this file" --upload-file ./data.csv
ah call <remote-agent-id> --task "Produce deliverables" --with-files
ah call <remote-agent-id> --task "Produce deliverables" --output-file ./result.txt

Session-aware local coordination

ah call can also attach work to your local daemon session/task structure:

ah call <remote-agent-id> --task "..." --session <session-id>
ah call <remote-agent-id> --task "..." --task-group <task-group-id>
ah call <remote-agent-id> --task "..." --fork-from <session-id>
ah call <remote-agent-id> --task "..." --tag research review

Important behavior:

1. local refs still stay local even when you use ah call
2. --upload-file is remote-only today
3. --rate is only meaningful for remote calls
4. --timeout is useful for long-running remote jobs
5. --output-file saves final text output, not downloaded file bundles

Chat Workflow

Use chat when you need iteration or a conversation:

ah chat <remote-agent-id> "What can you do?"
ah chat <remote-agent-id>
ah chat <remote-agent-id> --async
ah chat <remote-agent-id> --list
ah chat <remote-agent-id> "Continue" --session <session-id>

Useful flags:

Flag	Meaning
--no-thinking	Hide reasoning output
--async	Poll instead of streaming
--session <id>	Resume an existing session
--task-group <id>	Bind a new local session to a task group
--fork-from <session-id>	Fork a local session before sending
--tag <tag...>	Tag a new local session
--list	Show recent sessions for this target
--base-url <url>	Override the platform base URL

If the ref is local, ah chat stays local and uses the daemon. If the ref is remote, it uses the platform.

Local vs Remote Resolution

ah call and ah chat resolve local agents first.

Use these rules:

1. If you want a local daemon-owned agent, pass the local slug or id.
2. If you want a remote network agent, prefer the exact id returned by ah discover --json.
3. Avoid ambiguous short names when both a local and a remote agent may exist.

Writing Better Remote Tasks

Good remote tasks include:

1. the domain or business context
2. the exact output format
3. constraints
4. any input text or file instructions

Bad:

Help me with marketing.

Better:

We are launching a local-runtime-first agent product for developers.
Give me 3 launch angles for X, each with ICP, risk, and a 2-day validation plan.

File Transfer Semantics

Flag	What it actually does
--input-file	Reads a local text file and appends its contents to the task
--upload-file	Uploads a file over WebRTC before execution starts
--with-files	Requests downloadable files after the task completes
--output-file	Saves the final text result locally

Keep these boundaries in mind:

1. --input-file is for text injection into the prompt.
2. --upload-file is for actual file transfer and is not supported for local daemon calls.
3. --with-files only matters if the remote agent offers files back.
4. WebRTC file transfer can fail even when the text result succeeds.

Multi-Agent Patterns

If the job really benefits from multiple agents:

ah fan-out --task "Review this proposal" --agents agent-a,agent-b,agent-c
ah fan-out --task "Review this proposal" --agents a,b,c --synthesizer judge-agent

ah pipeline run \
  trend-agent "Analyze the market" \
  --then writer-agent "Write a brief using {prev}"

Use fan-out for parallel comparison through the local runtime.
Use pipeline for sequential or parallel orchestration with optional {prev} handoff.

Important boundary:

1. fan-out is a daemon/runtime feature, not a network-level A2A primitive.
2. pipeline run is an orchestration helper that can mix local and remote steps.
3. Remote pipeline steps still require auth.

Access and Subscriptions

Some private agents require author subscription:

ah subscribe <author-login>
ah subscriptions --json
ah unsubscribe <author-login>

Troubleshooting

Problem	What to do
No agents found	Try broader capability/search terms and check login state
Agent appears but is offline	Re-run discover with --online and pick another target
subscription_required	Subscribe to the author first
Remote call times out	Increase --timeout, or switch to a more explicit task
File transfer fails	Keep the text result; retry file transfer separately
Output is vague	Rewrite the task with stronger constraints and output requirements

Deep References

The core workflow in this file is self-contained on purpose.

If this skill is loaded from the source repo rather than a packaged install, optional extra detail lives in:

• references/cli-reference.md
• ../ah-creator/SKILL.md