Skip to content

AI Manager management API

Status: Current | Last reviewed: 2026-09-29

The management API lets authorized users and coding agents explore, author, validate, publish, generate, diagnose, ask questions about, and update Agent Studio agents and workflows.

Detail Value
REST base /api/v1/management
MCP endpoint /api/mcp/authoring
A2A Agent Card /.well-known/agent-card.json
A2A endpoint /api/a2a/management
Live OpenAPI /management-openapi.json
Full agent JSON Schema /api/v1/management/schemas/agent-config
Full workflow JSON Schema /api/v1/management/schemas/workflow-config
Preferred auth OAuth authorization code with S256 PKCE and Agent Studio SSO
Compatibility auth Tenant or personal Bearer tsf_* token

OAuth quick start

MCP clients normally configure only the MCP URL. An unauthenticated request receives a WWW-Authenticate challenge pointing to protected-resource metadata. Claude Code and Codex then register as public clients, open the Studio authorization page, and complete the normal SSO login and tenant-scope consent.

For a custom client:

  1. Read /.well-known/oauth-protected-resource/api/mcp/authoring and the listed authorization-server metadata.
  2. Register loopback or HTTPS redirect URIs at /oauth/register.
  3. Send the browser to /oauth/authorize with response_type=code, an S256 code_challenge, requested scopes, and resource=<origin>/api/mcp/authoring.
  4. Exchange the code at /oauth/token with the exact redirect URI, code_verifier, client_id, and resource.
  5. Rotate the returned refresh token on every refresh and discard the old one.

See Authentication for the scope table and token lifecycle.

For A2A, use the protected-resource metadata at /.well-known/oauth-protected-resource/api/a2a/management and set the OAuth resource to <origin>/api/a2a/management. Access tokens are bound to the exact MCP or A2A resource for which they were issued.

Scenario-building guidance

GET /authoring/skill returns the maintained scenario skill, reference index and content hash. Pass ?document=references/interaction-patterns.md to read a focused reference. POST /authoring/test-plan accepts declared components, features and explicit latency targets and returns required cases with status:"not_run". These routes require agents:read, call no model and create no drafts or test runs.

The MCP/A2A equivalents are get_agent_build_skill and get_scenario_test_plan. See the contracts and worked request.

Draft concurrency

Always read before writing:

GET /api/v1/management/agents/4119/draft
Authorization: Bearer <access-token>

HTTP/1.1 200 OK
ETag: "2026-07-22T12:34:56.789Z"

Send that ETag with the edited config:

PUT /api/v1/management/agents/4119/draft
Authorization: Bearer <access-token>
If-Match: "2026-07-22T12:34:56.789Z"
Content-Type: application/json

{"config": {"pipeline": []}}

Missing If-Match returns 428. A concurrent Studio save returns 412 and the current revision. Re-read and merge the intended change; never blindly retry the stale body.

Generate, ask, and update

POST /generations starts the same server-side generation capability used by the Studio UI. Poll /generations/{id} for plans, progress, questions, terminal status, and the created target_id. Submit question answers at /answers or cancel an active run at /cancel.

POST /ask uses the existing assistant runner with a separate, target-bound advisory session. Its MCP tool set cannot save drafts, even if the model asks to. The response includes a session_id; pass it on follow-up requests to retain the assistant conversation.

POST /update uses the existing editor assistant with target-bound draft-write access. It reads, edits, validates, and saves the draft but never publishes. The result includes updated, the current revision, and a session_id for follow-up edits. The target-specific agents:write or workflows:write scope is required in addition to studio-ai:run. For a newly generated target, wait until the generation is terminal before starting an update session.

The equivalent MCP and A2A operations are generate_agent, generate_workflow, get_generation, answer_generation, cancel_generation, ask_about_agent, ask_about_workflow, update_agent, and update_workflow.

A2A Agent Card

The public A2A 1.0 Agent Card at /.well-known/agent-card.json advertises the same scoped operation registry as management MCP and declares streaming support. Send SendStreamingMessage to /api/a2a/management with A2A-Version: 1.0 and a structured DataPart:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "SendStreamingMessage",
  "params": {
    "message": {
      "messageId": "client-message-1",
      "role": "ROLE_USER",
      "parts": [
        {
          "data": {
            "operation": "get_draft",
            "arguments": { "kind": "agent", "target_id": "4119" }
          }
        }
      ]
    }
  }
}

The HTTP 200 response is text/event-stream. It begins with a Task, streams artifact and working-status updates, and ends in a terminal task status. SendMessage provides the blocking/non-streaming form; set configuration.returnImmediately=true to receive the submitted Task without waiting. GetTask, ListTasks, CancelTask, and SubscribeToTask are also supported. SubscribeToTask replays durable ordered events and honors the SSE Last-Event-ID header. The same cursor is available as metadata.eventSequence on each streamed response.

The caller chooses an advertised operation and supplies its arguments for a new context. Use ask_about_* for natural-language advice without writes and update_* for natural-language, validated draft edits. After one of those turns, create a new Task with the returned contextId; that follow-up may be a bare TextPart and automatically reuses the assistant session. Neither operation publishes.

To exercise the public surface with the official A2A JavaScript SDK:

cd apps/ai-manager
TRUESERVE_A2A_TOKEN='<oauth-or-tsf-token>' npm run test:a2a-e2e

The devcontainer-only npm run test:a2a-e2e:local wrapper provisions and then deletes an ephemeral test token. Add TRUESERVE_A2A_AGENT_ID=<id> to verify a two-turn streamed assistant conversation. The explicitly mutating variant uses TRUESERVE_A2A_UPDATE_AGENT_ID=<safe-id> plus TRUESERVE_A2A_UPDATE_INSTRUCTION='<expected draft change>' and asserts that update_agent saved a new revision without publishing it.

Complete config schemas

AgentConfig and WorkflowConfig in the live OpenAPI are the full generated schemas, not generic JSON objects. In particular:

  • AgentConfig.$defs.ServiceStage contains one described if/then branch per registered (provider, service) pair. Each branch references a separate named $defs.ServiceConfig_<service-definition-id> schema containing the exact stage config properties, types, defaults, enums, and conditions.
  • The OpenAPI document promotes those same 49 definitions to individual components.schemas.ServiceConfig_* entries, so Swagger and other OpenAPI explorers show them as separately browsable models instead of anonymous conditional fragments.
  • AgentConfig.$defs.PipelineEntry documents stages, parallel groups, and swimlane groups, plus all top-level settings, output lanes, translation, resilience, transfer, lifecycle, and avatar branches.
  • WorkflowConfig.$defs.WorkflowNode contains the fully described node-type branches, alongside edges, phases, triggers, parameters, and settings.

The standalone schema URLs above are easier to load into a JSON Schema viewer or IDE. The source of truth is shared/service-definitions/schemas/{agent-config,workflow-config}.schema.json; shared/service-definitions/generate-config-schemas.ts regenerates them from the service-definition and workflow-manifest catalogs. The OpenAPI build embeds those generated artifacts directly and rebases their local $defs references.

Live OpenAPI

The generated reference below is refreshed from /management-openapi.json when the developer documentation builds.

See also