docs(tarko): agent ui config api reference (#1653)

Author: ulivz

multimodal/agent-tars/core/src/agent-tars.ts

@@ -32,7 +32,7 @@ export class AgentTARS<T extends AgentTARSOptions = AgentTARSOptions> extends MC
   static label = '@agent-tars/core';
 
   /**
-   * Default Web UI configuration for Agent TARS
+   * Default Agent UI Configuration for Agent TARS
    */
   static webuiConfig: AgentWebUIImplementation = {
     logo: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/zyha-aulnh/ljhwZthlaukjlkulzlp/appicon.png',

multimodal/tarko/agent-server-next/src/utils/webui/config.ts

@@ -9,9 +9,9 @@ import type { AgentServer } from '../../types';
 /**
  * Merge web UI config with agent constructor config
  * This ensures consistent configuration merging across different contexts
- * @param baseWebUIConfig Base web UI configuration from app config
+ * @param baseWebUIConfig Base Agent UI Configuration from app config
  * @param server Optional agent server instance to get constructor config
- * @returns Merged web UI configuration
+ * @returns Merged Agent UI Configuration
  */
 export function mergeWebUIConfig(
   baseWebUIConfig: AgentWebUIImplementation,

multimodal/tarko/agent-server/src/utils/webui/config.ts

@@ -10,9 +10,9 @@ import type { AgentServer } from '../../server';
 /**
  * Merge web UI config with agent constructor config
  * This ensures consistent configuration merging across different contexts
- * @param baseWebUIConfig Base web UI configuration from app config
+ * @param baseWebUIConfig Base Agent UI Configuration from app config
  * @param server Optional agent server instance to get constructor config
- * @returns Merged web UI configuration
+ * @returns Merged Agent UI Configuration
  */
 export function mergeWebUIConfig(
   baseWebUIConfig: AgentWebUIImplementation,

multimodal/tarko/agent-ui-builder/README.md

@@ -112,7 +112,7 @@ new AgentUIBuilder(input: AgentUIBuilderInputOptions)
 - `input.sessionInfo`: Session metadata
 - `input.staticPath?`: Optional path to static web UI files
 - `input.serverInfo?`: Optional server version info
-- `input.uiConfig?`: Optional web UI configuration
+- `input.uiConfig?`: Optional Agent UI Configuration
 
 #### Methods
 

multimodal/tarko/agent-ui-builder/src/types.ts

@@ -26,7 +26,7 @@ export interface AgentUIBuilderInputOptions {
   /** Optional server version info */
   serverInfo?: AgentServerVersionInfo;
 
-  /** Optional web UI configuration to inject */
+  /** Optional Agent UI Configuration to inject */
   uiConfig?: AgentWebUIImplementation;
 }
 
@@ -36,7 +36,7 @@ export interface AgentUIBuilderInputOptions {
 export interface UploadOptions {
   /** Custom slug for the share URL */
   slug?: string;
-  
+
   /** Original user query for metadata */
   query?: string;
 }

multimodal/tarko/agent-ui/src/config/default-config.ts

@@ -8,7 +8,7 @@ import type { BaseAgentWebUIImplementation } from '@tarko/interface';
 const sandboxBaseUrl = location.host.includes('localhost') ? 'http://localhost:8080' : '';
 
 /**
- * Default Web UI configuration for standalone deployment
+ * Default Agent UI Configuration for standalone deployment
  */
 export const DEFAULT_WEBUI_CONFIG: BaseAgentWebUIImplementation = {
   logo: 'https://lf3-static.bytednsdoc.com/obj/eden-cn/zyha-aulnh/ljhwZthlaukjlkulzlp/icon.png',

multimodal/tarko/agent-ui/src/config/web-ui-config.ts

@@ -9,15 +9,15 @@ import type { BaseAgentWebUIImplementation } from '@tarko/interface';
 import { ENV_CONFIG } from '@/common/constants';
 
 /**
- * Get web UI configuration with enhanced multi-source loading
+ * Get Agent UI Configuration with enhanced multi-source loading
  */
 export function getWebUIConfig(): BaseAgentWebUIImplementation {
   const result = loadWebUIConfigSync();
   return result.config;
 }
 
 /**
- * Get web UI configuration with enhanced multi-source loading
+ * Get Agent UI Configuration with enhanced multi-source loading
  */
 export function getWebUIRouteBase(): string {
   // Extract actual basename from current URL using shared utility

multimodal/websites/tarko/docs/en/api/_meta.json

@@ -23,5 +23,10 @@
     "type": "file",
     "name": "hooks",
     "label": "Hooks"
+  },
+  {
+    "type": "file",
+    "name": "agent-ui-config",
+    "label": "Agent UI Config"
   }
 ]

multimodal/websites/tarko/docs/en/api/agent-ui-config.mdx

@@ -0,0 +1,283 @@
+# Agent UI Config
+
+The Agent UI Configuration API allows you to customize the Agent web interface appearance, layout, and behavior. Configure branding, welcome screens, navigation, and GUI Agent display options.
+
+## Configuration Methods
+
+### Via tarko.config.ts
+
+Configure Web UI through the `webui` option in your `tarko.config.ts`:
+
+```typescript
+// tarko.config.ts
+import { AgentAppConfig } from '@tarko/interface'
+
+export default {
+  // ... other config
+  webui: {
+    logo: 'https://example.com/logo.png',
+    title: 'My Agent',
+    subtitle: 'AI Assistant for Development',
+    welcomTitle: 'Welcome to My Agent',
+    welcomePrompts: [
+      'Search for the latest GUI Agent papers',
+      'Find information about UI TARS'
+    ]
+  }
+} as AgentAppConfig
+```
+
+### Via Agent Constructor
+
+Set Agent UI Configuration through the static `webuiConfig` property:
+
+```typescript
+// Agent class
+import { AgentWebUIImplementation } from '@tarko/interface'
+
+export class MyAgent extends MCPAgent {
+  static webuiConfig: AgentWebUIImplementation = {
+    logo: 'https://example.com/logo.png',
+    title: 'My Agent',
+    workspace: {
+      navItems: [
+        {
+          title: 'Code Editor',
+          link: 'http://localhost:3000',
+          icon: 'code'
+        }
+      ]
+    }
+  }
+}
+```
+
+## Configuration Options
+
+### Basic Branding
+
+#### logo
+
+```typescript
+logo?: string
+```
+
+Web UI logo URL. Displayed in the navigation bar.
+
+**Default:** Tarko logo
+
+#### title
+
+```typescript
+title?: string
+```
+
+Site title displayed in navbar and browser tab.
+
+**Default:** Agent name
+
+#### subtitle
+
+```typescript
+subtitle?: string
+```
+
+Subtitle for home page and SEO meta description.
+
+#### welcomTitle
+
+```typescript
+welcomTitle?: string
+```
+
+Hero title displayed on the home page welcome screen.
+
+### Welcome Screen
+
+#### welcomePrompts
+
+```typescript
+welcomePrompts?: string[]
+```
+
+Array of suggested prompts displayed on the welcome screen.
+
+**Example:**
+```typescript
+welcomePrompts: [
+  'Search for the latest GUI Agent papers',
+  'Find information about UI TARS',
+  'Tell me the top 5 most popular projects on ProductHunt today'
+]
+```
+
+#### welcomeCards
+
+```typescript
+welcomeCards?: WelcomeCard[]
+```
+
+Welcome screen cards with predefined prompts and Agent options.
+
+**WelcomeCard Interface:**
+```typescript
+interface WelcomeCard {
+  title: string          // Card display title
+  prompt: string         // Prompt content
+  image?: string         // Background image URL
+  category: string       // Grouping category
+  agentOptions?: Record<string, any>  // Agent configuration
+}
+```
+
+**Example:**
+```typescript
+welcomeCards: [
+  {
+    title: 'Code Review',
+    prompt: 'Review my latest pull request',
+    category: 'Development',
+    image: 'https://images.unsplash.com/photo-1551288049-bebda4e38f71',
+    agentOptions: { mode: 'review' }
+  }
+]
+```
+
+### Workspace Configuration
+
+#### workspace
+
+```typescript
+workspace?: {
+  navItems?: WorkspaceNavItem[]
+}
+```
+
+Workspace header navigation configuration.
+
+**WorkspaceNavItem Interface:**
+```typescript
+interface WorkspaceNavItem {
+  title: string                    // Display text
+  link: string                     // URL to open in new tab
+  icon?: WorkspaceNavItemIcon      // Icon type
+}
+
+type WorkspaceNavItemIcon = 'code' | 'monitor' | 'terminal' | 'browser' | 'desktop' | 'default'
+```
+
+**Example:**
+```typescript
+workspace: {
+  navItems: [
+    {
+      title: 'Code Server',
+      link: 'http://localhost:8080',
+      icon: 'code'
+    },
+    {
+      title: 'VNC',
+      link: 'http://localhost:6080',
+      icon: 'monitor'
+    }
+  ]
+}
+```
+
+### Layout Configuration
+
+#### layout
+
+```typescript
+layout?: {
+  defaultLayout?: LayoutMode
+  enableLayoutSwitchButton?: boolean
+  enableSidebar?: boolean
+  enableHome?: boolean
+}
+```
+
+Layout behavior and display options.
+
+**LayoutMode:**
+```typescript
+type LayoutMode = 'default' | 'narrow-chat'
+```
+
+**Properties:**
+- `defaultLayout` - Initial layout mode (default: `'default'`)
+  - `default` - Standard layout with full workspace
+  - `narrow-chat` - Compact chat-focused layout
+- `enableLayoutSwitchButton` - Show layout toggle in toolbar (default: `false`)
+- `enableSidebar` - Display sidebar panel (default: `true`)
+- `enableHome` - Register home route (default: `true`)
+
+**Example:**
+```typescript
+layout: {
+  defaultLayout: 'narrow-chat',
+  enableLayoutSwitchButton: true,
+  enableSidebar: true
+}
+```
+
+### GUI Agent Configuration
+
+#### guiAgent
+
+```typescript
+guiAgent?: {
+  defaultScreenshotRenderStrategy?: 'both' | 'beforeAction' | 'afterAction'
+  enableScreenshotRenderStrategySwitch?: boolean
+  renderGUIAction?: boolean
+  renderBrowserShell?: boolean
+}
+```
+
+GUI Agent display and screenshot rendering options.
+
+**Properties:**
+- `defaultScreenshotRenderStrategy` - Screenshot display strategy (default: `'afterAction'`)
+  - `both` - Show before and after screenshots for comparison
+  - `beforeAction` - Show only pre-action screenshots (suitable for Agent-TARS)
+  - `afterAction` - Show only post-action screenshots (suitable for Omni-TARS)
+- `enableScreenshotRenderStrategySwitch` - Allow runtime strategy switching (default: `false`)
+- `renderGUIAction` - Show GUI operation details card (default: `true`)
+- `renderBrowserShell` - Wrap screenshots in browser shell UI (default: `true`)
+
+**Example:**
+```typescript
+guiAgent: {
+  defaultScreenshotRenderStrategy: 'beforeAction',
+  enableScreenshotRenderStrategySwitch: true,
+  renderGUIAction: true,
+  renderBrowserShell: false
+}
+```
+
+### Advanced Options
+
+#### enableContextualSelector
+
+```typescript
+enableContextualSelector?: boolean
+```
+
+Enable @ syntax file selector. When enabled, users can type @ in the input to search and select workspace files/directories.
+
+**Default:** `false`
+
+#### base
+
+```typescript
+base?: string
+```
+
+Base path for routing deployment. Supports both static paths and regex patterns.
+
+**Examples:**
+```typescript
+base: "/agent-ui"           // Static path
+base: "/tenant-.+"         // Regex pattern
+base: "/(foo|bar)/app"     // Regex with groups
+```

multimodal/websites/tarko/docs/zh/api/_meta.json

@@ -23,5 +23,10 @@
     "type": "file",
     "name": "hooks",
     "label": "Hooks"
+  },
+  {
+    "type": "file",
+    "name": "agent-ui-config",
+    "label": "Agent UI Config"
   }
 ]