Setup on new Namespace
This guide describes all steps required to configure a new Kubernetes namespace for the UPW-UI application, specifically for the Aptean AI Studio (AIS) integration and the Agent Management feature. This enables the intigration of new or existing AI Agents from Aptean AI studio in any namespace.
How to Navigate to Agent Management
The Agent Management page lets users register AI agents that can be used in the Chat window. Each agent is backed by a data source and a flow configuration.
Navigation to the page goes as follows:
- Log in to the application.
- Open Header settings menu.
- Locate **Namespace Management" and click it.
- In the left-hand sidebar, locate the Editors section.
- Click Manage Agents in the sidebar menu.
The page URL is:
/namespace-management/agent-management
The page displays a two-panel layout:
- Left panel — list of all existing agents with a search box and an Add (+) button.
- Right panel — details of the currently selected agent.
How to Add a New Agent
- On the Agent Management page, click the + (Add) button in the top-right corner of the agent list panel.
- The "Add agent" dialog opens.
- Fill in all required fields (marked below) and click Save.
Click Save to submit the form. If any required field is empty, the form will highlight validation errors without submitting.
- On success — the dialog closes and the new agent appears in the list.
- On conflict (duplicate path) — an inline error banner is shown: "A data source with this path already exists. Please use a different path."
- On general failure — an inline error banner is shown: "Failed to save agent. Please try again."
Click Cancel at any time to close the dialog without saving.
Understanding the Dialog
The dialog is divided into three sections.
Section 1 — Data Source
This section is only shown when creating a new agent. It is hidden when editing an existing one.
| Field | Required | Description |
|---|---|---|
| Name | Yes | The internal name of the data source that will be created for this agent. |
| Path | Yes | The URL path segment used to identify the data source. Maximum 255 characters. Must be unique — if a data source with this path already exists, saving will fail. |
| OpenApi Url | No | The OpenAPI specification URL for the agent's API. |
Section 2 — Agent Configuration
| Field | Required | Description |
|---|---|---|
| Agent name | Yes | The display name of the agent shown to users in the chat and agent list. |
| Agent API key | Yes | The secret API key used to authenticate requests to the agent. Entered as a password (masked input). |
| Flow Id | Yes | The identifier of the flow that this agent is connected to. |
| Description | No | A short description of the agent's purpose. Displayed in the agent detail panel. |
Section 3 — Example Questions
All three fields are optional. Populated questions are displayed in the agent detail panel under "Example questions" and surfaced to users in the chat window.
| Field | Required | Description |
|---|---|---|
| Example question 1 | No | A sample question that demonstrates what this agent can answer. Maximum 1000 characters. |
| Example question 2 | No | A second sample question. Maximum 1000 characters. |
| Example question 3 | No | A third sample question. Maximum 1000 characters. |
Consul Keys
The intigration requires three consul keys, as explained in the table. They are explained in more detail below.
| Consul Key | Required | Purpose |
|---|---|---|
upw-ui/aptean-agents | no (managed via UI) | list of registered AI agents — created and maintained through the Agent Management UI |
upw-ui/app-studio-config | yes | Aptean IAM credentials + datasource IDs for AIS session management |
config/upw-ui/features | yes | feature flags controlling which application features are enabled |
upw-ui/app-studio-config
Purpose
This key provides:
- IAM credentials used to obtain a bearer token from Aptean IAM (via OAuth2 client_credentials flow).
- Datasource IDs that point to platform datasources used for AIS session and message operations. All datasources will be providen automatically.
The application reads this key at runtime via ApteanIamService. If the key is missing or malformed, all AI agent chat functionality will be unavailable.
Value Format
The value must be a JSON object with the following format.
| Field | Required | Endpoint | Details |
|---|---|---|---|
| client_id | yes | - | OAuth2 client ID used to authenticate against Aptean IAM |
| client_secret | yes | - | OAuth2 client secret |
| grant_type | no | - | OAuth2 grant type. Defaults to client_credentials if omitted |
| token_data_source_id | yes | POST https://appcentral-int.aptean.com/iam/auth/realms/aptean/protocol/openid-connect/token | proxies the Aptean IAM token endpoint (application/x-www-form-urlencoded) |
| sessions_datasource_id | yes* | GET https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/sessions | fetches a single AIS session by flow_id |
| messages_datasource_id | yes* | GET https://appcentral-int.aptean.com/ais/api/v1/monitor/messages | fetches messages by flow_id + session_id |
| delete_session_datasource_id | yes* | DELETE https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/session/{sessionId} | deletes a session by sessionId (path param) |
| patch_session_datasource_id | yes* | PATCH https://appcentral-int.aptean.com/ais/api/v1/monitor/messages/session/{sessionId} | renames a session (sessionId path param, new_session_id query param) |
*Required for full agent chat functionality (session management). The app will fall back gracefully but session-related features will not work.
Example:
{
"client_id": "<oauth2-client-id>",
"client_secret": "<oauth2-client-secret>",
"grant_type": "client_credentials",
"token_data_source_id": "cc9d627c-b0ec-364a-82da-81f95e85842b",
"sessions_datasource_id": "f49de3c9-00ba-3457-80de-fd0df0b85740",
"messages_datasource_id": "4c59e7d2-ad68-35b1-928e-d1387312bd78",
"delete_session_datasource_id": "d5239ee1-3b9d-32dd-8b22-96f829561692",
"patch_session_datasource_id": "5405342b-662e-3507-9037-e4491678eb7a"
}upw-ui/aptean-agents
Purpose
Stores the list of AI agents available in the chat interface. This key is managed automatically by the Agent Management UI — you do not need to create it manually. It is created/updated whenever an agent is added or removed through the UI.
Value Format
The value must be a JSON object with the following format.
| Field | Required | Description |
|---|---|---|
| agentName | yes | display name shown in the agent selector |
| agentApiKey | yes | AIS API key (x-api-key header) sent with every chat request to this agent |
| agentDatasourceId | yes | ID of the platform datasource that proxies the AIS chat endpoint for this agent |
| flowId | yes | AIS Flow ID used to scope sessions and messages to this specific flow |
| description | no | short description displayed in the agent selector |
| exampleQuestions | no | up to 3 example questions surfaced in the UI to guide users |
| createdBy | no | username of the person who registered the agent |
Example:
{
"agents": [
{
"agentName": "My Agent",
"agentApiKey": "<ais-api-key-for-this-agent>",
"agentDatasourceId": "<platform-datasource-id>",
"flowId": "<ais-flow-id>",
"description": "Optional description shown to users",
"exampleQuestions": [
"What can you help me with?",
"Show me the latest data"
],
"createdBy": "user@example.com"
}
]
}upw-ui/aptean-agents
Purpose
Controls which application features are enabled in the namespace. The application reads this key at startup to toggle functionality on or off without requiring a redeployment.
Value Format
The value is a flat JSON object of feature flag names mapped to booleans. Like other Consul keys, it must be base64-encoded when written via the API.
| Flag | Default | Description |
|---|---|---|
| platform-admin-app-context-feature | true | enables Platform Administration app context features |
| dynamic-dialog-in-app-features | true | enables dynamic dialogs within application features |
| user-overview-in-namespace-management | false | shows user overview inside namespace management |
| custom-function-ai-assistance | true | enables AI assistance for custom functions |
| chat-panel | true | enables the AI agent chat panel in the UI |
| user-view-state | true | persists and restores user view state |
| mcp-datasources | true | enables MCP (Model Context Protocol) datasource support |
Example:
{
"platform-admin-app-context-feature": true,
"dynamic-dialog-in-app-features": true,
"user-overview-in-namespace-management": false,
"custom-function-ai-assistance": true,
"chat-panel": true,
"user-view-state": true,
"mcp-datasources": true
}Summary Checklist for a New Namespace
- Obtain Aptean IAM credentials (client_id, client_secret) for the namespace.
- Identify or create the platform datasource IDs for each AIS endpoint (token, session, sessions list, messages, delete, patch).
- Create Consul key upw-ui/app-studio-config with the base64-encoded JSON payload.
- Verify the key is readable: open the app, open browser DevTools, confirm no Missing Consul key upw-ui/app-studio-config errors appear in the console.
- Create Consul key config/upw-ui/features with the desired feature flags JSON.
- Register at least one agent via the Agent Management UI.