Inflow.aiDocs

Optional technical reference. This material is for developers, integration specialists and platform administrators. For the consultant lesson, read the practical guide.

Preserved from source baseline d4587c7c0e073e58c2d430342f65ac55dd701bf4; source/static examples retain their stated scope. They are not new runtime verification or required consultant setup steps.

Current product update — 9 November 2026. App Chat is now an implemented optional App Shell feature, distinct from the Studio Ask Inflow conversations described below. Configure it on the App Shell itself and explicitly connect approved sources and actions; Studio conversation context or generic Agent Memory does not configure App Chat. The preserved reference to “future floating” App Chat describes the historical state, not current availability. See the current App Shell and App Chat lesson. The preserved text below is not runtime evidence for it.

Current product update — 10 November 2026. Saved Ask Inflow conversations now use bounded recent history, automatic compaction and a structured proposal ledger to support multi-turn follow-ups. This source-backed description is not runtime acceptance; see the current consultant walkthrough and context limits.

Current product update — 11 November 2026 (SPEC-535). Interactive Ask Inflow uses the bounded platform-mcp agent loop (StudioAgentLoop; platform.agent.loop.enabled defaults to true). StudioAgentToolPolicy classifies calls as READ_ONLY, AUTO_ELIGIBLE or CONFIRM_ALWAYS: read-only calls run in both supervised and Auto modes; eligible calls run automatically only when effective Auto Mode is on, and otherwise pause for human confirmation; CONFIRM_ALWAYS calls always require explicit confirmation. Mutating proposals bind a proposalId to an argumentsDigest. Effective Auto Mode requires a true request flag and enabled server policy (platform.agent.auto-mode.enabled defaults to false); the effective-mode check requires request opt-in, the administrator switch, an active durable conversation and a qualified model profile. It is not a permission grant. The loop also records bounded step outcomes, permits one active turn per saved conversation and supports outcome reconciliation. The Studio's Stop viewing button stops the local stream and sends a best-effort request to cancel the server turn. Cancellation is observed at a loop boundary; it cannot undo a step already completed, and a turn can finish with partial work. These defaults and source behaviors do not verify any particular environment's runtime configuration. The Studio switch has a separate browser default: without an explicit stored actor/workspace choice, AgentRail follows the current server Auto Mode availability setting. A server setting of true can therefore preselect Auto Mode in a fresh browser. Check the actual switch and effective turn mode; do not describe every browser as initially off or treat the generated request flag as proof of a separate explicit human opt-in. The 19 November 2026 consultant walkthrough records the local switch being set off before its explanation-only turn.

Current product update — 12 November 2026 (SCRUM-4476). A workflow response includes at most ten recent saved specification-document history links, with total/returned/limit/truncated metadata and a pointer to the owning manage_build_specs history reader. It returns recorded links, not the full history or frozen render inputs; use the owning reader for a specific filename and page. This response bound does not shorten or delete persisted history, change permissions, establish a current document readback, or approve a build. See BlueprintTools.documentHistoryLinks and the bounded-response contract.

Current product update — 16 November 2026 (SPEC-538, SCRUM-5207–SCRUM-5211).

  • Sibling proposal batching, Skip dismissal, and server-enforced continuation (FR-001–FR-004, FR-019): In Supervised Mode, StudioAgentLoop batches up to 6 independent non-rescoping proposals from the allowlist (create_screen, create_screen_from_pattern, create_rule, refine_screen, refine_rule) targeting distinct keys when prerequisites exist, while isolating create_workspace/select_workspace and dependent mutations as single proposals. POST /api/studio-agent/proposals/{proposalId}/dismiss records DB status SUPERSEDED (honoring 000439 CHECK) with TOOL_SUMMARY outcomeStatus = DISMISSED and returns remainingPendingProposals and batchReadyToContinue. DefaultStudioConversationService enforces and audits continuationOrigin (USER | POST_CONFIRMATION | AUTO_CHECKPOINT | GOAL_RESUME), capping consecutive non-USER hops at <= 8 (409 STUDIO_CONTINUATION_HOP_LIMIT_REACHED on overflow).
  • Snapshot proposal filtering and shared-viewer non-actionability (FR-012, FR-018): StudioConversationSnapshot.proposals projects chronologically ordered (createdAt ASC, max 200) proposals filtered through StudioArtifactReadPort to the active workspace, non-redacted visible messages, and caller-readable targets. Non-owner EXPLICIT_SHARED viewers receive status = SHARED_VIEW_ONLY (actionableByCaller: false) on PENDING rows while preserving settled CONSUMED/SUPERSEDED/EXPIRED + outcomeStatus history; Studio never renders Confirm & run, Revise or Skip for non-owners or unauthorized targets.
  • Caller-scoped dry-run validation, reference read cache, and untrusted discovery boundary (FR-007–FR-009): Before registering a PENDING proposal, StudioAgentLoop calls McpStudioAgentToolService.validateProposalCandidate under the caller's effective access (returning neutral TARGET_NOT_AVAILABLE issues without leaking unreadable targets). Static reference reads (get_platform_catalog, search_platform_api) are cached per (conversationId, actorId, workspaceId, toolName, argumentsDigest) (max 16, 15m TTL); live workspace, record, readiness and observation reads (describe_workspace_entity, get_build_status, observe_*, manage_records) always execute live. Prior-turn discoveries (<prior_turn_discoveries data-only="true">) accept only allowlisted catalog section names and grammar-validated entityType:key tokens (excluding free-text search strings), are escaped via BOUNDARY_TAG_PATTERN, and sit inside the untrusted data boundary.
  • Hoisted workflow task-routing fallback (FR-010): McpStudioAgentToolService hoists process-directory and workspace assignment-reach checks to once per lifecycle operation (never exposing member identities or counts) and falls back to admitted workspace role: admin with singleAdminWorkspaceAssignmentFallback: true and assignmentGovernanceNote when default operational or manager roles have zero admitted candidates in the workspace at authoring time.

