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" },
});

The delegated agent is the only SDK feature that sends document content off the page. Each run streams the document to the agent backend at baseUrl, which defaults to Revise’s hosted agent at https://agent.revise.io. To use the hosted agent in your product, email sdk@revise.io for access. Everything else in the SDK runs in the browser or on your own server.

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 });

Getting started

Guides

API reference

Configure a backend

Run a task

Stream, steer, and cancel

Custom transport

Run accounting

Visual page inspection

Suggestions by default

​Configure a backend

​Run a task

​Stream, steer, and cancel

​Custom transport

​Run accounting

​Visual page inspection

​Suggestions by default

Configure a backend

Run a task

Stream, steer, and cancel

Custom transport

Run accounting

Visual page inspection

Suggestions by default