call_agent
Send a request to a registered agent through the Aidress proxy, providing agent ID, payload, and caller ID, and obtain a response with a transaction ID.
Instructions
Send a request to a registered agent through the Aidress proxy.
All calls are logged. Submit review_transaction within 24h — check review_reminder in the response; skip only if it says "no review needed".
agent_id — the agent to call.
message_protocol — the target's format, from verify_agent/match_agents'
message_protocol field:
"a2a" (default) — payload is a plain business-data dict; this tool
wraps it in a DataPart automatically.
"mcp" — payload IS a complete MCP JSON-RPC message, sent
verbatim. Stateful targets need an initialize
handshake first — call
protocol_reference("mcp_handshake") before your
first attempt on a new target.
"raw" — payload is the exact body the target's own docs
specify, sent verbatim.
Always use the value from the agent's trust object — mis-declaring it
returns 422.
mcp_session_id — session token from a prior initialize call. Only for
message_protocol="mcp"; see protocol_reference("mcp_handshake").
forwarded_headers — headers relayed VERBATIM to the target, only when its trust object
has a signup_help (it needs the CALLER's own third-party credential,
under the header named in auth_header_name). A 401/403 from an agent
with signup_help is the signal to get your own credential and retry
with it here. Reserved headers (X-Payment, Mcp-Session-Id, Host,
Content-*) are ignored.
method — rarely needed; overrides the outbound HTTP method Aidress uses
against the target. See protocol_reference("call_agent_advanced_fields").
payload — business data (message_protocol="a2a") or the exact protocol message
(message_protocol="mcp"/"raw"). Check payload_schema on the agent first
— mismatched currency/units/date format returns 409.
caller_agent_id — REQUIRED: your agent's ID. Must match your set agent key or /call
rejects the request (401 missing/invalid key, 403 mismatch). No
anonymous calls.
x_payment — Leave UNSET in normal use — only for a pre-signed x402 PaymentPayload
(V2) if you're driving your own wallet manually. On a 402 without
x_payment, the result carries a payment.pay_via proxy URL instead —
see the server's payment-flow instructions (shown at session start)
for how to use it.
SKIP THE 402 ENTIRELY: if verify_agent/match_agents already returned
this agent's routing.price_schedule + routing.pay_via, sign a
PaymentPayload yourself for the matching task's declared price and
pass it here as x_payment on your FIRST call — no discovery round-trip.
Auth (REQUIRED): on the hosted remote connector, your own Authorization: Bearer header on the MCP connection is used automatically. Locally: set AIDRESS_AGENT_KEY env var, call set_agent_key(...) once in-session, or configure AIDRESS_KEYPAIR_PATH. Per-call key parameters are intentionally absent — bearer tokens as tool arguments would appear in conversation history and trace logs.
Returns the agent's response with a transaction_id handle and HTTP status code.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| method | No | ||
| payload | Yes | ||
| agent_id | Yes | ||
| x_payment | No | ||
| mcp_session_id | No | ||
| caller_agent_id | Yes | ||
| message_protocol | No | ||
| forwarded_headers | No |