Current product update — 17 November 2026 (SPEC-540, SCRUM-5272–SCRUM-5277).

  • Null-safe gateway & protocol map snapshots (SCRUM-5272): AiGatewayResponse, AiTaskGatewayResponse and StudioAgentModelProtocol.StepModelMetadata store structuredOutput and usage as unmodifiable maps that omit null keys while tolerating null JSON values without throwing NullPointerException.
  • Compact <additional_tools> schemas & operation-declaration sync (SCRUM-5273, SCRUM-5274): StudioAgentPromptAssembler includes compact inputSchema definitions (retaining operation enums and bounded parameter descriptions while stripping server-owned confirm) on <additional_tools> entries, and McpOperationDeclarations aligns AdminIdentityController#users(String), DataModelController#publicationImpactCandidate, TaskController#release, document-generation review routes and all registered authoring MCP tools.
  • Draft-only publish: false control & checkpoint/rail guards (SCRUM-5275–SCRUM-5277): McpStudioAgentToolService honors explicit publish: false on create_screen, create_screen_from_pattern, create_rule, create_lifecycle and update_lifecycle by leaving the artifact in DRAFT state (published: false). AgentRail.tsx requires at least one succeeded mutating step before queuing AUTO_CHECKPOINT continuations (using CONTINUE_CHECKPOINT_MESSAGE), clears snapshotProposals on new/switched conversations, and scrolls .agent-body on active CONVERSATION updates.

For the consultant walkthrough and current limits, see Example 8: continue a long model-and-form discussion. The saved-conversation summary is distinct from an accepted memory, does not grant workspace access, and does not prove that an earlier proposal ran.

Workspace-index compaction, exact-entity inspection and validation locations — 11 November 2026

Large Studio Agent workspace snapshots are serialized within a 12,000-character context envelope. The prompt assembler progressively compacts the inventory to fit: it first removes record-type field details; next removes bulky blueprint/practice-guide sections; then drops row counts and names from record types and removes connected-system and cabinet data; then replaces secondary artifact arrays with counts; and finally slims model entries to keys and record-type keys or trims entries. The terminal fallback retains a truncation notice and directs the agent to describe_workspace_entity. This is prompt-context compaction; it does not delete workspace artifacts. See StudioAgentPromptAssembler and its compactWorkspaceStateJson degradation path.

describe_workspace_entity is a read-only MCP tool for one exact entity in the selected, admitted workspace. It accepts entityType and key; optional arguments are modelKey (record-type disambiguation), section, limit and offset. Types are data_model, record_type, screen, rule, lifecycle and case_file. The default page size is 50 and the limit is clamped to 1–200; offset is zero-based. Available sections are type-specific: data models expose recordTypes, relationships and publications; record types expose fields and relationships; screens expose body, controls, layout, dataSources, data, inputs, actions, settings, onSubmit and onLoad; rules expose inputs, outputs and body; lifecycles expose states and transitions; case files expose variables. Collection replies expose total counts. Explicit requests for paged array sections include their effective limit and offset; object-valued sections return the section value directly. Some unsectioned secondary lists include a total but omit page metadata and return from offset zero. Request a named section when paging a list. Section names are canonicalized case-insensitively, but keys are not guessed by the tool.

Example MCP arguments for inspecting a page of a record type's fields:

{
  "entityType": "record_type",
  "key": "leave_request",
  "modelKey": "people_ops",
  "section": "fields",
  "limit": 50,
  "offset": 0
}

The tool checks authentication and workspace admission before catalog lookup. It rejects unsupported entity types, unsafe keys and invalid type/section pairs. A missing or cross-workspace key returns the neutral WORKSPACE_ENTITY_NOT_FOUND shape. Some unsuccessful upstream reads, including non-200 4xx responses or empty bodies, can resolve to that same neutral result so the reply does not reveal whether an inaccessible entity exists. Dispatcher-not-executed responses, upstream 5xx/null-status responses and malformed payloads share the WORKSPACE_ENTITY_UNAVAILABLE refusal; response truncation and bounded scan exhaustion have their own refusal codes. None should be described as an empty business result. When a published record type's count is available, the tool may perform an authorized page=0&size=1 read (with a bounded-endpoint fallback) and copy only a returned numeric total into rowCount; it does not put the returned record row in the entity-description payload. This is a bounded read, while the reported total may be exact. See WorkspaceEntityDescriptionTools, admission and argument checks, count probe, and tool registration/schema.

