Collect Data

The collect data tool puts a form in front of the user during a chat, so an agent can gather structured information before it carries on with a task.

Tool: `collect_data`

Returns a form definition. It does not wait for the user and returns no answers itself: the Chat screen sees the definition, shows the form, and when the user submits it, their answers arrive as the next user message in the conversation.

Arguments

Argument	Type	Description
`fields`	array	The fields to show (required)

Field definition

Property	Type	Required	Description
`label`	string	Yes	The question shown to the user
`type`	string	Yes	`text`, `number`, `email`, `date`, `phone` or `options`
`options`	array of strings	For `options`	The choices, shown as buttons
`multiple`	boolean	No	Allow several choices (`options` only)

There is no field name, title, placeholder or required flag. Answers are identified by their label, so give each field a distinct one.

Use cases

Before I run the report, I need to collect some parameters from you.

Please fill in your project details so I can set up the repository.

I need a few details to book the meeting. Let me show you a form.

Example

{
  "tool": "collect_data",
  "arguments": {
    "fields": [
      {
        "label": "Date Range",
        "type": "options",
        "options": ["last_7_days", "last_30_days", "last_quarter"]
      },
      { "label": "Send report to", "type": "email" },
      {
        "label": "Include charts?",
        "type": "options",
        "options": ["yes", "no"]
      }
    ]
  }
}

The user sees the form in Chat. After they submit it, the agent receives a plain-text message with each label and answer:

Date Range: last_30_days, Send report to: alice@example.com, Include charts?: yes

With a single field, the message is just the answer. Several choices from a multiple field are joined with commas.

Where the form appears

Only the Chat screen renders the form. Through the API, a messaging channel or a chat widget there is no form — the caller just sees the agent's reply. Use it for agents people talk to in Chat.

Integration with workflows

In a workflow, use a Human step to collect input partway through a run — the run pauses, is checkpointed, and resumes when someone answers. Use collect_data for lightweight, in-conversation data gathering in Chat.