Guide
API
Examples
Guide
API
Examples

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:

// 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:

// 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?: string

Web UI logo URL. Displayed in the navigation bar.

Default: Tarko logo

title

title?: string

Site title displayed in navbar and browser tab.

Default: Agent name

subtitle

subtitle?: string

Subtitle for home page and SEO meta description.

welcomTitle

welcomTitle?: string

Hero title displayed on the home page welcome screen.

Welcome Screen

welcomePrompts

welcomePrompts?: string[]

Array of suggested prompts displayed on the welcome screen.

Example:

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

welcomeCards?: WelcomeCard[]

Welcome screen cards with predefined prompts and Agent options.

WelcomeCard Interface:

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:

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

workspace?: {
  navItems?: WorkspaceNavItem[]
}

Workspace header navigation configuration.

WorkspaceNavItem Interface:

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:

workspace: {
  navItems: [
    {
      title: 'Code Server',
      link: 'http://localhost:8080',
      icon: 'code'
    },
    {
      title: 'VNC',
      link: 'http://localhost:6080',
      icon: 'monitor'
    }
  ]
}

Layout Configuration

layout

layout?: {
  defaultLayout?: LayoutMode
  enableLayoutSwitchButton?: boolean
  enableSidebar?: boolean
  enableHome?: boolean
}

Layout behavior and display options.

LayoutMode:

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:

layout: {
  defaultLayout: 'narrow-chat',
  enableLayoutSwitchButton: true,
  enableSidebar: true
}

GUI Agent Configuration

guiAgent

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:

guiAgent: {
  defaultScreenshotRenderStrategy: 'beforeAction',
  enableScreenshotRenderStrategySwitch: true,
  renderGUIAction: true,
  renderBrowserShell: false
}

Advanced Options

enableContextualSelector

enableContextualSelector?: boolean

Enable @ syntax file selector. When enabled, users can type @ in the input to search and select workspace files/directories.

Default: false

base

base?: string

Base path for routing deployment. Supports both static paths and regex patterns.

Examples:

base: "/agent-ui"           // Static path
base: "/tenant-.+"         // Regex pattern
base: "/(foo|bar)/app"     // Regex with groups