Skip to main content

Agents API

Create, validate, import, export, publish, and execute agents.

📄️Diff two agent specs

Compares two agent specs and reports the semantic changes between them: workflow nodes added, removed or modified; reasonings (decision-node evaluation criteria, matched by name) added, removed or modified; nodes whose routing rules (transitions) changed; and changed top-level fields. Each side is an agent in this deployment (`agentId`) or an inline spec / export bundle (`spec`), so two different agents can be compared — for example a production agent against its development copy. Specs are normalized before comparison (ids and per-environment criteria references are neutralized), and the normalized specs are returned for stable textual diffs.

📄️Ask AI agent builder and get full reply

Converse with Docana's agent-building expert without streaming: send one message, receive the complete reply. Use it to ask design questions (node types, transitions, platform gotchas) even when authoring a spec yourself, or to delegate the build — when the builder creates or edits a spec, the response carries the persisted artifact (id, version, spec) alongside the reply. On follow-up requests pass the returned `threadId` (to continue the conversation) and `artifact.id` as `artifactId` (so the builder edits that spec instead of creating a new one). Replies can take a minute or two for complex requests; clients that can consume a stream may prefer `runAgentBuilder`.

📄️Import agent bundle

Imports an exported agent bundle (root agent plus sub-agents, evals, and routines) into an application. Use `createAgent` instead to create one new draft agent. The body is NOT a bare AgentSpec: to import a spec you authored, wrap it as `{ 'exportVersion': 1, 'agent': { 'name': '<name>', 'spec': <AgentSpec> } }`. Accepts `application/json` or `multipart/form-data` with a `file` field. Any supplied query `applicationId` must be a valid positive integer. When both valid body and query IDs are supplied, the body value wins.

📄️Execute published agent

Validates the request, schedules a background run of the published agent version and returns immediately with both the `executionId` and `assistantMessageId` handles the run will use. Output content is populated asynchronously. Body: `{ prompt: string, threadId?: string, context?: object, waitSeconds?: number }`. Poll `getAgentExecution` with the returned id for status, node outputs and the threadId; the execution row appears once the background run starts, so a brief 404 right after scheduling means 'not started yet' while a persistent one means the run failed to start. Optional bounded wait: `waitSeconds` (1-120) holds the response until the run settles or the window elapses; the response then carries `waitOutcome` (`completed`, `failed` or `timeout`) and, when the run settled, `executionStatus`. A timeout never cancels the run — keep polling `getAgentExecution` with the same `executionId`. Supports the `Idempotency-Key` header: a retry with the same key and body replays the stored ack (same executionId) instead of running the agent a second time. `waitSeconds` is a delivery preference, not part of the request identity: it is excluded from the idempotency payload hash, and replays return the stored asynchronous ack immediately without waiting.