Feat(sdk, cli): 1998 extend form extension for settings

[jjeliga]

Summary

Moving the settings extension under form.
Extending FormServiceExtensionSpec to demand either form or settings or both.
Extending FormServiceExtensionServer to allow settings parsing.
Allowing only CheckboxGroupField and SingleSelectField to be used for settings to be aligned with the ui.
Deprecating the old settings, but keeping them for now to allow compatibility with older agents.
Modifying cli agent run cmd to be able to work with both the new and deprecated settings.
Including examples using both old and new method.
Updated docs.

Linked Issues

Closes #1998

Documentation

• No Docs Needed:

If this PR adds new feature or changes existing. Make sure documentation is adjusted accordingly. If the docs is not needed, please explain why.

[gemini-code-assist]

Summary of Changes

Hello @jjeliga, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request refactors the agent settings mechanism by integrating it directly into the existing form extension. This change aims to provide a more unified and consistent approach for agents to define and interact with user-configurable options, whether they are initial forms or agent settings. It introduces new API constructs for settings under the form extension, deprecates the old standalone settings extension, and ensures backward compatibility for existing agents through updated CLI handling.

Highlights

• Settings Extension Integration: The existing UI settings extension has been integrated into the common form extension, centralizing form and settings handling for a more unified approach.
• New API for Settings: New SettingsFormRender and SettingsFormResponse classes have been introduced within agentstack_sdk.a2a.extensions.common.form to define and process agent settings using the form extension framework.
• Deprecation of Old Settings: The agentstack_sdk.a2a.extensions.ui.settings module and its components are now officially deprecated, with clear @deprecated annotations added to guide developers towards the new form-based approach.
• Backward Compatibility: The CLI agent run command has been updated to intelligently support both the new form-based settings and the deprecated legacy settings, ensuring compatibility with older agents during the transition period.
• Limited Field Types for Settings: Only CheckboxGroupField and SingleSelectField are permitted for use in the new SettingsFormRender, aligning with the intended UI capabilities for agent settings.
• Enhanced Form Service Spec: FormServiceExtensionSpec now includes demand_settings and demand_forms class methods, allowing agents to explicitly demand settings forms or a combination of initial forms and settings forms.
• Updated Documentation and Examples: The documentation (agent-settings.mdx) and example agents have been thoroughly updated to reflect the new settings integration, including a new settings_agent_legacy.py example to demonstrate the deprecated settings usage.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• apps/agentstack-cli/src/agentstack_cli/commands/agent.py
  • Added imports for new form-based settings types (SettingsFormFieldValue, SettingsFormRender, SettingsFormResponse).
  • Introduced _ask_settings_form_questions for handling new settings interactions.
  • Implemented _get_settings_from_agent_card to dynamically determine and retrieve settings based on legacy or new format.
  • Updated _run_agent to accept both legacy and new settings types and correctly serialize them.
  • Modified run_agent to use the new settings detection and question-asking logic.
• apps/agentstack-cli/uv.lock
  • Added typing-extensions dependency.
• apps/agentstack-sdk-py/examples/settings_agent.py
  • Migrated example to use the new form-based settings API (FormServiceExtensionSpec.demand_settings, SettingsFormRender, form.parse_settings_form).
  • Updated field definitions to align with common.form types (e.g., OptionItem now uses id).
• apps/agentstack-sdk-py/examples/settings_agent_legacy.py
  • Added a new example file demonstrating the use of the deprecated settings extension for backward compatibility.
• apps/agentstack-sdk-py/pyproject.toml
  • Added typing-extensions dependency.
• apps/agentstack-sdk-py/src/agentstack_sdk/a2a/extensions/common/form.py
  • Introduced CheckboxGroupField and CheckboxGroupFieldValue into the common form types.
  • Defined SettingsFormField, SettingsFormFieldValue, SettingsFormRender, and SettingsFormResponse for specialized settings forms.
• apps/agentstack-sdk-py/src/agentstack_sdk/a2a/extensions/services/form.py
  • Extended FormDemands to include settings_form as an optional field.
  • Updated FormServiceExtensionMetadata to support SettingsFormResponse in form_fulfillments.
  • Added demand_settings and demand_forms class methods to FormServiceExtensionSpec for requesting settings or combined forms.
  • Implemented parse_settings_form method in FormServiceExtensionServer for extracting settings data.
• apps/agentstack-sdk-py/src/agentstack_sdk/a2a/extensions/ui/settings.py
  • Marked all classes and methods related to the old UI settings extension as @deprecated.
  • Updated SettingsRender to use Annotated and Field(discriminator="type") for better type handling.
• apps/agentstack-sdk-py/uv.lock
  • Added typing-extensions dependency.
• apps/agentstack-server/uv.lock
  • Added typing-extensions dependency.
• docs/development/agent-integration/agent-settings.mdx
  • Updated documentation to reflect the new form-based settings integration, including quickstart steps, examples, and detailed explanations.
  • Removed references to the old settings extension and updated code snippets to use the new API.
  • Added a note about combining settings with initial forms and the allowed field types for settings.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request refactors the agent settings to be part of the form extension, which is a good architectural improvement. It introduces a new API for settings while maintaining backward compatibility with the old one. The changes are well-structured, and the documentation and examples have been updated accordingly. I've identified one area of code duplication in the CLI command that could be refactored to improve maintainability.

[jjeliga]

I know these imports look weird, but that is the work of ruff. No-harm as it will be deleted soon

[JanPokorny]

We switched to pyrefly in the meantime, can you rebase, remove # pyright comments and run mise check to verify?