Screen-tool validation replies retain their original issues and additionally expose normalized issueEnvelopes, with aggregate issueCount, errorCount and warningCount. The envelope includes assetType, code, source severity, a typed locator, optional secondaryLocator, message and optional suggestion. Screen locations are RFC 6901 JSON Pointers, such as /body/0/children/0/dataSource; downstream consumers should preserve the locator rather than reconstructing it from control labels. This adapter changes presentation only: it does not add validation logic, elevate a warning to an error or prove the screen is published. See ValidationIssueEnvelope, normalization, and the screen validation reply.

Current loop rollout, budgets and recovery — 11 November 2026

The current source default for platform.agent.loop.enabled is true. The separate platform.agent.enabled master switch and the provider/model configuration still govern whether Ask Inflow is available. Setting the loop property to false makes the service return an unavailable response; it does not restore the retired single-shot heuristic path. platform.agent.auto-mode.enabled defaults to false. A requested Auto Mode is effective only when the administrator enables it, durable conversation history is available, and the selected model profile is qualified. Auto Mode is not an authorization grant and does not bypass a tool policy or a human confirmation boundary. A source default is not proof that a particular environment has these settings, a qualified model, or completed release acceptance.

The source defaults for the principal loop limits are platform.agent.max-agent-steps=8, platform.agent.max-agent-auto-mode-steps=12, and platform.agent.turn-wall-clock-millis=85000. These cap ordinary/Auto Mode iteration counts and the whole turn. The same StudioAgentProperties source defines a 60-second model-step timeout (platform.agent.per-step-model-timeout-millis=60000, independent of the legacy platform.agent.max-latency-millis key), a 25-second tool timeout, 16,384 output tokens per model call and 500,000 total tokens per turn. Use the application's canonical configuration path and owner-approved rollout to change them; the examples here explain defaults, not an instruction to change a live environment.

Session-only blueprint planning and confirmation boundary — 12 November 2026

In an interactive Studio session, plan_application can propose a non-empty blueprint for that session. When the request contains no applicationKey, buildId, expectedRevision or expectedFence, the policy classifies the non-empty blueprint as AUTO_ELIGIBLE; revise_blueprint similarly allows a non-empty session-only mergePatch without durable build identifiers. Empty or malformed payloads and requests targeting durable builds fail closed to CONFIRM_ALWAYS. Auto-eligible means the step can run automatically only when effective Auto Mode is on; otherwise the loop asks for confirmation. It does not mean that a blueprint has been saved as a durable application or that it has been built or published.

For example, a consultant may ask Ask Inflow to outline a fictional leave-request application and review the session proposal. Any request that supplies a durable application/build target or advances construction remains behind the applicable explicit confirmation and native authorization gates. Check the proposal and intended workspace before approving a durable action.

Sources: classifySessionBlueprintPlan and classifySessionBlueprintRevise, policy tier selection, and blueprint authoring tools.

Model-selected authoring and hydrated MCP sessions — 11 November 2026

SCRUM-5052 removes the legacy request-text classifiers and argument-rewriting path. In the bounded loop, Ask Inflow selects a catalog tool and arguments; the service validates the tool schema, authorization and policy before execution. It no longer silently changes a create_screen request into create_screen_from_pattern, invents a suffixed retry after a key conflict, provisions unrelated prerequisites to make a tool call pass, retries lifecycle creation as an update, or applies demo data automatically. A refusal, missing prerequisite or validation issue is an actual result to read and resolve; it is not permission to substitute a different tool or target. Explicitly confirmed, same-domain post-create convenience work remains part of the operation when its proposal describes it.

MCP authoring sessions now hydrate relevant persisted workspace assets when a session is created and when a tool reports an unmet precondition (SCRUM-5053). The session cache is principal- and workspace-scoped; a cache miss or precondition response is not proof that an object is absent or accessible. The MCP tool still performs current workspace admission and the corresponding source read/write checks. If a tool reports a prerequisite, inspect the named prerequisite and current workspace state before continuing; do not create a similarly named substitute.

Sources: StudioAgentProperties, DefaultStudioAgentService, McpStudioAgentToolService, BuildSession, PreconditionTable, SPEC-535 authoring tasks.

Limit Source default Meaning
Standard loop steps 8 Maximum model/tool loop steps for the ordinary turn.
Auto Mode loop steps 12 Maximum steps when Auto Mode is effective.
Turn wall clock 85 seconds Stops a turn whose total bounded work exceeds its budget.
One tool call 25 seconds Per-tool execution timeout.
One model step 60 seconds platform.agent.per-step-model-timeout-millis; invalid or unset values fall back to 60 seconds. The loop clamps each call to the remaining turn budget.
Legacy max latency 20 seconds platform.agent.max-latency-millis; retained separately and does not set the bounded loop step timeout.
Output tokens per model call 16,384 Configured output ceiling, subject to the model's own limit.
Total tokens per turn 500,000 Stops the turn when its aggregate token budget is exhausted.
Repair retries 2 Bounds response/schema repair attempts.
Tool result characters 12,000 Bounds tool output retained for the next model step.
Repeated failing calls 2 Stops repeated calls that fail without useful progress.
Rate-limit retries per step 2 Bounded retries with a 500 ms initial backoff.

