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.common.form import (
CheckboxField,
CheckboxGroupField,
OptionItem,
SettingsFormRender,
SingleSelectField,
)
from agentstack_sdk.a2a.extensions.services.form import (
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.common.form and agentstack_sdk.a2a.extensions.services.form.
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.common.form 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.common.form 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",
)