Delegate to the Revise agent

revise_run_agent sends a task to the Revise multi-turn agent, the same agent that runs in the Revise product. It plans, reads, and edits until the task is done, then returns the result.

Configure a backend#

Tell the editor where turns go. Fetch any token before rendering, for example in a loader or a parent component:

export function Workspace({ token, docs }: { token: string; docs: ReviseDocumentInput[] }) {
  return (
    <ReviseEditor
      agent={{
        baseUrl: "https://agent.example.com",
        token,
        model: "claude-opus-5-5",
        provider: "anthropic",
      }}
      initialDocuments={docs}
    />
  );
}

The editor needs one of three transports: turnStream for your own model (see custom transport), baseUrl for your own agent backend, or token for Revise's hosted agent. With none of them, agent.run() rejects with an AgentNotConfiguredError (code: "agent_not_configured") and nothing leaves the page. The revise_run_agent tool returns the same code, and getToolDefinitions() leaves it out.

Per-document configuration overrides the editor-wide default:

await editor.documents.open({
  id: "exhibit-a",
  source: file,
  agent: { model: "claude-sonnet-5-5" },
});

Run a task#

const result = await editor.agent.run(
  "Make the liability cap mutual and raise it to two years of fees.",
);

result.actionCount; // number of edits
result.messages;    // the conversation
result.state;       // "complete" | "error"

It is also available as a tool, so a supervising model can call it:

await editor.tools.execute("revise_run_agent", { task });

Stream, steer, and cancel#

useEffect(
  () =>
    editor.agent.subscribe((event) => {
      setStatus(event.status);       // progress text
      setActiveTool(event.activeTool);
      setMessages(event.messages);
    }),
  [editor],
);

editor.agent.steer("Keep the defined terms as they are.");
editor.agent.cancel();

steer() adds guidance to a run in progress. It does not queue a new turn.

The same events are available as a component callback:

<ReviseEditor
  onAgentEvent={(documentId, event) => setStatus(documentId, event.status)}
/>

Custom transport#

To send turns through your own gateway, logging, or model, pass a transport instead of a URL:

<ReviseEditor
  agent={{
    turnStream: async function* (request) {
      yield* myGateway.stream(request);
    },
  }}
/>

The editor keeps its tool runtime, tracked changes, and review behavior. Only the model call changes. A new turnStream takes effect on the next run, so an inline generator like this one is fine: the open document is never reloaded.

Run accounting#

When a run finishes, the editor tells the agent backend at baseUrl, with a request to /api/v1/chat/metrics/complete, so the backend can settle the run's cost. It goes only to the backend you configured. turnStream skips it, since there is no backend to tell, and disableMetrics: true turns it off for a backend that does not need it. It is separate from the editor's telemetry ping.

Visual page inspection#

The delegated agent can call an internal render_document_pages tool to check layout visually. It renders page contact sheets or layout diagnostics from the mounted editor canvas. The agent sees pagination, tables, images, math, headers, and footers as the user sees them.

render_document_pages is not in editor.tools.getDefinitions(). That catalog is shared with the Node backend, and page rendering needs a mounted browser canvas. Run the task with editor.agent.run() or revise_run_agent, and the SDK routes the render call.

Suggestions by default#

Delegated runs follow the document mode. In suggesting, every agent edit is a tracked change for a person to accept or reject. Pass directMode in the run options to apply edits directly. Every tool call in that run inherits it.

await editor.agent.run(task, { directMode: true });