The numeric settings come from StudioAgentProperties, which loads the canonical runtime properties when the API creates the service. They are not entries in the Feature Flags API catalog; after changing them, use the deployment's planned API restart/change procedure. The preserved bootstrap example below still shows platform.agent.max-latency-millis=20000; this legacy setting is not the bounded loop step timeout, which uses platform.agent.per-step-model-timeout-millis (60-second default). Do not copy the values into an environment until its owner has checked the intended throughput, gateway and proxy budgets.

For saved conversations, the server admits one active turn per conversation and binds the request to its clientRequestId and expected revision. The same request ID with the same content reconciles to its recorded turn; reusing it with changed content conflicts. A stale revision or simultaneous turn must be resolved by reading the latest conversation, not by manufacturing a new revision.

Before a tool executes, the loop validates its contract and authorization and applies the relevant policy/confirmation boundary. Mutating calls receive a deterministic per-call idempotency key; a replay can return the recorded step rather than repeat the mutation. That behavior applies to tool operations that accept and enforce the key, not every external effect in the platform. If the result is OUTCOME_UNKNOWN, the loop stops dependent writes until an authorized read-only call reconciles the target. A timeout is not evidence that the write failed.

POST /api/studio-agent/conversations/{id}/turns/{clientRequestId}/cancel requests cancellation for an owned turn. Cancellation is observed at loop boundaries; it cannot roll back a step already committed, and the final turn may contain partial successful work. The Studio button is labeled Stop viewing because it stops the current browser from displaying the stream; its handler also sends this best-effort cancellation request. A local stop or a lost response is not a cancellation receipt. Read the turn's final activity and the actual workspace object before deciding whether to continue.

StudioRunObservabilityTrace records bounded step counts, stop reason, budget use, tool status and duration, model/profile and authorized policy/verification receipts; it omits hidden reasoning and protected payloads. Treat this as internal service observability, not a durable audit transcript or a public endpoint. Audit events and per-action receipts remain the sources for their own claims.

Sources: agent properties, loop and limits, tool tiers, tool policy tiers and effective Auto Mode, conversation send/cancel routes, cancellation result, turn cancellation, trace shape, Stop viewing handler.

The specialist body below is retained from the pinned manual-split baseline. Where its older loop/configuration description conflicts with the dated source updates above, use the current-source behavior and defaults above; in particular, disabling the bounded loop does not restore the retired single-shot path.

Studio Agent

Use the owned conversation and decision lifecycle

Ask Inflow is the Studio assistant. Its existing durable conversations, grounded context, memories, goals and decisions are separate contracts that share the current authenticated actor/workspace. A generic memory scope is not conversation ownership, and an ordinary chat answer is not approval of a native business effect. The future floating application-specific App Chat is not implied by these Studio controls.

You want to do Retain and inspect
Create/reopen a conversation actual conversation ID, owner/workspace and revision
Send or reconcile a turn original clientRequestId, expectedRevision and resulting turn state
Reuse context/memory current source access, lineage and accepted memory decision
Run a bounded goal objective, acceptance criteria, constraints, steps/budget and verification evidence
Approve a proposal actual discriminated subject/revision/option and any separate sensitive gate

Samples use the people-ops demonstration with Mohammad, Sara and Nadia. IDs/revisions come from actual authorized responses. The documentation did not call a provider, operate an application or certify the assistant's work.

Example UIAI-STUDIO_AGENT-01 — Create a conversation and send one deliberate turn

Scenario and inputs. Nadia is signed into the intended people-ops workspace and the Studio conversation feature is available. She wants to ask about the fictional leave application, not import a private personnel history. The actor and workspace are server-owned context, not arbitrary owner fields in a request.

Procedure. Create through /api/studio-agent/conversations with a title and clientRequestId. Retain its actual ID/revision. Send to that ID's /messages route with a new stable clientRequestId, the current expectedRevision, message and selected Studio context. The number3 below illustrates a revision actually read as3; replace it with your response value rather than assuming every new conversation starts there.

{"clientRequestId":"leave-turn-014","expectedRevision":3,"message":"Explain the fictional leave form's validation.","context":{"page":"interfaces","workspaceKey":"people-ops","selection":{}}}

Expected result. The service admits one owned conversation turn and returns its actual outcome. A repeated original intent is reconciled through the service rather than treated as a new independent model request. A successful text response still does not prove the form was built or published.

Failure and recovery. Re-read a stale revision and resolve the actual conversation state. After an unknown turn outcome, preserve its original clientRequestId and inspect/reconcile it; do not immediately mint another ID. A denied or disabled conversation is unavailable, not a reason to fall back to unowned generic memory.

Sources. Owned routes, send DTO, admission/reconciliation.

Example UIAI-STUDIO_AGENT-02 — Reopen a conversation after the selected context changes

