Configuration Options

Configuration

The Next Gen UI Agent can be configured in two ways: programmatically using Python dictionaries or declaratively using YAML configuration files.

Agent configuration JSON Schema and how to use it to validate YAML files in IDE is described here.

Configuration Options

component_system [str, optional]

UI Component system for rendering (default: "json")

data_transformer [str, optional]

Optional name of the Input Data Transformer used by the UI Agent. Can be overriden per data type. Defaults to JSON.

enable_input_data_type_detection [bool, optional]

Controls whether the agent automatically detects the appropriate Input Data Transformer based on data structure when no transformer is explicitly configured (default: True).

More detailed information can be found in Configuring data transformation auto detection section of our Input Data Transformation guide.

selectable_components [set[str], optional]

Set of components that can be selected by the agent's LLM for the input data visualization. If not set, all the components supported by the agent can be selected. You can select from all the supported dynamic components using their Component identification like one-card, image, video-player, table, set-of-cards, chart-bar, chart-line, chart-pie, chart-donut, chart-mirrored-bar.

component_selection_strategy [str, optional]

Strategy for LLM powered component selection and configuration step:

• one_llm_call: Uses single LLM inference call for component selection and configuration - default
• two_llm_calls: Uses two LLM inference calls - first selects component type, second configures it - experimental feature! We haven't seen any gain in accuracy, processing time mostly doubles, but you can play with this approach if interrested.

input_data_json_wrapping [bool, optional]

Whether to perform automatic InputData JSON wrapping if JSON structure is not good for LLM processing (default: True)

generate_all_fields [bool, optional]

If True, the agent will generate all possible view Fields for the UI component into its output configuration UIBlockComponentMetadata.fields_all. It can be used in UI component to give user a chance to manually select/update which fields are shown. If False then all fields aren't generated. Can be overriden for individual data_types. (default: False)

data_types [dict[str, AgentConfigDataType], optional]

Configurations for InputData.types, like:

• input data transformation
• list of components to render this data type

Key is InputData.type to configure, value is configuration object for that data type:

data_transformer [str, optional]

Optional name of the Input Data Transformer to be used for this data type instead of Agent's default one.

generate_all_fields [bool, optional]

If True, the agent will generate all possible view Fields for the UI component into its output configuration UIBlockComponentMetadata.fields_all. It can be used in UI component to give user a chance to manually select/update which fields are shown. If False then all fields aren't generated, if not defined then agent's default setting is used. All fields are supported only for table and set-of-cards components.

components [list[AgentConfigComponent], optional]

Optional list of components used to render this data type. See description of the component selection process.

Single component: When one component is configured, it's used directly without the LLM processing. It has to be Hand Build Component or Dynamic component with pre-defined configuration provided.

Multiple components: When multiple components are configured, LLM selects the best one based on user prompt and data. Each component can be:

• Dynamic component with or without pre-defined configuration
• Hand Build Component with prompt.description defined

Note: When using Hand Build Components in multi-component configuration, each HBC must have prompt.description defined for LLM selection. HBCs can be mixed with dynamic components.

component [str, required]

Name of the UI component. Identification of the supported Dynamic Component can be used here. Other value is interpreted as Hand Build Component name and HBC is rendered.

llm_configure [bool, optional]

Controls whether LLM generates component configuration. Defaults to True. Only applicable to Dynamic components.

• True (default): LLM generates configuration (fields). Pre-defined configuration is optional and ignored if provided for now (will be used as a base for LLM generation in the future).
• False: Pre-defined configuration must be provided and will be used. LLM only selects which component to use.

configuration [AgentConfigDynamicComponentConfiguration, optional]

Pre-defined configuration for Dynamic components. Required when llm_configure=False or for single dynamic component, optional otherwise.

title [str, required]

Title of the component to be rendered in UI.

fields [list[DataField], required]

Fields of the UI component in the same format as generated by the LLM. Data transformation step is performed to pick-up Input Data values for UI rendering, so consult it for individual components specifics.

####### name [str, required]

Name of the field rendered in UI. Can be used as a name of column in the table, or name of the fact in the card.

####### data_path [str, required]

JSON Path pointer to Input Data structure to pick up values for UI rendering.

prompt [AgentConfigPromptComponent, optional]

Customize LLM prompts for this specific component when it's used in multi-component selection. Has the same fields as global prompt.components. Overrides global prompt configuration for this component in this data_type context.

