RemoteAgent Class

RemoteAgent exposes the following main public API:

• new RemoteAgent({ url })
  • agent.session_collection()
  • agent.runPluginAction(input)

agent.session_collection().create_session() and agent.session_collection().get_session() return RemoteAgentSession.

Session collection

agent.session_collection() returns an AgentSessionCollection with the following methods:

• session_collection.create_session(input?)
• session_collection.get_session(sessionId)
• session_collection.list_sessions(input?)
• session_collection.archive_session({ id })
• session_collection.archive_sessions(input?)
• session_collection.clean_archive()

runPluginAction

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

await agent.runPluginAction({
  plugin: "shell",
  action: "approve",
  payload: {
    approvalId: "ap_xxx",
  },
});

For unrestricted shell approval flows, subscribe to session events and respond to tool-approval-request:

session.subscribe(async (event) => {
  if (event.type !== "tool-approval-request") return;

  const displayText = event.operation === "write"
    ? event.inputPreview || event.cmd
    : event.cmd;
  const approved = window.confirm(`${displayText}\n\n${event.reason}`);

  await agent.runPluginAction({
    plugin: "shell",
    action: approved ? "approve" : "deny",
    payload: {
      approvalId: event.approvalId,
    },
  });
});

url

The current constructor shape is:

new RemoteAgent({
  url: "http://127.0.0.1:5314/agents/repo-helper",
});

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.