Scenario and inputs. Nadia returns to a conversation about the synthetic leave form. Since the previous turn, the selected interface revision or her current access may have changed. Stored prose mentioning an object does not guarantee current authorization to fetch that object's data.

Procedure. Open the actual owned conversation and inspect its latest snapshot before resuming. Use the context surface to resolve the current selection and its source lineage; use the conversation's event cursor/limit contract for incremental events rather than repeatedly reading an unbounded history. Keep the actual workspace and object coordinates distinct from user-visible titles.

Expected result. The service applies its owned actor/workspace boundary and current context admission. A summary or prior message remains historical text; it does not silently substitute a current draft for a referenced published object or create a grant. Event paging continues from the returned sequence instead of inventing a message ID cursor.

Failure and recovery. If a source is revoked or unavailable, the assistant must not claim it refreshed that source successfully. Restore only the specifically authorized access or continue with a narrower admitted context. Do not copy a stale private snippet into another workspace to evade the refusal, and do not report an unavailable source as an empty business result.

Sources. Context and event routes, owned-context service, context port.

Example UIAI-STUDIO_AGENT-03 — Review an owned memory proposal

Scenario and inputs. The assistant proposes remembering that the demonstration must use synthetic leave records. Nadia wants this constraint retained in the owned conversation, but not as an automatic business decision or a generic global fact. She has the actual conversation and memory IDs from the proposal response.

Procedure. Read the proposal's kind, subject, content, unresolved constraints and source lineage. Accept or reject it through that conversation's /memories/{memoryId}/decision route, using the memory's current expectedRevision and the deliberate accept Boolean. The value2 below is illustrative only after reading revision2. Re-read the returned memory and conversation state before relying on acceptance.

{"expectedRevision":2,"accept":true}

Expected result. The decision updates the particular owned memory through its native lifecycle. It does not approve a vacation, authorize a tool effect or bypass a source revocation. Generic /api/agent-memory grouping fields remain a different storage boundary.

Failure and recovery. If the memory revision changed, review the latest proposal rather than applying a stale decision. Reject content whose lineage is wrong or disclosure is inappropriate. After an uncertain reply, inspect the same memory and original decision context; do not create another proposal that silently changes what the user reviewed.

Sources. Memory routes, decision body, memory ownership tests.

Example UIAI-STUDIO_AGENT-04 — Judge a bounded goal using its verification evidence

Scenario and inputs. Nadia asks the assistant to prepare a leave-form change with explicit acceptance criteria: required dates/reason, understandable validation, and no unauthorized employee data. The intended artifacts, constraints and budget belong to one goal in the actual owned conversation.

Procedure. Create or inspect the goal through its native goal surface. Review objective, steps, dependencies, selected artifacts and budget before permitting work. Read its proposals/effects/verification separately. If a proposal requires a decision, use its actual subject family, target revision and allowed option, including any separate sensitive gate; an ordinary message saying proceed is not a replacement wire contract.

Expected result. A bounded goal carries concrete progress and evidence limits. Its verification endpoint is the source for what the system actually established, not a fluent “done” answer. Pause/resume/cancel use their native current-revision controls and do not erase recorded effects or retry uncertain operations automatically.

Failure and recovery. Missing artifacts, exhausted budget or failed verification remain explicit unmet work. Inspect the causal/recovery proposal and actual source evidence before continuing. Do not relabel a plan as a published application, infer production readiness from tool output, or accept a proposal whose reviewed target revision has changed.

Sources. Goal/proposal routes, goal request, discriminated decision.

The Studio Agent is the always-on assistant used by the inflow.ai Studio UI. It is intentionally routed through the platform AI Gateway instead of calling an AI provider directly. This keeps redaction, model routing, workspace AI policy, usage accounting, and audit behavior in one place.

Runtime Default

The default purpose is:

studio-agent

Migration 000030_create_platform_ai_defaults creates platform_ai_defaults. Its old seed row (studio-agent -> qwen3:1.7b) names a model that no longer exists (SCRUM-4817, 2026-11-05), so it is treated as unset. The default can be changed at runtime by platform administrators without restarting the server.

Resolution order for gateway requests without a preferred model:

  1. platform_ai_defaults row for the request purpose, when it names an existing model.
  2. The enabled model: the <connectionKey>-chat model of an enabled AI provider connection with a chosen model.

Without an enabled model, Ask Inflow is hidden. The settings platform.agent.model and platform.agent.provider were removed.

Configuration

conf/custom_config.properties contains the bootstrap values:

platform.agent.enabled=true
platform.agent.load-on-boot=true
platform.agent.max-latency-millis=20000
platform.agent.max-reply-characters=4000
platform.agent.api-base-url=http://localhost:8080

There is no configured model or provider: the model comes from the purpose default or the enabled model, as above.

Administration API

List defaults:

GET /api/admin/ai-defaults
X-Actor-Id: root

Set the Studio Agent model:

PUT /api/admin/ai-defaults/studio-agent
X-Actor-Id: root
Content-Type: application/json

{"modelId":"my-ollama-chat"}

The model must be an enabled connection model. Unknown models return AI_MODEL_NOT_FOUND. Mutations require the AI_DEFAULTS_MANAGE permission. The development root account passes through the admin wildcard permission.