Per-component prompt overrides take the highest precedence during prompt construction. This allows you to provide data_type-specific guidance for component selection.

For detailed explanation of how prompt construction works and field descriptions, see Data UI Blocks - Prompt Customization.

Note for Hand-Build Components (HBCs):

• Required in multi-component: At least description field must be defined when multiple components are configured
• Used fields: Only description is used for LLM component selection
• Accepted but not used: chart_* and twostep_step2_* fields are accepted in configuration but not used for HBCs

prompt [AgentConfigPrompt, optional]

Configuration for customizing LLM system prompts used by the agent.

components [dict[str, AgentConfigPromptComponent], optional]

This allows you to override component related parts of the prompt. Dictionary mapping component names to their prompt part overrides. Keys must be valid component names, identification of the supported Dynamic Component can be used here, e.g., table, chart-bar, one-card. Only specified fields are overridden for the prompt, unspecified fields retain their default values.

description [str, optional]

Override the main component description for the component selection. This helps the LLM understand when to use this component.

twostep_step2configure_example [str, optional]

Override the example shown to the LLM during component configuration when using two_llm_calls strategy. Provide a JSON example showing how fields should be selected for this component.

twostep_step2configure_rules [str, optional]

Override additional rules for field selection when using two_llm_calls strategy. Use this to provide component-specific guidance for field selection.

chart_description [str, optional]

Override the chart type description shown in chart selection prompts. Only applicable to chart components (chart-bar, chart-line, chart-pie, chart-donut, chart-mirrored-bar).

chart_fields_spec [str, optional]

Override the fields specification for chart component. Describes what fields the chart expects (e.g., [category, metric]).

chart_rules [str, optional]

Override chart-specific rule. Use this to add domain-specific guidance for chart usage.

chart_inline_examples [str, optional]

Override inline JSON examples for chart components. Provide examples specific to your data domain.

system_prompt_start [str, optional]

Override the initial system prompt section for the one-step strategy (used when component_selection_strategy is one_llm_call).

The custom prompt should include the AVAILABLE UI COMPONENTS: heading at the end - the component list, examples and chart instructions will be automatically appended after this heading.

If not set, uses the default hardcoded prompt. For detailed information and examples, see Prompt Tuning.

chart_instructions_template [str, optional]

Override the chart instructions template used in both strategies when chart components are available.

Supports placeholders that will be replaced with dynamically generated component-specific content:

• {charts_description} - Chart type descriptions
• {charts_fields_spec} - Required fields for each chart type
• {charts_rules} - Component-specific rules
• {charts_inline_examples} - Chart configuration examples

If not set, uses the default hardcoded template. For detailed information and examples, see Prompt Tuning.

examples_normalcomponents [str, optional]

Override the normal component examples (table, cards, image) for one-step strategy.

If not set, uses default hardcoded examples. For detailed information, see Prompt Tuning - Examples Customization.

examples_charts [str, optional]

Override the chart component examples for one-step strategy.

If not set, uses default hardcoded examples. For detailed information, see Prompt Tuning - Examples Customization.

twostep_step1select_system_prompt_start [str, optional]

Override the initial system prompt section for two-step strategy's first step (component selection, used when component_selection_strategy is two_llm_calls). Works like system_prompt_start.

If not set, uses the default hardcoded prompt.

twostep_step2configure_system_prompt_start [str, optional]

Override the initial system prompt section for two-step strategy's second step (field configuration, used when component_selection_strategy is two_llm_calls). Must contain {component} placeholder.

If not set, uses the default hardcoded prompt.

twostep_step1select_examples_normalcomponents [str, optional]

Override normal component examples (table, cards, image) for two-step strategy's first step (used when component_selection_strategy is two_llm_calls). Works like examples_normalcomponents.

If not set, uses default hardcoded examples.

twostep_step1select_examples_charts [str, optional]

Override chart component examples for two-step strategy's first step (used when component_selection_strategy is two_llm_calls). Works like examples_charts.

If not set, uses default hardcoded examples.

Programmatic Configuration

Usage with Inference Configuration

from next_gen_ui_agent import NextGenUIAgent, LangChainModelInference
from langchain_ollama import ChatOllama

# Configure LLM inference
llm = ChatOllama(model="llama3.2")
inference = LangChainModelInference(llm)

# Create configuration
config = {
    "component_system": "json",
    "component_selection_strategy": "default",
    "enable_input_data_type_detection": True  # Auto-detect input format (default)
}

