Admin API Overview

此内容尚不支持你的语言。

This section is for a different audience than the rest of the docs.

If you’re integrating an existing agent into your product — starting sessions, sending messages, listening for replies — see the Getting Started guide and Agents instead. That surface uses a two-tier API key / session-token auth model and assumes the agent and its workflow already exist.

This section is for building the agent-creation and workflow-editing tools themselves: a dashboard where a human designs personas, builds workflow graphs, registers tools, and tests conversations before anything goes live. Everything here is authenticated with a real user JWT (login-based), not an API key, and covers full CRUD rather than a fixed integration flow.

Agents: Full CRUD

createAgent and updateAgent are both JWT-guarded and give you complete control over an agent’s configuration — persona, use case, voice tier, and (via updateAgent) which workflow it runs.

Required fields on creation: name, personaPrompt, position, useCase (a fixed enum — INTERVIEW, SUPPORT, EDUCATION, SALES, ONBOARDING, or CUSTOM — which selects the evaluation prompt used at session end), and voiceTier (required even for text-only agents; harmless to hardcode if you’re not building voice).

A key detail for the builder UI specifically: workflowId cannot be set on createAgent — it only exists on UpdateAgentInput. The flow is always create the agent, build and publish its workflow separately, then call updateAgent to wire the two together. Standard agent/agents queries and a deleteAgent mutation round out the CRUD surface.

Workflows: A Two-and-a-Half-Step Lifecycle

This is the single most common surprise for anyone building a workflow editor: createWorkflow does not accept a graph. It only takes a name and description, and returns a workflow that starts as a completely empty graph — no nodes, no edges.

The full lifecycle is three separate calls:

createWorkflow(name, description) — creates an empty draft, returns an id.
updateWorkflow(id, nodes, edges) — saves the actual graph (as JSON) onto that draft. Both nodes and edges are optional here, so you can update either independently — this is the call your “Save” button should trigger every time the graph changes.
publishWorkflow(id) — the step that’s easy to forget entirely. A workflow does nothing until this is called, no matter how complete its graph is. Publishing flips isPublished to true and bumps version. An agent can only ever run a published workflow.

If you edit and re-save a workflow that’s already live, the agent keeps using the old published version until you call publishWorkflow again.

mutation CreateWorkflow($input: CreateWorkflowInput!) {
  createWorkflow(input: $input) {
    id
  }
}

mutation UpdateWorkflow($input: UpdateWorkflowInput!) {
  updateWorkflow(input: $input) {
    id
    nodes
    edges
  }
}

mutation PublishWorkflow($id: Int!) {
  publishWorkflow(id: $id) {
    id
    isPublished
    version
  }
}

For the node/edge JSON shape itself (node types, per-type config fields, edge label semantics), see Workflows Overview — that contract is identical whether you’re hand-authoring the graph or building a visual canvas on top of it.

Registering Tools: MCP Connectors and Custom Actions

Agents call out to external systems through two kinds of registered tools, both created via JWT-guarded mutations:

MCP Connectors (createMcpConnector) — for servers that already speak the Model Context Protocol. You give it a name, serverUrl, and apiKey; the key is swapped server-side for an opaque credential reference and is never returned again. Once registered, listMcpTools(connectorId) does a live discovery call against that server so your workflow editor can populate a tool picker.
Custom Actions (createCustomAction) — for plain REST endpoints. You give it a url, HTTP method, and optionally a bearerToken. Simpler to set up than an MCP connector, and the right default choice unless you already have a live MCP server.

Both are covered from the integration side in MCP Connectors; the registration mutations themselves only make sense from an authenticated builder UI, since only a dashboard user can create or manage them for a tenant.

Watching a Workflow Run Live

Beyond CRUD, the same JWT-authenticated session mutations used for testing (startSession, sendMessage, endSession) pair with the sessionEvents subscription to give you a live feed of what a workflow is doing turn by turn — node-by-node execution events as they happen, not just the final reply. This is the mechanism you’d use to build a “watch it run” debugging view directly in a builder UI, so an agent author can see their workflow execute against a real test conversation before publishing it. See Troubleshooting & FAQ for how to read a run’s full trace after the fact via workflowRun.nodeTrace.