Collect Input with Forms

One of the most powerful features of the Agent Stack is the ability to request structured data from users through interactive forms. Instead of relying on free-form text input, your agent can present users with specific fields, dropdowns, and other form elements to gather precise information. The Agent Stack provides a Form extensions that allows you to collect structured data from users in two ways:

Initial form rendering - Present a form as the first interaction before users start a conversation with your agent
Dynamic form requests - Request forms at any point during a multi-turn conversation when your agent needs specific structured input

Initial Form Rendering

For initial form rendering, you specify the form structure when injecting the extension and then parse the response using a Pydantic model. The form is presented to users before they start a conversation with your agent.

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

import os
from typing import Annotated

from a2a.types import Message
from agentstack_sdk.a2a.extensions import (
    FormRender,
    TextField,
    FormServiceExtensionServer,
    FormServiceExtensionSpec,
)
from agentstack_sdk.server import Server
from pydantic import BaseModel

server = Server()

class UserInfo(BaseModel):
    first_name: str | None
    last_name: str | None

@server.agent()
async def initial_form_rendering_example(
    _message: Message,
    form: Annotated[
        FormServiceExtensionServer,
        FormServiceExtensionSpec.demand(
            initial_form=FormRender(
                title="Welcome! Please tell us about yourself",
                columns=2,
                fields=[
                    TextField(id="first_name", label="First Name", col_span=1),
                    TextField(id="last_name", label="Last Name", col_span=1),
                ],
            )
        ),
    ],
):
    """Agent that collects user information through an initial form"""
    
    # Parse the form data using a Pydantic model
    user_info = form.parse_initial_form(model=UserInfo)
    
    if user_info is None:
        yield "No form data received."
    else:
        yield f"Hello {user_info.first_name} {user_info.last_name}! Nice to meet you."


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

if __name__ == "__main__":
    run()

Import the form extension

Import FormServiceExtensionServer, FormServiceExtensionSpec, FormRender, and field types from the Agent Stack SDK.

Define your form data model

Create a Pydantic model with fields matching your form field IDs.

Add form parameter to your agent

Inject the form extension into your agent function using FormServiceExtensionSpec.demand(initial_form=FormRender(...)).

Parse form data

Call form.parse_initial_form(model=YourModel) to extract the submitted form data.

Dynamic Form Requests

For dynamic form requests during conversation, you can request forms at any point when your agent needs structured input. This is useful when your agent needs to collect additional information based on the conversation flow.

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

import os
from typing import Annotated

from a2a.types import Message
from a2a.utils.message import get_message_text
from agentstack_sdk.a2a.extensions import (
    FormRender,
    TextField,
    FormRequestExtensionServer,
    FormRequestExtensionSpec,
)
from agentstack_sdk.server import Server
from pydantic import BaseModel

server = Server()


class ContactInfo(BaseModel):
    email: str | None
    phone: str | None
    company: str | None


