RemoteAgent Class

RemoteAgent exposes the following main public API:

• new RemoteAgent({ url })
• agent.sessions
• agent.run_plugin_action(input)

agent.sessions.create() and agent.sessions.get() return RemoteAgentSession.

Sessions

agent.sessions returns an AgentSessions with the following methods:

• agent.sessions.create(input?)
• agent.sessions.get(session_id)
• agent.sessions.list(input?)
• agent.sessions.archive({ id })
• agent.sessions.archived(input?)
• agent.sessions.clean_archive()

run_plugin_action

Use run_plugin_action() when your client UI needs to call an action on the remote runtime.

await agent.run_plugin_action({
  plugin: "example",
  action: "refresh",
  payload: {
    scope: "current-session",
  },
});

Shell approvals belong to the specific remote Session, not the top-level RemoteAgent:

const interactions = await session.interactions();
await session.respond({
  interaction_id: interactions[0].request.interaction_id,
  response: { kind: "approval", decision: "approved" },
});

You can also handle a pending Interaction Part through the unified Mutation stream:

session.subscribe((mutation) => {
  if (
    mutation.variant === "part" &&
    mutation.type === "interaction" &&
    mutation.part.status === "pending"
  ) {
    render_interaction(mutation.part);
  }
});

url

The current constructor shape is:

new RemoteAgent({
  url: "http://127.0.0.1:5314",
});

not baseUrl.

url currently supports:

• http://...
• https://...
• rpc://...

Core semantics

It does not execute tasks by itself. It only connects to remote session capability.

If the local Agent is the execution shell on the server side, RemoteAgent is the paired client.