Agent Tool Integration

Quick path: new to the API? Go from an API key to your first successful call in the Quickstart (~5 minutes), then come back here to register SuperDocs as an agent tool. If your product has an existing AI agent (built with OpenAI function-calling, Anthropic tool_use, LangChain, LlamaIndex, or a custom framework) that needs to edit documents, the right integration shape is to register SuperDocs as a tool the agent can call — not to build a separate UI around SuperDocs.

Your agent can pick model_tier per call based on user intent. A simple “fix typo” call can use core; a contract-clause edit can switch to max mid-conversation. Add model_tier and thinking_depth to your tool’s parameter schema and let the agent reason about which tier fits the current task. See Model Selection for the full matrix.

This guide covers the pattern + working snippets for the five most common agent frameworks, plus a generic JSON-schema definition you can adapt to any framework that supports tool-calling.

Why this shape is different from a UI integration

In a typical SuperDocs UI integration, a human types in a chat panel, the chat sends a message to SuperDocs, and SuperDocs returns proposed edits the human reviews. The customer-facing app is the consumer of SuperDocs. In an agent-tool integration, your AI agent is the consumer. The agent decides — based on its own reasoning, the user’s query, and the conversation context — that it needs to edit a document. It invokes SuperDocs as a tool, receives proposed changes as structured data, and either approves them itself (auto-decide), surfaces them through your existing UI for the user to review, or sends them out-of-band (Slack, email). The integration is server-side, the SuperDocs sk_ key lives next to your other model API keys, and there is no SuperDocs-specific UI to build — your agent’s existing UI is where the result appears.

The pattern, in 4 steps

Define the SuperDocs tool in your agent’s tool registry. The two required parameters are message (the natural-language instruction for the AI) and session_id (a string that ties multiple turns together). document_html (the HTML the agent wants edited) is optional — send it on the first turn, then omit it: the server persists document state by session_id across turns, so resending the full HTML every turn just wastes tokens.
Implement the tool function. Call POST /v1/chat with the three parameters plus your chosen approval_mode. Return the response back to the agent — either as the parsed proposed changes (for ask_every_time) or as the final updated HTML (for approve_all).
Decide approval shape. Choose between approve_all (your agent’s reasoning is the approval — fastest), ask_every_time (the agent reviews each proposed change individually before deciding), or surface to a human through your UI.
Persist the result. The agent receives the updated HTML and writes it back to wherever your documents live.

That’s the whole loop. The snippets below are the same loop in five different framework idioms.

Generic JSON-schema tool definition

Every framework that supports tool-calling accepts a JSON-schema tool definition. Use this as the canonical version and adapt for your framework:

{
  "name": "edit_document",
  "description": "Edit a document with AI by sending the document HTML and a natural-language instruction. Returns the updated HTML. Use this when the user asks to modify, rewrite, expand, summarize, translate, or improve any document.",
  "parameters": {
    "type": "object",
    "properties": {
      "message": {
        "type": "string",
        "description": "The natural-language instruction for what to do to the document. Examples: 'rewrite the introduction in plain English', 'add a section about pricing', 'tighten the conclusion to one paragraph', 'translate to French'."
      },
      "session_id": {
        "type": "string",
        "description": "A string that ties multiple turns together. Use the same session_id across multiple tool calls if you want the AI to remember earlier edits in the same conversation."
      },
      "document_html": {
        "type": "string",
        "description": "The current HTML of the document to be edited, as a complete HTML string. OMIT this once the session already holds the document — the server persists document state across turns by `session_id`, so resending the full HTML every turn just burns tokens. Send it on the first turn (or when you're switching the session to a new document). The response includes `data-chunk-id` attributes — preserve them on the next call so SuperDocs can target previously-edited sections precisely."
      },
      "approval_mode": {
        "type": "string",
        "enum": ["approve_all", "ask_every_time"],
        "description": "Whether to apply all proposed changes automatically (approve_all — best for autonomous agents) or pause for review on each change (ask_every_time — best when a human is in the loop)."
      }
    },
    "required": ["message", "session_id"]
  }
}