Chat API

Health:

GET /api/studio-agent/health
X-Actor-Id: root

Example response:

{
  "purpose": "studio-agent",
  "modelId": "my-ollama-chat",
  "providerId": "my-ollama",
  "reachable": true,
  "agentDefinitionId": null
}

Chat:

POST /api/studio-agent/chat
X-Actor-Id: root
X-Workspace-Id: 00000000-0000-0000-0000-000000000001
Content-Type: application/json

{
  "message": "Explain this workspace",
  "context": {
    "page": "Workspaces home",
    "workspaceKey": "default"
  },
  "conversationId": null
}

Example response:

{
  "conversationId": "4d54d83e-3a75-4b53-a2da-ef1a7d2fd9de",
  "reply": "This workspace is the default platform workspace...",
  "modelId": "my-ollama-chat",
  "proposedActions": [],
  "available": true
}

The response always carries proposedActions. These are human-facing action drafts with hidden execution details. The UI displays labels such as Create workspace, visible field values, missing inputs, and risk level; it does not show raw API paths or HTTP methods to consultants. When the provider is down or the model cannot answer, the endpoint returns HTTP 200 with available: false and a plain-language reply instead of exposing a stack trace.

API Tool Catalog And Execution

The Studio Agent learns platform APIs from the running Spring request mapping registry. This is not a hand-maintained list. When a controller endpoint is added, it appears in the agent tool catalog automatically.

List available tools:

GET /api/studio-agent/tools
X-Actor-Id: root

Each internal tool includes method, path, owning controller method, risk, parameter metadata, and an example request body inferred from controller method signatures:

{
  "id": "POST /api/workspaces",
  "method": "POST",
  "path": "/api/workspaces",
  "summary": "WorkspaceController.create",
  "risk": "MEDIUM",
  "parameters": [
    {"name": "key", "location": "body", "type": "String", "required": true},
    {"name": "name", "location": "body", "type": "String", "required": true},
    {"name": "description", "location": "body", "type": "String", "required": true}
  ],
  "exampleBody": {
    "key": "",
    "name": "",
    "description": ""
  }
}

Execute a tool:

POST /api/studio-agent/tools/execute
X-Actor-Id: root
X-Workspace-Id: 00000000-0000-0000-0000-000000000001
Content-Type: application/json

{
  "method": "GET",
  "path": "/api/workspaces",
  "confirmed": true
}

Execution is approval-gated. If confirmed is false, the endpoint returns executed:false with status 428. The server forwards the current actor and workspace headers into the internal API call, so the same authentication, permissions, workspace isolation, audit, and validation rules still apply. The agent is prevented from recursively executing its own chat/execution endpoint.

Plugin process nodes in the platform catalog

The processNodes section of the platform catalog (platform_catalog, section processNodes) lists the built-in nodes under nodes and, under pluginNodes, every approved and enabled process-node plugin from the same registry the Studio palette reads: pluginId, nodeKey, display name, description, category, ports, and for an operation node each operation with its key, label, sentence, sideEffect, requiredPermission, approval, scope, allowedRunAs and fields (name, label, help, type, picker, required, choices). An agent binds the node by pluginId and chooses an operation by key; it never sees, and never needs, an artifact path, digest or trust tier. The section follows the palette's own rules: it needs PROCESS_DEFINITION_VIEW when a caller is signed in (otherwise pluginNodesWithheld says so), it is empty while the process module is off, and a plugin that shadows a built-in node key is dropped. With no signed-in actor (an internal, server-side caller with no request principal) the permission is not checked and the section is listed; only a permission or authentication refusal withholds it, any other failure propagates like every other catalog error.

Studio UI Behavior

The right-side Agent rail calls /api/studio-agent/health on load to know whether the assistant is reachable. The consultant UI shows readiness only; model and provider details stay out of the rail and belong in administration or diagnostics views. When the user sends a message, the rail posts to /api/studio-agent/chat with the current page, workspace key, and route context. If the platform API is offline, the input is disabled together with the rest of the write-capable Studio controls.

Replies are rendered as lightweight rich text: headings, bullets, bold text, and inline code are displayed as formatted content instead of raw plain text. Proposed actions are shown as action cards with a human label, plain-language description, risk, visible field values, and either a missing-input prompt or a Confirm & run button. The action card intentionally hides internal API paths and methods.

The rail keeps the product rule that the agent proposes before it acts. Confirmed execution uses /api/studio-agent/tools/execute behind the scenes. The UI sends confirmed:true only after the user presses the action button, especially for medium and high-risk tools.

After a successful action, the Studio UI must update the affected local state immediately and then refresh from the platform API. For example, when the agent creates a workspace, the rail inserts the returned workspace into the shared workspace state, marks it as current/recent, and then reloads the workspace list from the server. Agent actions should never leave the visible screen stale after a successful mutation.

Verification

Focused backend tests:

docker compose run --rm java-dev mvn "-Dtest=AiDefaultsServiceTest,StudioAgentServiceTest,ApiStudioAgentControllerTest" test

Frontend build:

cd studio/frontend
npm run build

