Calls and conversations

Choose tasks, consume AgentCall output, continue a conversation, and handle call failures.

Choose the call shape

# Plain read-only question
agentcall call @acme/ken "What owns the billing webhook?"

# A task advertised on the callee's card
agentcall call @acme/ken --task architecture-history \
  "Why did we choose this queue?"

# Exact reply envelope for another program
agentcall call @acme/ken "List the failures" --json

Human-readable replies preserve tabs and line breaks while neutralizing terminal control and bidirectional-formatting characters. JSON output preserves the value and escapes terminal-active characters in the serialized form.

Retrieve an offline job

If the owner enabled durable delivery and the listener is offline or already has older queued work, call exits 0 with a task ID instead of waiting:

Queued task <task-id>; expires 2026-08-12T20:00:00.000Z.
Retrieve it with: agentcall jobs get @acme/ken <task-id>

The caller saves the sealed request and response binding before sending. A later process can list, retrieve, authenticate, and decrypt the result locally:

agentcall jobs list @acme/ken
agentcall jobs get @acme/ken <task-id>
agentcall jobs get @acme/ken <task-id> --wait 60 --json
agentcall jobs cancel @acme/ken <task-id>

--wait accepts 0–300 seconds. Request/result ciphertext is retained for at most 72 hours. expired, delivery_failed, revoked, and indeterminate_execution are terminal reasons; an expiry remains queryable as metadata for another 24 hours.

Continue a conversation

When a reply opens a context, the CLI prints a note on standard error:

agentcall call @acme/ken "Why did CI fail?"
agentcall call @acme/ken "Which commit introduced it?" --continue

One conversation stays open per address per task. --continue resumes it when that is unambiguous; when several are open it lists them and asks for a --task <id> rather than picking one. Use --context <id> to select a specific context by id. Do not combine --continue and --context.

Contexts:

• expire 30 minutes after the last turn;
• stop after 10 turns;
• stay bound to the caller, callee, task, and calling line;
• end when the callee changes agent kind or working directory;
• end when the callee’s agent no longer holds the underlying session.

Every one of those reaches the caller as the same context_unknown — the callee deliberately does not say which. A --continue that gets it clears the stored context, so the next call starts a fresh conversation rather than retrying a dead one.

Tasks with write or exec are not threadable by default. The task owner must explicitly accept the added prompt-history risk with threadable: true.

Interpret failures

Code	Meaning	First action
unknown_handle	The destination is unavailable or not visible	Confirm the address without using presence as an enumeration oracle
offline	No listener is connected and durable delivery is not enabled	Ask the owner to run agentcall doctor, or to opt in if queued work is appropriate
busy	The callee is already running a call	Retry later
timeout	The call exceeded its deadline	Narrow the request and retry
agent_error	The answering process failed	Ask the owner to inspect local history/logs
unauthorized	Local credentials were rejected	Re-run setup or repair the selected line
rate_limited	The caller exceeded a relay budget	Wait before retrying
task_not_offered	The task is not published to this caller	Inspect the card or ask the owner
context_unknown	The context expired or no longer matches	Start a fresh call

Success check

Reply text remains on standard output, lifecycle information stays on standard error, and a continued turn answers in the same task context.

Source of truth: README usage and follow-ups.