Developer guide

Configure the AI Agent

Choose the model, supply application instructions and tools, and control how the Agent accesses documents and application data.

The server host owns providers, tools and operating policy. The browser panel owns presentation and context capture. Start with the Agent integration guide for installation, transport and the complete backend example.

Provider and model

The built-in OpenAI adapter uses fetch without a provider SDK. Keep credentials on the server.

import { createOpenAIProvider } from "@onodocs/agent/openai";

const provider = createOpenAIProvider({
  apiKey: () => process.env.OPENAI_API_KEY,
  model: process.env.OPENAI_MODEL
});

Set both environment variables before starting the server, then pass provider to your AgentTurnHost.

OptionPurpose
modelModel identifier for your configured service.
apiKeyA credential string or synchronous/asynchronous credential callback.
endpointFull Responses API URL. A compatible gateway must support the same request and response format.
fetchYour fetch implementation, for application networking and instrumentation.
reasoningEffortnone, low, medium or high; defaults to low.
serviceTierauto, default, flex, priority or fast.

Use option values supported by your model and endpoint. For a different provider protocol, implement AgentProvider.respond. It receives instructions, conversation items, tool definitions, an output allowance and an abort signal; it returns text, ordered calls, continuation items and token usage.

The runner adds user messages and function_call_output items to the conversation. Your adapter translates those and prior provider output into its provider's format. Return document operations as { id, call: { target, method, args } } and application tools as { id, tool: { name, arguments } }. Preserve call IDs and report reliable usage for settlement.

Application instructions

Set AgentTurnHost.instructions to describe your product's terminology, response style and editing conventions. The runner appends tool-result guidance and a high-level API map. The built-in api_read tool reads related API members and types together when needed, without loading the complete reference into every request.

const instructions = [
  "Use concise language.",
  "Inspect the current selection before editing.",
  "Preserve the document's existing formatting.",
  "Use get_clause for approved clause wording."
].join("\n");

Pass this string to the host with the corresponding tool registered. Instructions guide the model; authorization callbacks enforce what it may do. Document contents, attachments and tool results remain untrusted data.

Additional tools

AgentTurnHost.tools adds application functions alongside the built-in document tools. Each tool supplies a name, description, JSON Schema and server callback. Only the definition is sent to the model.

import { runAgentTurn, agentEventResponse } from "@onodocs/agent/server";

const getClause = {
  name: "get_clause",
  description: "Read an approved clause by its identifier.",
  parameters: {
    type: "object",
    properties: { id: { type: "string", enum: ["payment"] } },
    required: ["id"],
    additionalProperties: false
  },
  execute(input, signal) {
    signal.throwIfAborted();
    if (!input || typeof input !== "object" || Array.isArray(input) || input.id !== "payment") {
      throw new TypeError("Unknown clause identifier.");
    }
    return { text: "Payment is due within 30 days of the invoice date." };
  }
};

const events = runAgentTurn({ ...host, provider, instructions, tools: [getClause] }, conversation, request, signal);
return agentEventResponse(events, signal);

This excerpt belongs in your authenticated server request handler. host is the configured host from the integration guide, including its document bridge and required reserve, settle and commit callbacks. conversation, request and signal come from that handler.

Callbacks return JSON or a promise of JSON. Validate arguments and authorize access inside the callback; JSON Schema describes arguments to the model and does not enforce application permissions. Pass the abort signal to I/O. The OpenAI adapter preserves supplied schemas using non-strict function calling, including optional properties.

Names must be unique, contain 1–64 ASCII letters, digits, underscores or hyphens, and avoid api_read, api_script and get_page_image. Custom providers receive definitions in ProviderRequest.tools and return the application-tool call format described above.

Tools run sequentially and share the turn's cancellation, result limits and usage accounting. Definitions count toward context size. Callback failures become tool error results, allowing the model to correct arguments or explain the failure.

Permissions and side effects

Authorize document operations through createEditorApiBridge(editor, authorizeDocumentCall), or your server bridge. Application tools execute separately: select tools for the current user and enforce data access inside their callbacks.

Document Undo covers editor changes. It does not reverse an application's database writes or external actions. Stop prevents further work and signals cancellation; completed effects can remain. The application owns any required confirmation, idempotency and recovery.

Limits and conversation history

Override selected limits by spreading defaultAgentLimits into AgentTurnHost.limits. Defaults are 4,000 message bytes, 1,000,000 context bytes, 24,000 result bytes and 1,200 output tokens per model call.

import { defaultAgentLimits } from "@onodocs/agent/server";

const limits = { ...defaultAgentLimits, calls: 12, outputTokens: 2000 };

resultPropertyCharacters separately caps each top-level result property at 4,000 serialized characters by default. Large values are truncated; tools should return only relevant fields. Setting limits: false removes turn limits, but reservation and settlement callbacks are still required.

The host supplies previous conversation.input and persists completed continuation items through commit. It controls retention, turn serialization and request deduplication. There is no automatic conversation summarization; oversized context ends the turn. Reserve usage before every model continuation and settle reported usage afterward. Keep reservations when charges are uncertain.

Context and attachments

createAgent.pageContext chooses metadata (the default), text or image. Metadata includes document counts, the visible page and selection. Text adds extracted context; image adds the current page render. pageImageDpi defaults to 96. Tools can still read authorized document content in metadata mode.

Server pageImages: true enables on-demand page-image calls when the bridge supports capture. Browser attachments configures accepted types, size, upload and optional removal callbacks; server attachments resolves session-authorized references into provider input. The host owns upload validation, storage and deletion. See data flow and attachments.

Interface

createAgent mounts in your container and accepts an editor, transport, optional transcriptUrl and onEvent callback. Use toggle, stop and dispose for visibility and lifecycle. Closing the panel preserves the displayed conversation; disposal cancels its active work.

Style the host element and inherit --onodocs-agent-height, --onodocs-color, --onodocs-toolbar-background, --onodocs-selection and --onodocs-accent. The panel uses Shadow DOM. Its title, labels and composer placeholder currently have no configuration options.

For a fully custom chat interface, consume AgentTransport and AgentEvent directly and use the same document bridge and backend. The API reference covers published exports.