agent = NextGenUIAgent(config=config)

With Prompt Customization

from next_gen_ui_agent import NextGenUIAgent, AgentConfig
from next_gen_ui_agent.types import AgentConfigPrompt, AgentConfigPromptComponent

# Create configuration with customized prompts
config = AgentConfig(
    prompt=AgentConfigPrompt(
        components={
            "table": AgentConfigPromptComponent(
                description="Display structured business data in tabular format",
                twostep_step2configure_rules="Always include ID, name, and date fields"
            ),
            "chart-bar": AgentConfigPromptComponent(
                chart_description="Compare sales metrics across products or regions",
                chart_rules="Show values in thousands"
            )
        }
    )
)

agent = NextGenUIAgent(config=config)

With Hand-Built Components

config = {
    "component_system": "json",
    "data_types": {
        "movies:movie-detail": { components : [{ componnet: "movies:movie-detail-view"}]},
        "movies:movies-list":  { components : [{ componnet: "movies:movies-list-view"}]},
    }
}

agent = NextGenUIAgent(config=config)

YAML Configuration

Basic YAML Configuration

Create a YAML configuration file:

---
component_system: json
component_selection_strategy: default

# Auto-detect input data format (enabled by default)
enable_input_data_type_detection: true

data_types:
  movies:movie-detail: 
    components:
      - component: movies:movie-detail-view
  movies:movies-list:
    components:
      - component: movies:movies-list-view

YAML with Prompt Customization

Customize component descriptions and rules for your domain:

---
component_system: json

prompt:
  components:
    table:
      description: "Display structured business data in tabular format"
      twostep_step2configure_rules: "Always include ID, name, and date fields"
    
    chart-bar:
      description: "Bar chart is suitable for values comparison"
      chart_description: "Compare sales metrics across products or regions"
      chart_rules: "Show values in thousands"
    
    one-card:
      description: "Show detailed information for a single business entity"
      twostep_step2configure_rules: "Include key identifiers and status information"

Multiple Component Configuration

Configure multiple components per data type with LLM-based selection:

---
data_types:
  product-list:
    components:
      # Option 1: LLM selects and configures
      - component: table
        llm_configure: true  # default, can be omitted
      # Option 2: LLM selects, use pre-config
      - component: set-of-cards
        llm_configure: false
        configuration:
          title: "Products"
          fields:
            - name: "Name"
              data_path: "products[*].name"
            - name: "Price"
              data_path: "products[*].price"
  
  custom-data:
    components:
      # Hand-Build Component with required description
      - component: my-custom-component
        prompt:
          description: "Use custom component for special data format"

This configuration allows LLM to choose between table and cards for product lists based on user intent, while still controlling the exact fields shown in cards view.

Per-Component Prompt Customization

Customize LLM prompts at the component level within data_types for fine-grained control:

---
# Global prompt (applies to all data types by default)
prompt:
  components:
    table:
      description: "Generic table description"

data_types:
  product-data:
    components:
      # Dynamic component with per-component prompt override
      - component: table
        prompt:
          description: "Use table for structured product listings with many items"
      
      # HBC with required description (multi-component scenario)
      - component: products:listing-with-parameters
        prompt:
          description: "Use this listing if user also wants to see products parameters"
      
      # Chart with custom prompt
      - component: chart-bar
        llm_configure: true
        prompt:
          description: "Use bar chart for product category comparisons"
          chart_description: "Product sales by category"
  
  movie-data:
    components:
      # Same table component, different prompt for movies
      - component: table
        prompt:
          description: "Use table for movie listings with ratings and genres"

Per-component prompts override global prompts, allowing different selection behavior per data_type.

Loading YAML Configuration

You can load one or several YAML config files which are merged into one configuration where the last config has the highest precedense. Field data_types is merged so having different keys in different yamls are merged into one data_types configuration.

From File Path

from next_gen_ui_agent import NextGenUIAgent
from next_gen_ui_agent.agent_config import read_config_yaml_file

# Load configuration from files
config = read_config_yaml_file(["path/to/config.yaml", "/path/to/config2.yaml"])
agent = NextGenUIAgent(config=config)

From YAML String

from next_gen_ui_agent import NextGenUIAgent

yaml_config = """
component_system: json
component_selection_strategy: two_llm_calls
"""

# Pass YAML string directly to constructor
agent = NextGenUIAgent(config=yaml_config)