> ## Documentation Index
> Fetch the complete documentation index at: https://revise.io/developer/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Delegate to the Revise agent

> Run a whole task with the Revise multi-turn 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:

```tsx theme={null}
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](#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:

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

<Note>
  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](mailto:sdk@revise.io)
  for access. Everything else in the SDK runs in the browser or on your own
  server.
</Note>

## Run a task

```ts theme={null}
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:

```ts theme={null}
await editor.tools.execute("revise_run_agent", { task });
```

## Stream, steer, and cancel

```ts theme={null}
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:

```tsx theme={null}
<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:

```tsx theme={null}
<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`](/developer/docs/developer/docs/editor-sdk/api/revise-editor) 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.

```ts theme={null}
await editor.agent.run(task, { directMode: true });
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.