Manual checks:

  1. Apply migrations through .\scripts\migrate.ps1 -Command up.
  2. Start the API and Studio frontend.
  3. Open /workspaces and confirm the Agent rail shows readiness without exposing model or provider names.
  4. Stop Ollama or use an unavailable local model and confirm chat returns an unavailable reply without a server error.
  5. Ask Create a workspace for procurement approvals, confirm the action card shows Create workspace with key/name values, and click Confirm & run.

Identity and access steps from MCP

configure_identity_step configures a Manage Application Access or Administer Tenant Security step inside a state flow from the node's catalog contract (processNodes.pluginNodes): the operation, only its declared settings (people, groups, profiles, personas, service accounts and permissions picked from the process directory, never typed), input bindings and run-as. When a value is missing it answers IDENTITY_STEP_INPUT_NEEDED with what to ask and the picker to use; an operation you may not publish, an unknown operation or setting, an unresolved reference or a stale revision is refused and nothing is written. Check the result with assess_lifecycle, then publish_lifecycle.

Canonical feature configuration (spec503)

platform.agent.enabled, platform.agent.conversations.enabled, platform.assist.enabled and platform.process.assist.enabled use the canonical file and restart. API/MCP writes edit that same file. platform.agent.load-on-boot has no implemented boot-load consumer; the rule-assist counterpart is logged only. Neither is an implemented model warm-up control. Authorized enabled provider/model records remain separate prerequisites. See Feature switches and migration for exact keys, defaults, scope, direct-edit locking, migration and rollback.

Owned Durable Conversations (Spec 505 R1 Slice 1)

Durable conversation persistence is off by default (NFR-009) and becomes available only when an administrator configures both keys in conf/custom_config.properties:

platform.agent.conversations.enabled=true
platform.agent.conversations.retention-days=30

When either key is absent or disabled, the conversation endpoints return available: false with a plain-language reason, and the Studio Agent rail shows History is off (data-agent-id="app.agent.history.state", data-agent-state="disabled") while continuing to support ephemeral turns through POST /api/studio-agent/chat.

When enabled with a positive retention-days, conversations are owned by the signed-in actor (CurrentActorProvider) and bound to the server-verified WorkspaceContext (FR-009, FR-010):

  • GET /api/studio-agent/conversations?limit=20 lists the caller's active, non-expired conversations in the current workspace (newest first).
  • POST /api/studio-agent/conversations creates an owned conversation in the current workspace.
  • GET /api/studio-agent/conversations/{conversationId} returns the conversation and ordered messages (sequenceNo), or a neutral 404 (STUDIO_CONVERSATION_NOT_FOUND) when the ID is unknown, expired, or belongs to another actor or workspace.
  • POST /api/studio-agent/conversations/{conversationId}/messages accepts { "clientRequestId": "<uuid>", "expectedRevision": 0, "message": "...", "context": { ... } }:
    • (conversationId, clientRequestId) is unique with a SHA-256 content digest (FR-015). Repeating the same clientRequestId with identical content returns the existing turn (deduplicated: true) without a second model call; repeating it with different content returns 409 STUDIO_REQUEST_CONFLICT.
    • A stale expectedRevision returns 409 STUDIO_REVISION_CONFLICT.
    • Turns transition through ACCEPTED -> DISPATCH_STARTED -> ANSWER_RECORDED (or REFUSED / OUTCOME_UNKNOWN) with no database transaction held across the AI Gateway call (NFR-006, NFR-007). A dangling DISPATCH_STARTED turn settles to OUTCOME_UNKNOWN and is never automatically re-dispatched.
    • Reloaded historical action cards are display-only (From an earlier session) and cannot be executed. Typing bare approval words (yes, confirm, ok) never executes a proposed action (FR-033, FR-064); only an explicit click on a live, same-session, same-workspace Confirm & run button invokes /api/studio-agent/tools/execute.
    • Audit events (AI_TASK_EXECUTED on studio_agent_conversation) record conversation and message identifiers, workspace, revision, and turn status only—never raw prompt or assistant content (NFR-010).

Grounded Context, Controlled Memory, and Resumable Events (Spec 505 R1 Slices 2 & 3)

  • Context Envelope & Unsaved-Draft Opt-in (POST /api/studio-agent/context, POST /api/studio-agent/conversations/{id}/context). Resolves authorized workspace artifacts into StudioContextChip and verifiable StudioCitation items (FR-001..FR-008). Unsaved local drafts (unsavedDraft, draftContent, dirtyModel, localDraft, editorBuffer) are withheld by default (unsavedDraftWithheld: true) unless the user explicitly toggles Include unsaved draft (data-agent-id="app.agent.context.include-unsaved").
  • Arabic/English Discovery (StudioMultilingualIntentTokenizer). Tokenizes and normalizes Arabic and English requests (\p{L}\p{N}) and expands Arabic business concepts (such as إنشاء, نموذج بيانات, شاشة, موافقة, فاتورة, قاعدة, مجلد, خزانة) to canonical MCP and platform API tool concepts (FR-025).
  • Controlled Memory (GET/POST /api/studio-agent/conversations/{id}/memories, POST .../memories/{memoryId}/decision). Long-term facts, preferences, and decisions are proposed in PROPOSED state and require explicit human approval (ACCEPTED or REJECTED) before reuse (FR-011). Derived summaries, memories, and exports enforce conservative source closure (A+B lineage even when citing only A; FR-012).
  • Lifecycle, Sharing, Export, and Legal-Hold Safe Deletion (PATCH/DELETE /api/studio-agent/conversations/{id}, GET .../export, GET .../events). Conversations remain OWNER_ONLY by default and require explicit EXPLICIT_SHARED opt-in (FR-013). Deletion refuses conversations under legalHold: true with 409 STUDIO_CONVERSATION_LEGAL_HOLD (FR-014). Ordered resumable events (StudioConversationEventPage) stream into the Activity tab (FR-061).