@server.agent()
async def dynamic_form_requests_example(
    message: Message,
    form_request: Annotated[
        FormRequestExtensionServer,
        FormRequestExtensionSpec(),
    ],
):
    """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=[
                    TextField(id="email", label="Email Address", col_span=2),
                    TextField(id="phone", label="Phone Number", col_span=1),
                    TextField(id="company", label="Company", col_span=1),
                ],
            ),
            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."


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


if __name__ == "__main__":
    run()

Import the request form extension

Import FormRequestExtensionServer, FormRequestExtensionSpec, FormRender, and field types from the Agent Stack SDK.

Define your form data model

Create a Pydantic model with fields matching your form field IDs.

Add request form parameter to your agent

Inject the request form extension into your agent function using FormRequestExtensionSpec().

Request form dynamically

Call await form_request.request_form(form=FormRender(...), model=YourModel) when you need to collect structured input.

How to work with forms

Here’s what you need to know to add form capabilities to your agent: Import the form components:

For form fields and FormRender, import from agentstack_sdk.a2a.extensions
For initial forms, import FormServiceExtensionServer and FormServiceExtensionSpec from agentstack_sdk.a2a.extensions
For dynamic forms, import FormRequestExtensionServer and FormRequestExtensionSpec from agentstack_sdk.a2a.extensions

Inject the extension: Add a form parameter to your agent function using the Annotated type hint. For initial forms: Use FormServiceExtensionSpec.demand(initial_form=FormRender(...)) to specify the form structure and call form.parse_initial_form(model=YourModel) to extract data. For dynamic forms: Use FormRequestExtensionSpec() and call await form_request.request_form(form=FormRender(...), model=YourModel) when needed. Access form data: The recommended approach is to use a Pydantic model (or TypedDict, dataclass, or any class supported by pydantic.TypeAdapter) to load form data. Define a model with fields matching your form field IDs:

from pydantic import BaseModel

class ContactInfo(BaseModel):
    email: str | None
    phone: str | None
    company: str | None

Then, pass model=ContactInfo to parse_initial_form(...) or request_form(...) to get the form data directly as an instance of ContactInfo:

# For initial forms
contact_info: ContactInfo | None = form.parse_initial_form(model=ContactInfo)

# For dynamic forms
contact_info: ContactInfo | None = await form_request.request_form(
    form=FormRender(...),
    model=ContactInfo
)

If you don’t use a model, the methods return FormResponse which has a values dictionary. You can access values using form_data.values['field_id'].value. Different field types return different value types:

Field Type	Return Type	Notes
TextField	`str \| None`
DateField	`str \| None`
FileField	`list[FileInfo] \| None`	Each `FileInfo` has `uri`, `name`, and `mime_type`
SingleSelectField	`str \| None`	Selected option ID
MultiSelectField	`list[str] \| None`	List of selected option IDs
CheckboxField	`bool \| None`

Form Field Types

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

TextField

Basic text input fields for collecting strings, names, descriptions, etc.

from agentstack_sdk.a2a.extensions import TextField

TextField(
    id="username", 
    label="Username", 
    col_span=1,
    required=True,
    placeholder="Enter your username",
    default_value="",
    type="text"  # Optional, defaults to "text"
)

DateField

Date input fields for collecting dates and timestamps.

from agentstack_sdk.a2a.extensions import DateField

DateField(
    id="birth_date", 
    label="Birth Date",
    col_span=1,
    required=True,
    placeholder="YYYY-MM-DD",
    default_value="1990-01-01"
)

FileField

File upload fields for collecting files from users.

from agentstack_sdk.a2a.extensions import FileField

FileField(
    id="document", 
    label="Upload Document",
    col_span=2,
    required=True,
    accept=["application/pdf", "image/jpeg", "image/png"]
)

SingleSelectField

Single-select dropdown fields for choosing single option from a list.

from agentstack_sdk.a2a.extensions import OptionItem, SingleSelectField

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"
)

MultiSelectField

Multi-select dropdown fields for choosing multiple options from a list.

from agentstack_sdk.a2a.extensions import OptionItem, MultiSelectField

MultiSelectField(
    id="interests", 
    label="Your Interests",
    col_span=2,
    required=False,
    options=[
        OptionItem(id="tech", label="Technology"),
        OptionItem(id="sports", label="Sports"),
        OptionItem(id="music", label="Music"),
        OptionItem(id="travel", label="Travel")
    ],
    default_value=["tech", "music"]
)

CheckboxField

Single checkbox fields for boolean values.

from agentstack_sdk.a2a.extensions import CheckboxField

CheckboxField(
    id="newsletter", 
    label="Subscribe to Newsletter", 
    col_span=1,
    required=False,
    content="I agree to receive marketing emails",
    default_value=False
)

Form Layout Configuration

Control how your form appears using the FormRender configuration:

from agentstack_sdk.a2a.extensions import FormRender

FormRender(
    title="Form Title",
    description="Optional description text below the title",
    columns=2,  # Number of columns in the form grid
    submit_label="Custom Submit Button Text",
    fields=[
        # Your field definitions here
    ]
)

FormRender properties:

Property	Description
`title`	Main heading displayed above the form (optional)
`description`	Optional description text displayed below the title
`columns`	Number of columns in the form grid (1-4, optional)
`submit_label`	Custom text for the submit button (optional, default: “Submit”)
`fields`	List of form field definitions (required)

Use col_span on individual fields to control how they span across the grid. For example, with columns=2, a field with col_span=2 will take the full width, while col_span=1 will take half the width.

Examples

For more examples, see:

Introduction

Deploy Agents

Agent Integration

Reference

Deploy Agent Stack

Custom UI Integration

Experimental

Community

Collect Input with Forms

Initial Form Rendering

Dynamic Form Requests

How to work with forms

Form Field Types

TextField

DateField

FileField

SingleSelectField

MultiSelectField

CheckboxField

Form Layout Configuration

Examples

​Initial Form Rendering

​Dynamic Form Requests

​How to work with forms

​Form Field Types

​TextField

​DateField

​FileField

​SingleSelectField

​MultiSelectField

​CheckboxField

​Form Layout Configuration

​Examples

Initial Form Rendering

Dynamic Form Requests

How to work with forms

Form Field Types

TextField

DateField

FileField

SingleSelectField

MultiSelectField

CheckboxField

Form Layout Configuration

Examples