Remote Execution
With a connection in effect, agent.run() and agent.stream() run the agent of the same name on a remote Astromesh node instead of the local runtime. Available since astromesh-adk v0.4.0; before it, the connection was recorded and ignored.
The local definition is a handle: the agent has to be deployed on the node under the same name (as an *.agent.yaml, from Cortex, or with astromeshctl). Its Python @tools and its handler do not travel — the node runs the agent it has.
Connect Globally
Section titled “Connect Globally”from astromesh_adk import connect, disconnect
connect(url="https://node.example.com", api_key="ask-xxx")result = await my_agent.run("query")disconnect()Context Manager
Section titled “Context Manager”from astromesh_adk import remote
async with remote("https://node.example.com", api_key="..."): result = await agent.run("query")# back to the local runtime (or to the connect() global) herePer-Agent Binding
Section titled “Per-Agent Binding”my_agent.bind(remote="https://node.example.com", api_key="...")result = await my_agent.run("query")my_agent.bind(None, None) # unbindResolution Priority
Section titled “Resolution Priority”agent.bind()(per-agent)remote()context manager (scoped withcontextvars, safe across concurrent tasks)connect()global- Local runtime
Passing runtime= to run()/stream() always runs locally on that runtime.
What Goes Over the Wire
Section titled “What Goes Over the Wire”| Call | Node endpoint | Notes |
|---|---|---|
run(query, session_id, context) | POST /v1/agents/{name}/run | context is sent as the run context. |
stream(query, session_id) | WebSocket /v1/ws/agent/{name}?session_id=… | The WS protocol carries only the query, so context is not sent when streaming. Events map to token (model text), step (each tool_call) and done (with the RunResult). |
The API key goes as both Authorization: Bearer <key> and X-API-Key: <key>, and neither is sent when the key is empty. A bare node doesn’t authenticate; the key is for the hub (Nexus) or a gateway in front of it.
Every remote call declares origen: "agente" (in the POST body and in the WS message): it is an agent talking to another agent, never the person. The node therefore never takes the calling model’s "si" as human confirmation of a requires_approval tool, so a remote agent used as a tool (as_tool()) cannot be confirmed by its parent. The person confirms by talking to the remote agent directly (the node’s default origen is "humano"). The protection requires a node >= 0.73; older nodes ignore the field.
The RunResult from a remote run fills answer, steps, trace, tokens and model from the node’s usage, adds up cost across usage.by_model, and measures latency_ms on the client. metadata carries remote (the node URL), propuestas (writes a mode: propose tool left for approval), data and chain.
Errors
Section titled “Errors”| Situation | Exception |
|---|---|
| The node has no agent with that name (HTTP 404) | AgentNotFoundError |
The node answers an error (4xx/5xx), or the stream sends an error event | RemoteError, with the node’s detail |
| The node can’t be reached | RemoteUnavailableError |
Remote A2A Agents
Section titled “Remote A2A Agents”remote_a2a() reaches an agent that speaks A2A (any framework, not only Astromesh) through astromesh-a2a (overview: A2A). It has the same shape as an ADK agent: run(), stream() and as_tool().
pip install 'astromesh-adk[a2a]'from astromesh_adk import agent, remote_a2a
agenda = remote_a2a( "https://agents.example.com/.well-known/agent-card.json", api_key_env="AGENDA_KEY", # optional: the variable's NAME, sent as X-API-Key policy={"timeout": 30}, # optional: max_bytes, timeout, accept_parts, allow_insecure_http)
result = await agenda.run("Book me on Tuesday", session_id="s1")print(result.answer, result.metadata["status"])
@agent(name="assistant", model="openai/gpt-4o", tools=[agenda.as_tool()])async def assistant(ctx): """Help the user; use the agenda for appointments."""
await agenda.aclose() # or: async with remote_a2a(...) as agenda:- Construction checks, no network. Without the extra,
remote_a2a()raisesMissingA2AExtraError(anImportError: “pip install ‘astromesh-adk[a2a]’”). Only thecard_urlhost is allowed. Anhttp://card URL is rejected unlesspolicy={"allow_insecure_http": True}(local development only).name=sets the tool name (default: the host);description=overrides the generic one. - Origin. Every call goes as
Origin.AGENT, including directrun()/stream(): the ADK cannot tell whether a person typed the query, so a remote never takes it as human confirmation. This matchesremote()/bind(), which sendorigen: "agente". - Confirmations (
input_required). When the remote asks for something,run()returnsmetadata["status"] == "input_required"andanswerholds its question. The next call in the samesession_idanswers that task (reply()), and other sessions start their own. Used as a tool, the pending task is kept per parent session, and the model is told to ask the user rather than answer for them. With concurrent calls in the same session, the first one takes the pending task and resumes it, and the others start new tasks. - Output. As a runnable,
RunResult.answeris the remote’s text andmetadatahasstatus,task_id,context_id,pending,data,usage_remotoanda2a_trace. As a tool, the model sees{answer, status, task_id?, pending?}, with everything the remote wrote (itsdataincluded, as[data]lines) inside an escaped<remote-agent-output untrusted="true">block. A remote failure is an{error, status: "failed"}observation and does not break the parent run. A directrun()raisesRemoteError(RemoteUnavailableErrorwhen the egress guard blocks the destination). - Cost.
costis0unless the remote reports usage as a data part{"usage": {"cost": …, "input_tokens": …, "output_tokens": …}}, which is metadata, not answer. Used as a tool, it is recorded on the tool span asa2a.usage_remotoand is not added to the parent’s cost orby_model, because it is not one of your models. - Streaming yields
tokenevents with the remote’s text and a finaldone. A session with a pending task is answered withreply()(A2A streams only start new messages), as onetokenplusdone.