Guided Application Builder, Bounded Goals, and Discriminated Decisions (Spec 505 R2)

  • Bounded Goals (POST/GET /api/studio-agent/conversations/{id}/goals, GET/PATCH /api/studio-agent/goals/{goalId}, POST .../pause|cancel|resume). StudioGoalService tracks explicit objectives, acceptance criteria, constraints, finite execution budgets (maxSteps, maxRetriesPerStep), canonical MCP build revision/fence (linkedBuildId, linkedBuildRevision, linkedBuildFence), and readback verification receipts (FR-016..FR-023). No step transitions to COMPLETED without an authorized readback receipt (FR-048).
  • Discriminated Human Decisions (POST /api/studio-agent/proposals, POST /api/studio-agent/proposals/{id}/decisions, POST /api/studio-agent/proposals/batch-approve). Every decision binds to one canonical StudioDecisionSubjectFamily (MCP_SPEC_PLAN_BUILD, RUNTIME_EFFECT, or PROVISIONAL_RESULT_REVIEW), principal, workspace, target revision, and expiry (FR-032..FR-039). Decisions never cross families, RUNTIME_EFFECT approvals are consumed atomically once, batch approvals are capped at 10 non-sensitive items, and publication/security/destructive changes require separateSensitiveGateConfirmed: true.
  • Document-Approval Reference Application & Tutorial (GET /api/studio-agent/reference-apps/document-approval, POST /api/studio-agent/conversations/{id}/plan-reference-app). StudioBuildAssistant and DocumentApprovalReferenceBlueprint provide the golden Document-Approval reference application (document_approval_app) with governed DMS cabinet (gov_approvals_cabinet) and folder (incoming_vendor_docs) references, typed variable continuity (false/0/""/null/absent), 6-pattern Human Task output separation (approvalDecision, reviewerNotes, decisionReason), and synthetic acceptance reporting (FR-040..FR-050).

Reliable Operator, Causal Diagnosis, BPMN Delegation, and Observability (Spec 505 R3)

  • Causal Diagnosis & Safe Recovery (POST /api/studio-agent/operations/diagnose, GET /api/studio-agent/operations/recovery-proposals). StudioOperationsAssistant inspects redacted value lineage (FORM_INPUT -> OFFERED_PAYLOAD -> PERSISTED_SCOPE -> STATE_EXPORT -> NEXT_RULE) to identify the first divergent boundary, separating reproduced causes from hypotheses (FR-051), and proposes only existing permitted recovery actions (RETRY, REASSIGN, CANCEL, RESUME, REPAIR) with explicit confirmation gates (FR-053).
  • BPMN Agent Delegation & Operational Truth (GET /api/studio-agent/operations/bpmn-delegation-manifest, POST/GET /api/studio-agent/operations/watches). Negotiates a versioned delegation manifest (2026.11-CF1) honoring CF1 admission holds (DEP-02/DEP-03) without fabricating a ProcessContext (FR-054, FR-055). StudioOperationalStatusView separates goal, run, attempt, business outcome, workflow delivery, and verification states so a started, cancelled, or timed-out run is never shown as a completed case (FR-057). Governed watches are opt-in (enabled: false by default) with finite notification budgets (FR-058).
  • Run Observability, Representative Evaluations, and Rollout (POST /api/studio-agent/evaluations/run, POST /api/studio-agent/feedback). StudioRunObservabilityTrace omits hidden reasoning and reports UNKNOWN (never invented zero/numbers) when token usage is unavailable (FR-071). runRepresentativeEvaluations() executes the frozen bilingual/safety/held-out evaluation suite (FR-072), and rolloutAndFeedback records sanitized defect/feedback references (data-agent-id="app.agent.evidence.report-defect") with reversible capability exposure (FR-065, FR-074).

Current publication-candidate revision binding

  • Publication Impact Candidate Revision Binding Under PAN Redaction (SCRUM-5279, Spec 541). Because 13-digit epoch-millisecond revision values returned by /api/{data-models|rules}/drafts/{draftId}/publication-impact-candidate are masked as [REDACTED:card-number] in model-visible tool results by DefaultAiRedactionService, McpStudioAgentToolService accepts assess_publication_impact (operation: "PUBLISH") with revision omitted when workspaceId, kind, key, draftId, operation, and exact contentHash match the secured native publication-impact-candidate readback under the caller's identity.

Try “document generation”, “integrations” or “first form”.