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 boundedplatform-mcpagent loop (StudioAgentLoop;platform.agent.loop.enableddefaults totrue).StudioAgentToolPolicyclassifies calls asREAD_ONLY,AUTO_ELIGIBLEorCONFIRM_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_ALWAYScalls always require explicit confirmation. Mutating proposals bind aproposalIdto anargumentsDigest. Effective Auto Mode requires a true request flag and enabled server policy (platform.agent.auto-mode.enableddefaults tofalse); 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,AgentRailfollows 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 owningmanage_build_specshistory 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. SeeBlueprintTools.documentHistoryLinksand the bounded-response contract.
Current product update — 16 November 2026 (
SPEC-538,SCRUM-5207–SCRUM-5211).
- Sibling proposal batching,
Skipdismissal, and server-enforced continuation (FR-001–FR-004,FR-019): In Supervised Mode,StudioAgentLoopbatches 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 isolatingcreate_workspace/select_workspaceand dependent mutations as single proposals.POST /api/studio-agent/proposals/{proposalId}/dismissrecords DB statusSUPERSEDED(honoring000439CHECK) withTOOL_SUMMARYoutcomeStatus = DISMISSEDand returnsremainingPendingProposalsandbatchReadyToContinue.DefaultStudioConversationServiceenforces and auditscontinuationOrigin(USER | POST_CONFIRMATION | AUTO_CHECKPOINT | GOAL_RESUME), capping consecutive non-USERhops at<= 8(409 STUDIO_CONTINUATION_HOP_LIMIT_REACHEDon overflow).- Snapshot proposal filtering and shared-viewer non-actionability (
FR-012,FR-018):StudioConversationSnapshot.proposalsprojects chronologically ordered (createdAt ASC, max200) proposals filtered throughStudioArtifactReadPortto the active workspace, non-redacted visible messages, and caller-readable targets. Non-ownerEXPLICIT_SHAREDviewers receivestatus = SHARED_VIEW_ONLY(actionableByCaller: false) onPENDINGrows while preserving settledCONSUMED/SUPERSEDED/EXPIRED+outcomeStatushistory; Studio never rendersConfirm & run,ReviseorSkipfor non-owners or unauthorized targets.- Caller-scoped dry-run validation, reference read cache, and untrusted discovery boundary (
FR-007–FR-009): Before registering aPENDINGproposal,StudioAgentLoopcallsMcpStudioAgentToolService.validateProposalCandidateunder the caller's effective access (returning neutralTARGET_NOT_AVAILABLEissues 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-validatedentityType:keytokens (excluding free-text search strings), are escaped viaBOUNDARY_TAG_PATTERN, and sit inside the untrusted data boundary.- Hoisted workflow task-routing fallback (
FR-010):McpStudioAgentToolServicehoists process-directory and workspace assignment-reach checks to once per lifecycle operation (never exposing member identities or counts) and falls back to admitted workspacerole: adminwithsingleAdminWorkspaceAssignmentFallback: trueandassignmentGovernanceNotewhen 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,AiTaskGatewayResponseandStudioAgentModelProtocol.StepModelMetadatastorestructuredOutputandusageas unmodifiable maps that omitnullkeys while toleratingnullJSON values without throwingNullPointerException.- Compact
<additional_tools>schemas & operation-declaration sync (SCRUM-5273,SCRUM-5274):StudioAgentPromptAssemblerincludes compactinputSchemadefinitions (retaining operationenums and bounded parameter descriptions while stripping server-ownedconfirm) on<additional_tools>entries, andMcpOperationDeclarationsalignsAdminIdentityController#users(String),DataModelController#publicationImpactCandidate,TaskController#release, document-generation review routes and all registered authoring MCP tools.- Draft-only
publish: falsecontrol & checkpoint/rail guards (SCRUM-5275–SCRUM-5277):McpStudioAgentToolServicehonors explicitpublish: falseoncreate_screen,create_screen_from_pattern,create_rule,create_lifecycleandupdate_lifecycleby leaving the artifact inDRAFTstate (published: false).AgentRail.tsxrequires at least one succeeded mutating step before queuingAUTO_CHECKPOINTcontinuations (usingCONTINUE_CHECKPOINT_MESSAGE), clearssnapshotProposalson new/switched conversations, and scrolls.agent-bodyon activeCONVERSATIONupdates.
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:
platform_ai_defaultsrow for the request purpose, when it names an existing model.- The enabled model: the
<connectionKey>-chatmodel 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:
- Apply migrations through
.\scripts\migrate.ps1 -Command up. - Start the API and Studio frontend.
- Open
/workspacesand confirm the Agent rail shows readiness without exposing model or provider names. - Stop Ollama or use an unavailable local model and confirm chat returns an unavailable reply without a server error.
- Ask
Create a workspace for procurement approvals, confirm the action card showsCreate workspacewith key/name values, and clickConfirm & 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=20lists the caller's active, non-expired conversations in the current workspace (newest first).POST /api/studio-agent/conversationscreates an owned conversation in the current workspace.GET /api/studio-agent/conversations/{conversationId}returns the conversation and ordered messages (sequenceNo), or a neutral404(STUDIO_CONVERSATION_NOT_FOUND) when the ID is unknown, expired, or belongs to another actor or workspace.POST /api/studio-agent/conversations/{conversationId}/messagesaccepts{ "clientRequestId": "<uuid>", "expectedRevision": 0, "message": "...", "context": { ... } }:(conversationId, clientRequestId)is unique with a SHA-256 content digest (FR-015). Repeating the sameclientRequestIdwith identical content returns the existing turn (deduplicated: true) without a second model call; repeating it with different content returns409 STUDIO_REQUEST_CONFLICT.- A stale
expectedRevisionreturns409 STUDIO_REVISION_CONFLICT. - Turns transition through
ACCEPTED -> DISPATCH_STARTED -> ANSWER_RECORDED(orREFUSED/OUTCOME_UNKNOWN) with no database transaction held across the AI Gateway call (NFR-006,NFR-007). A danglingDISPATCH_STARTEDturn settles toOUTCOME_UNKNOWNand 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-workspaceConfirm & runbutton invokes/api/studio-agent/tools/execute. - Audit events (
AI_TASK_EXECUTEDonstudio_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 intoStudioContextChipand verifiableStudioCitationitems (FR-001..FR-008). Unsaved local drafts (unsavedDraft,draftContent,dirtyModel,localDraft,editorBuffer) are withheld by default (unsavedDraftWithheld: true) unless the user explicitly togglesInclude 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 inPROPOSEDstate and require explicit human approval (ACCEPTEDorREJECTED) before reuse (FR-011). Derived summaries, memories, and exports enforce conservative source closure (A+Blineage even when citing onlyA;FR-012). - Lifecycle, Sharing, Export, and Legal-Hold Safe Deletion (
PATCH/DELETE /api/studio-agent/conversations/{id},GET .../export,GET .../events). Conversations remainOWNER_ONLYby default and require explicitEXPLICIT_SHAREDopt-in (FR-013). Deletion refuses conversations underlegalHold: truewith409 STUDIO_CONVERSATION_LEGAL_HOLD(FR-014). Ordered resumable events (StudioConversationEventPage) stream into theActivitytab (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).StudioGoalServicetracks 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 toCOMPLETEDwithout 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 canonicalStudioDecisionSubjectFamily(MCP_SPEC_PLAN_BUILD,RUNTIME_EFFECT, orPROVISIONAL_RESULT_REVIEW), principal, workspace, target revision, and expiry (FR-032..FR-039). Decisions never cross families,RUNTIME_EFFECTapprovals are consumed atomically once, batch approvals are capped at 10 non-sensitive items, and publication/security/destructive changes requireseparateSensitiveGateConfirmed: true. - Document-Approval Reference Application & Tutorial (
GET /api/studio-agent/reference-apps/document-approval,POST /api/studio-agent/conversations/{id}/plan-reference-app).StudioBuildAssistantandDocumentApprovalReferenceBlueprintprovide 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).StudioOperationsAssistantinspects 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 aProcessContext(FR-054,FR-055).StudioOperationalStatusViewseparates 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: falseby default) with finite notification budgets (FR-058). - Run Observability, Representative Evaluations, and Rollout (
POST /api/studio-agent/evaluations/run,POST /api/studio-agent/feedback).StudioRunObservabilityTraceomits hidden reasoning and reportsUNKNOWN(never invented zero/numbers) when token usage is unavailable (FR-071).runRepresentativeEvaluations()executes the frozen bilingual/safety/held-out evaluation suite (FR-072), androlloutAndFeedbackrecords 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-millisecondrevisionvalues returned by/api/{data-models|rules}/drafts/{draftId}/publication-impact-candidateare masked as[REDACTED:card-number]in model-visible tool results byDefaultAiRedactionService,McpStudioAgentToolServiceacceptsassess_publication_impact(operation: "PUBLISH") withrevisionomitted whenworkspaceId,kind,key,draftId,operation, and exactcontentHashmatch the secured nativepublication-impact-candidatereadback under the caller's identity.