OpenAI function-calling (Python)

import os, httpx, json
from openai import OpenAI

client = OpenAI()
SUPERDOCS_KEY = os.environ["SUPERDOCS_API_KEY"]

# 1. Tool definition — registered when you call the model
edit_document_tool = {
    "type": "function",
    "function": {
        "name": "edit_document",
        "description": "Edit a document with AI. Returns the updated HTML.",
        "parameters": {
            "type": "object",
            "properties": {
                "message": {"type": "string", "description": "The instruction for what to do to the document."},
                "session_id": {"type": "string", "description": "Ties multi-turn edits together."},
                "document_html": {"type": "string", "description": "Current HTML to edit. Omit once the session already holds the document — state persists by session_id."},
                "approval_mode": {"type": "string", "enum": ["approve_all", "ask_every_time"]},
            },
            "required": ["message", "session_id"],
        },
    },
}

# 2. Tool function — called when the model invokes the tool
def edit_document(message: str, session_id: str, document_html: str, approval_mode: str = "approve_all") -> dict:
    with httpx.Client(headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"}, timeout=300) as c:
        r = c.post("https://api.superdocs.app/v1/chat", json={
            "message": message,
            "session_id": session_id,
            "document_html": document_html,
            "approval_mode": approval_mode,
        })
        r.raise_for_status()
        result = r.json()
    return {
        "updated_html": result["document_changes"]["updated_html"],
        "ai_response": result.get("response", ""),
        "usage": result.get("usage", {}),
    }

# 3. Standard agent loop — the model decides when to call edit_document
def run_agent(user_message: str, document_html: str, session_id: str):
    messages = [
        {"role": "system", "content": "You are an SOP-editor assistant. When the user asks to modify a document, use the edit_document tool."},
        {"role": "user", "content": f"{user_message}\n\nCurrent document HTML available — call edit_document with session_id={session_id}."},
    ]
    response = client.chat.completions.create(
        model="gpt-5",  # Your model choice — SuperDocs is provider-agnostic
        messages=messages,
        tools=[edit_document_tool],
    )
    msg = response.choices[0].message
    if msg.tool_calls:
        for call in msg.tool_calls:
            args = json.loads(call.function.arguments)
            args["document_html"] = args.get("document_html") or document_html
            result = edit_document(**args)
            # Append result back to the conversation if you want a multi-turn flow
            messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
            return result
    return {"ai_response": msg.content}

Anthropic `tool_use` (Python)

import os, httpx, anthropic

client = anthropic.Anthropic()
SUPERDOCS_KEY = os.environ["SUPERDOCS_API_KEY"]

edit_document_tool = {
    "name": "edit_document",
    "description": "Edit a document with AI. Returns the updated HTML.",
    "input_schema": {
        "type": "object",
        "properties": {
            "message": {"type": "string"},
            "session_id": {"type": "string"},
            "document_html": {"type": "string", "description": "Omit once the session already holds the document — state persists by session_id."},
            "approval_mode": {"type": "string", "enum": ["approve_all", "ask_every_time"]},
        },
        "required": ["message", "session_id"],
    },
}

def edit_document(message, session_id, document_html, approval_mode="approve_all"):
    with httpx.Client(headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"}, timeout=300) as c:
        r = c.post("https://api.superdocs.app/v1/chat", json={
            "message": message, "session_id": session_id,
            "document_html": document_html, "approval_mode": approval_mode,
        })
        r.raise_for_status()
        return r.json()

def run_agent(user_message, document_html, session_id):
    messages = [{"role": "user", "content": f"{user_message} (session_id={session_id})\n\nDocument HTML: {document_html[:500]}..."}]
    response = client.messages.create(
        model="claude-opus-4-5",  # Your model choice
        max_tokens=4096,
        system="You are an SOP-editor assistant. Call edit_document when the user asks to modify a document.",
        tools=[edit_document_tool],
        messages=messages,
    )
    for block in response.content:
        if block.type == "tool_use" and block.name == "edit_document":
            args = block.input
            args["document_html"] = args.get("document_html") or document_html
            result = edit_document(**args)
            return result["document_changes"]["updated_html"]
    return None

LangChain `Tool` (Python)

import os, httpx
from langchain.tools import tool
from langchain.agents import create_react_agent
from langchain_openai import ChatOpenAI

SUPERDOCS_KEY = os.environ["SUPERDOCS_API_KEY"]

@tool
def edit_document(message: str, session_id: str, document_html: str, approval_mode: str = "approve_all") -> str:
    """Edit a document with AI. Returns the updated HTML.

    Args:
        message: The natural-language instruction for what to do to the document.
        session_id: A string that ties multiple turns together.
        document_html: The current HTML of the document to be edited.
        approval_mode: 'approve_all' to auto-apply, 'ask_every_time' to pause per change.
    """
    with httpx.Client(headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"}, timeout=300) as c:
        r = c.post("https://api.superdocs.app/v1/chat", json={
            "message": message, "session_id": session_id,
            "document_html": document_html, "approval_mode": approval_mode,
        })
        r.raise_for_status()
        return r.json()["document_changes"]["updated_html"]

# Wire into your agent
llm = ChatOpenAI(model="gpt-5")
tools = [edit_document]  # Plus whatever other tools your agent has
agent = create_react_agent(llm, tools, prompt="...")

LlamaIndex `FunctionTool` (Python)

import os, httpx
from llama_index.core.tools import FunctionTool
from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI

SUPERDOCS_KEY = os.environ["SUPERDOCS_API_KEY"]

def edit_document(message: str, session_id: str, document_html: str, approval_mode: str = "approve_all") -> str:
    """Edit a document with AI. Returns the updated HTML."""
    with httpx.Client(headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"}, timeout=300) as c:
        r = c.post("https://api.superdocs.app/v1/chat", json={
            "message": message, "session_id": session_id,
            "document_html": document_html, "approval_mode": approval_mode,
        })
        r.raise_for_status()
        return r.json()["document_changes"]["updated_html"]

edit_tool = FunctionTool.from_defaults(fn=edit_document, name="edit_document",
                                       description="Edit a document with AI. Returns updated HTML.")

agent = ReActAgent.from_tools([edit_tool], llm=OpenAI(model="gpt-5"), verbose=True)

TypeScript / Vercel AI SDK

import { tool } from "ai";
import { z } from "zod";

const SUPERDOCS_KEY = process.env.SUPERDOCS_API_KEY!;

export const editDocument = tool({
  description: "Edit a document with AI. Returns the updated HTML.",
  parameters: z.object({
    message: z.string().describe("The instruction for what to do to the document."),
    session_id: z.string().describe("Ties multi-turn edits together."),
    document_html: z.string().describe("Current HTML to edit."),
    approval_mode: z.enum(["approve_all", "ask_every_time"]).default("approve_all"),
  }),
  execute: async ({ message, session_id, document_html, approval_mode }) => {
    const res = await fetch("https://api.superdocs.app/v1/chat", {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${SUPERDOCS_KEY}`,
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ message, session_id, document_html, approval_mode }),
    });
    if (!res.ok) throw new Error(`SuperDocs ${res.status}`);
    const data = await res.json();
    return {
      updated_html: data.document_changes.updated_html,
      ai_response: data.response,
    };
  },
});

// Wire into your agent's tool registry alongside your other tools

Approval modes — choose based on who decides

`approve_all` — your agent’s reasoning is the approval

The simplest pattern. Pass approval_mode: "approve_all" and SuperDocs returns the final updated HTML in one call. Use this when your agent is autonomous and you trust it to make the right call. Most appropriate for:

Backend AI agents processing a queue without human oversight.
Agents whose user already approved the high-level intent (e.g., “rewrite all sections in plain English”) and doesn’t need per-change review.
Server-to-server workflows.

`ask_every_time` — your agent reviews each proposed change

Pass approval_mode: "ask_every_time" and SuperDocs returns the turn’s proposed changes via SSE. The whole turn arrives as one proposed_change_batch event whose changes[] array holds every proposed change (a single-change turn arrives as a one-element array). Your agent reads that event (parse event.data then JSON.parse the content field again — see the SSE Streaming guide for the double-parse warning), loops over changes[] deciding whether to approve each based on its own reasoning, and POSTs to /v1/chat/{session_id}/approve to accept or reject. (You may also register a proposed_change listener defensively for forward-compatibility, but it never fires today — build your review loop on proposed_change_batch.) Use this when:

Your agent has higher reasoning capability than SuperDocs’ edit suggestions and wants to filter them.
The user is reviewing the agent’s overall plan but trusts the agent to filter individual edits.
You want an audit log of every accepted vs rejected change for compliance.

The decision flow inside the agent looks like:

# Pseudocode — adapt to your framework
# Each batch is the whole turn: parse the proposed_change_batch event, then
# loop over its changes[] array (one element for a single-change turn).
for batch in stream_proposed_change_batches(job_id, session_id):
    decisions = []
    for change in batch["changes"]:
        # The agent reasons about whether to approve each change
        decision = await agent.reason(
            f"SuperDocs proposed: {change['ai_explanation']}\n"
            f"Old: {change['old_html']}\n"
            f"New: {change['new_html']}\n"
            "Approve or deny?"
        )
        decisions.append({"change_id": change["change_id"], "approved": decision == "approve"})
    httpx.post(
        f"https://api.superdocs.app/v1/chat/{session_id}/approve",
        headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"},
        json={"job_id": job_id, "approved": True, "changes": decisions},
    )

Surface to a human through your UI

If your agent is in a chat with a human and SuperDocs proposes an edit, your agent can stop, surface the proposed change to the human via your existing chat thread (as a card, a button group, an inline question — whatever your UI does), wait for the human’s decision, and then POST the decision back to SuperDocs. This pattern keeps your AI agent in control of what gets surfaced and when, but defers the binary approve/deny decision to the human. The agent’s UI is the only UI involved — there’s no SuperDocs-specific UI.

Document HTML round-trip — same rule as everywhere else

The data-chunk-id attributes that SuperDocs adds to block-level elements must round-trip cleanly when you send the HTML back on the next call. If your agent stores the HTML in a database, file, or in-memory variable between calls, those attributes must survive the storage cycle. Most string-based storage preserves them automatically; if you parse the HTML through a library that strips unknown attributes, you’ll break the round-trip silently. If you’re piping the HTML through a rich-text editor at any point in your agent’s UI, see the Editor Integration guide for editor-specific preservation patterns.

Multi-document sessions for agents

A session can hold several open documents. Your agent targets one explicitly by passing document_id on chat/chat_async (ids come from the list_session_documents tool / GET /v1/sessions/{id}/documents), names it in the message (“update the invoice”), or omits both to hit the focused document. Agents that juggle related files (a contract + its amendment, a report + its data appendix) should keep them in ONE session and let the AI read across them, instead of copying content between sessions. See the Multi-Document guide.

Letting your agent undo a step

If your agent decides — mid-workflow — that a previous edit was wrong, it can rewind the session to before the user message that triggered the bad edit instead of trying to patch the result forward. Call POST /v1/sessions/{session_id}/revert with the turn_index of the user message you want to undo. SuperDocs returns the document state from before that turn plus the original message text, the agent can rewrite the instruction more clearly, and the session continues from the rewind point. The original conversation is preserved for audit but hidden from active reads. Concrete shape — register revert as a second tool alongside edit_document:

def revert_session(session_id: str, turn_index: int) -> dict:
    with httpx.Client(headers={"Authorization": f"Bearer {SUPERDOCS_KEY}"}, timeout=30) as c:
        r = c.post(f"https://api.superdocs.app/v1/sessions/{session_id}/revert",
                   json={"turn_index": turn_index})
        r.raise_for_status()
        return r.json()  # {compose_text, reverted_to_turn, document_state, editor_action, archived_turn_count}

The agent reasons “this edit went wrong, let me try a different prompt” and chains revert_session → edit_document with the corrected instruction. Returns 409 if a chat job is still in flight on the session — wait for it to settle first. See the full revert contract in Sessions → Revert a session to a previous message.

Choosing between sync `/v1/chat` and async `/v1/chat/async`

Most agent-tool integrations should use sync /v1/chat. It’s a simpler integration (one call, one response) and matches the standard tool-call shape (function in, JSON out, agent reasons over the result). Use async /v1/chat/async + the SSE stream when:

Your agent has a UI that wants to show streaming progress events to the user as the AI works.
The document is very large and you want to fail fast on auth errors before committing to a long edit.
You want to use ask_every_time and react to each proposed change in real time.

For everything else, sync is enough.

Stuck?

If your agent framework isn’t covered here or the tool-calling pattern doesn’t map cleanly to your setup, email hello@superdocs.app or book a 15-minute integration call at cal.com/superdocs. We’ll talk through the pattern and add a snippet to this guide for the next person.

Server Integration — if your agent is one of several services in a backend, the same patterns apply more broadly.
Human-in-the-Loop — if your agent surfaces proposed changes to a human via your UI, the rendering patterns there work for chat-thread cards too.
SSE Streaming — if you choose ask_every_time and need to consume the turn’s proposed_change_batch event.
Async Jobs — if you want polling instead of SSE.
Integration Starter Prompt — paste this into your coding agent to wire all the above up automatically.

Getting Started

Capabilities

Account & Billing

Core Concepts

Guides

MCP Integration

Errors & Limits

Code Examples

Agent Tool Integration

Agent Tool Integration

Why this shape is different from a UI integration

The pattern, in 4 steps

Generic JSON-schema tool definition

OpenAI function-calling (Python)

Anthropic `tool_use` (Python)

LangChain `Tool` (Python)

LlamaIndex `FunctionTool` (Python)

TypeScript / Vercel AI SDK

Approval modes — choose based on who decides

`approve_all` — your agent’s reasoning is the approval

`ask_every_time` — your agent reviews each proposed change

Surface to a human through your UI

Document HTML round-trip — same rule as everywhere else

Multi-document sessions for agents

Letting your agent undo a step

Choosing between sync `/v1/chat` and async `/v1/chat/async`

Stuck?

​Agent Tool Integration

​Why this shape is different from a UI integration

​The pattern, in 4 steps

​Generic JSON-schema tool definition

​OpenAI function-calling (Python)

​Anthropic tool_use (Python)

​LangChain Tool (Python)

​LlamaIndex FunctionTool (Python)

​TypeScript / Vercel AI SDK

​Approval modes — choose based on who decides

​approve_all — your agent’s reasoning is the approval

​ask_every_time — your agent reviews each proposed change

​Surface to a human through your UI

​Document HTML round-trip — same rule as everywhere else

​Multi-document sessions for agents

​Letting your agent undo a step

​Choosing between sync /v1/chat and async /v1/chat/async

​Stuck?

​Related guides

Agent Tool Integration

Why this shape is different from a UI integration

The pattern, in 4 steps

Generic JSON-schema tool definition

OpenAI function-calling (Python)

Anthropic `tool_use` (Python)

LangChain `Tool` (Python)

LlamaIndex `FunctionTool` (Python)

TypeScript / Vercel AI SDK

Approval modes — choose based on who decides

`approve_all` — your agent’s reasoning is the approval

`ask_every_time` — your agent reviews each proposed change

Surface to a human through your UI

Document HTML round-trip — same rule as everywhere else

Multi-document sessions for agents

Letting your agent undo a step

Choosing between sync `/v1/chat` and async `/v1/chat/async`

Stuck?

Related guides