Configure Agent Settings

Sometimes you need to give users control over how your agent behaves during a conversation. For example, users might want to enable or disable thinking mode, choose between different response styles, or configure other agent-specific parameters. The Agent Stack platform provides a settings as a part of Form extension that creates an interactive UI component where users can configure these options before or during their interaction with your agent.

Settings extensions are a type of form Service Extension that allows you to easily “inject dependencies” into your agent. This follows the inversion of control principle where your agent defines what it needs, and the platform provides those dependencies.

Quickstart

Import the Settings extension

Import the necessary components from the Agent Stack SDK fomr extension.

Add settings parameter to your agent

Inject the extension into your agent function using the Annotated type hint.

Define your settings structure

Create a SettingsFormRender object with the fields you want users to configure. The only allowed field types for settings are CheckboxGroupField and SingleSelectField.

Process settings data

Use parse_settings_form() to access the user’s configuration choices.

It is also possible to combine setting with initial form using FormServiceExtensionSpec.demand_forms, but they need to be parsed separately.

Basic Settings Example

Here’s how to add simple user defined settings to your agent:

# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os
from collections.abc import AsyncGenerator
from typing import Annotated

from a2a.types import Message
from agentstack_sdk.a2a.extensions import (
    CheckboxField,
    CheckboxGroupField,
    OptionItem,
    SettingsFormRender,
    SingleSelectField,
    FormServiceExtensionServer,
    FormServiceExtensionSpec,
)
from agentstack_sdk.a2a.types import RunYield
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext
from pydantic import BaseModel


class SettingsModel(BaseModel):
    checkbox_settings: dict[str, bool] | None = None
    response_style: str | None = None


server = Server()


@server.agent()
async def basic_settings_example(
    message: Message,
    context: RunContext,
    form: Annotated[
        FormServiceExtensionServer,
        FormServiceExtensionSpec.demand_settings(
            settings_form=SettingsFormRender(
                fields=[
                    CheckboxGroupField(
                        id="checkbox_settings",
                        label="Thinking Options",
                        fields=[
                            CheckboxField(
                                id="thinking",
                                label="Enable Thinking",
                                content="Show agent's reasoning process",
                                default_value=True,
                            ),
                            CheckboxField(
                                id="memory",
                                label="Enable Memory",
                                content="Use available memory system",
                                default_value=True,
                            ),
                        ],
                    ),
                    SingleSelectField(
                        id="response_style",
                        label="Response Style",
                        options=[
                            OptionItem(id="concise", label="Concise"),
                            OptionItem(id="detailed", label="Detailed"),
                            OptionItem(id="humorous", label="Humorous"),
                        ],
                        default_value="concise",
                    ),
                ],
            )
        ),
    ],
) -> AsyncGenerator[RunYield, Message]:
    """Demonstrate settings form extension"""

    if not form:
        yield "Form extension hasn't been activated, no settings are available"
        return

    parsed_settings = form.parse_settings_form(model=SettingsModel)

    if not parsed_settings:
        yield "No settings provided"
        return

    if not isinstance(parsed_settings, SettingsModel):
        yield f"Parsed settings in unexpected format: {parsed_settings}"
        return

    response = "Settings:\n"

    if parsed_settings.checkbox_settings:
        thinking_enabled = parsed_settings.checkbox_settings["thinking"]
        choice = "enabled" if thinking_enabled else "disabled"
        response += f"- Thinking is {choice}.\n"

        memory_enabled = parsed_settings.checkbox_settings["memory"]
        choice = "enabled" if memory_enabled else "disabled"
        response += f"- Memory is {choice}.\n"

    response_style = parsed_settings.response_style
    choice = response_style if response_style else "not set"
    response += f"- Response style: {choice}\n"

    yield response

    # Warning: the code below is not automatically tested, check the implementation if you want to use unparsed settings.
    # Alternatively, you can use the raw data without parsing into a model:

    # parsed_settings = form.parse_settings_form()

    # if not parsed_settings:
    #     yield "No settings provided"
    #     return

    # thinking_field = parsed_settings.values.get("checkbox_settings")
    # if thinking_field and thinking_field.type == "checkbox_group":
    #     thinking_enabled = thinking_field.value and thinking_field.value.get("thinking", False)
    #     if thinking_enabled:
    #         yield "Thinking is enabled. "
    #     else:
    #         yield "Thinking is disabled. "

    # response_style_field = parsed_settings.values.get("response_style")
    # if response_style_field and response_style_field.type == "singleselect":
    #     yield f"Response style: {response_style_field.value}"


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

How to work with settings

Here’s what you need to know to add settings capabilities to your agent: Import the form extension: Import FormServiceExtensionServer, FormServiceExtensionSpec, SettingsFormRender, and field types from agentstack_sdk.a2a.extensions. Inject the extension: Add a form parameter to your agent function using the Annotated type hint with FormServiceExtensionServer and FormServiceExtensionSpec.demand_settings(). Define your settings structure: Create a SettingsFormRender object with the fields you want users to configure. Only CheckboxGroupField and SingleSelectField are allowed for settings. Check if the extension exists: Always verify that the form extension is provided before using it, as service extensions are optional. Parse settings data: Use form.parse_settings_form() to access the user’s configuration choices. Access field values: Use parsed_settings.values['field_id'] to access the submitted values from your settings fields.

Settings are presented to users in a clean, organized interface that makes it easy to configure your agent’s behavior. The platform automatically handles the UI rendering and data collection.

Check if the extension exists: Always verify that the form extension is provided before using it, as service extensions are optional.

Settings Field Types

Agent Stack supports various field types for collecting different kinds of configuration data:

CheckboxGroupField

Groups multiple checkboxes together for related boolean options. A single checkbox must still be wrapped inside the CheckboxGroupField.

from agentstack_sdk.a2a.extensions import CheckboxField, CheckboxGroupField

CheckboxGroupField(
    id="features",
    label="Features",
    fields=[
        CheckboxField(
            id="thinking",
            label="Show Thinking Process",
            content="Display the agent's reasoning process",
            default_value=True,
        ),
        CheckboxField(
            id="citations",
            label="Include Citations",
            content="Add source citations to responses",
            default_value=False,
        ),
    ],
)

SingleSelectField

Dropdown fields for choosing an option from a list:

from agentstack_sdk.a2a.extensions import OptionItem, SingleSelectField

SingleSelectField(
    id="response_style",
    label="Response Style",
    options=[
        OptionItem(id="formal", label="Formal"),
        OptionItem(id="casual", label="Casual"),
        OptionItem(id="technical", label="Technical"),
    ],
    default_value="casual",
)

Introduction

Deploy Agents

Agent Integration

Reference

Deploy Agent Stack

Custom UI Integration

Experimental

Community

Configure Agent Settings

Quickstart

Basic Settings Example

How to work with settings

Settings Field Types

CheckboxGroupField

SingleSelectField

​Quickstart

​Basic Settings Example

​How to work with settings

​Settings Field Types

​CheckboxGroupField

​SingleSelectField

Quickstart

Basic Settings Example

How to work with settings

Settings Field Types

CheckboxGroupField

SingleSelectField