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

# Delegating to the Revise agent

> Hand a whole task to Revise's own multi-turn agent loop.

Wiring your own loop gives you control. Sometimes you would rather hand over a
task and get the finished edits back. `revise_run_agent` delegates to Revise's
native multi-turn agent — the same loop that runs in the Revise product — which
plans, reads, and edits until the task is done.

## Configure a backend

```tsx theme={null}
<ReviseEditor
  agent={{
    baseUrl: "https://agent.example.com",
    token: await getToken(),
    model: "claude-opus-5",
    provider: "anthropic",
  }}
  initialDocuments={docs}
/>
```

Per-document configuration overrides the editor-wide default:

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

<Note>
  The agent backend is the one network dependency in the SDK, and it is
  entirely yours. The wire protocol is a small HTTP/SSE contract implemented by
  the public Go package `agentcore`, so you can run it yourself rather than
  calling Revise.
</Note>

## Running 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; // how many edits it made
result.messages;    // the conversation
result.state;       // "complete" | "error"
```

It is also callable as a tool, so a supervising model can delegate to it the
same way it calls anything else:

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

## Streaming, steering, cancelling

```ts theme={null}
useEffect(
  () =>
    editor.agent.subscribe((event) => {
      setStatus(event.status);       // human-readable progress
      setActiveTool(event.activeTool);
      setMessages(event.messages);
    }),
  [editor],
);

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

`steer()` injects guidance into a run already in flight rather than queueing a
new turn — the difference between correcting the model mid-task and waiting for
it to finish doing the wrong thing.

The same events are available as a component callback:

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

## Custom transport

To route turns through your own infrastructure — your gateway, your logging,
your model — supply a transport instead of a URL:

```tsx theme={null}
<ReviseEditor
  agent={{
    turnStream: async function* (request) {
      yield* myGateway.stream(request);
    },
    disableMetrics: true,
  }}
/>
```

The editor keeps its tool runtime, tracked changes, and review behaviour; only
the model call is yours.

## Visual page inspection

The delegated browser agent can call its internal `render_document_pages`
tool when a task requires visual QA. It renders bounded appearance contact
sheets or detailed layout diagnostics from the mounted editor canvas, so the
agent can inspect pagination, tables, images, math, headers, and footers as the
user sees them.

This is deliberately not part of `editor.tools.getDefinitions()`: that public
catalogue is the deterministic document-local contract shared with the Node
backend, while page rendering requires a mounted browser canvas. Delegate the
task with `editor.agent.run()` or `revise_run_agent`; the SDK routes the
internal render call automatically.

## Suggestions by default

Delegated runs respect the document mode: in `suggesting`, everything the agent
does arrives as tracked changes for a human to accept or reject. Pass
`directMode` in the run options to apply edits outright, and every nested tool
call in that run inherits it.

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