SingleSelectField clash between Settings and Form

[jpwsutton]

Pre-requisities

• I am using the newest version of the platform (agentstack version shows that CLI and platform are the same version, and there is no newer version available)

Describe the bug
If building an agent that has both a settings element containing a agentstack_sdk.a2a.extensions.ui.settings.SingleSelectField and then requests a form mid conversation that also includes a agentstack_sdk.a2a.extensions.ui.form.SingleSelectField, you get an import clash (Assuming this is all in the same file) resulting in pydantic validation errors for the agentstack_sdk.a2a.extensions.ui.form.SingleSelectField.

agentstack_sdk.a2a.extensions.ui.settings.OptionItem and agentstack_sdk.a2a.extensions.ui.form.OptionItem are similarly affected.

The equivalent types are similar enough that when defining them, mypy complains about things like id or value missing from the OptionItem. You can try and resolve this by adding the missing field in, but upon execution, an exception will be thrown when attempting to render the mid chat form.

A quick workaround is just to alias one of the pair on import like so:

from agentstack_sdk.a2a.extensions.ui.settings import (
    OptionItem as SettingsOptionItem,
    SingleSelectField as SettingsSingleSelectField,
)

However, I think longer term, it might be worth combining the Settings and Form classes into a single common form class as there is so much overlap between the two.

To Reproduce
Create a simple agent that uses a agentstack_sdk.a2a.extensions.ui.settings.SingleSelectField in it's settings, and then requests a form mid chat using agentstack_sdk.a2a.extensions.ui.form.SingleSelectField.

Expected behavior
Both the settings and the mid chat form should render correctly.

Logs / Screenshots / Code snippets
Example to re-produce:

from typing import Annotated

from a2a.types import Message
from a2a.utils.message import get_message_text
from agentstack_sdk.a2a.extensions.ui.form import (
    FormExtensionServer,
    FormExtensionSpec,
    FormRender,
    OptionItem,
    SingleSelectField,
)
from agentstack_sdk.a2a.extensions.ui.settings import (
    OptionItem,
    SettingsExtensionServer,
    SettingsExtensionSpec,
    SettingsRender,
    SingleSelectField,
)
from agentstack_sdk.server import Server
from pydantic import BaseModel

server = Server()



class ContactInfo(BaseModel):
    contact_method: str | None
   

vector_store_doctype_select = SingleSelectField(
    id="vector_store_doc_type",
    options=[
        OptionItem(value="sql_query", label="SQL Queries"),
        OptionItem(value="question", label="Questions"),
        OptionItem(value="both", label="Both"),
    ],
    default_value="sql_queries",
    label="Vector Store Doc Type"
)


@server.agent()
async def dynamic_form_agent(
    message: Message,
    form_request: Annotated[FormExtensionServer, FormExtensionSpec(params=None)],
    settings: Annotated[SettingsExtensionServer, SettingsExtensionSpec(
        params=SettingsRender(
            fields=[vector_store_doctype_select]
        )
    )]
):
    """Agent that requests forms dynamically during conversation"""

    user_input = get_message_text(message)

    # Check if user wants to provide contact information
    if "contact" in user_input.lower() or "reach" in user_input.lower():
        # Request contact form dynamically
        contact_info = await form_request.request_form(
            form=FormRender(
                title="Please provide your contact information",
                columns=2,
                fields=[
                    SingleSelectField(
                        id="contact_method",
                        label="Preferred Contact Method",
                        col_span=2,
                        required=False,
                        options=[
                            OptionItem(id="email", label="Email"),
                            OptionItem(id="phone", label="Phone"),
                            OptionItem(id="sms", label="SMS"),
                            OptionItem(id="none", label="Do not contact"),
                        ],
                        default_value="email",
                    )
                ],
                model=ContactInfo
            )
        )

        if contact_info is None:
            yield "No contact information received."
        else:
            yield f"Thank you! I'll contact you at {contact_info.email} or {contact_info.phone} regarding {contact_info.company}."
    else:
        yield "Hello! If you'd like me to contact you, just let me know and I'll ask for your details."


if __name__ == "__main__":
    server.run()

[dosubot]

Hi @jpwsutton! I'm Dosu and I’m helping the agentstack team.

The clash happens because both the settings and form modules define their own SingleSelectField and OptionItem classes, but with different schemas: settings uses OptionItem with label/value, while form uses OptionItem with id/label, and their SingleSelectField types also differ in structure and validation logic. When you import both into the same file without aliasing, Python overwrites the first with the second, so Pydantic and mypy see the wrong schema, causing type and runtime errors. Aliasing the imports (e.g., OptionItem as SettingsOptionItem) is the correct workaround to avoid this collision.

There’s significant overlap between the two, but also key differences, which is why simply adding missing fields doesn’t work and leads to validation errors. A recent major rework of the form extension introduced breaking changes and a migration guide, but there’s no indication that unifying the settings and form field classes is planned or underway—aliasing remains the best practice for now. If you’d like to see these unified, it could be worth proposing as a feature request, since the overlap is clear and the pain points are real for users working with both in the same agent file.

References:

• Settings module definitions
• Form module definitions
• Recent form extension rework PR

To reply, just mention @dosu.

---

^{How did I do? Good | Irrelevant | Incorrect | Verbose | Hallucination | Report 🐛 | Other}

   

[tomkis]

@jpwsutton

However, I think longer term, it might be worth combining the Settings and Form classes into a single common form class as there is so much overlap between the two.

This is exactly the long term goal we are trying to achieve. In fact, we are even considering unifiying the extnesion.

[PetrBulanek]

@tomkis Do we plan to address this in the near future?

[tomkis]

Closing this in favour of #1863