> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask user

> 使用 Laravel Copilot SDK 的 onUserInputRequest 处理器，响应通过 ask_user 工具向用户发起的提问。

## 用户输入请求

配置 `onUserInputRequest` 处理器后，代理就可以通过 `ask_user` 工具向用户提问。

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Types\UserInputRequest;
use Revolution\Copilot\Types\UserInputResponse;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: '请询问用户喜欢的语言');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'onUserInputRequest' => function (UserInputRequest $request): UserInputResponse {
        // $request->question - 问题内容
        // $request->choices - 多选选项数组（可选）
        // $request->allowFreeform - 是否允许自由输入（默认: true）

        dump("Question from agent: {$request->question}");
        if ($request->choices) {
            dump('Choices: '.implode(', ', $request->choices));
        }

        // 返回用户的回答
        return new UserInputResponse(
            answer: 'PHP',
            wasFreeform: true, // 是否是自由输入而非从选项中选择
        );
    },
]);
```

## UserInputRequest 类

来自代理的用户输入请求。

| 属性              | 类型       | 说明                   |
| --------------- | -------- | -------------------- |
| `question`      | `string` | 向用户提出的问题             |
| `choices`       | `?array` | 多选时的选项（可选）           |
| `allowFreeform` | `?bool`  | 是否允许自由输入（默认: `true`） |

## UserInputResponse 类

对用户输入请求的响应。

| 属性            | 类型       | 说明                         |
| ------------- | -------- | -------------------------- |
| `answer`      | `string` | 用户的回答                      |
| `wasFreeform` | `bool`   | 回答是否是自由输入（不是来自选项时为 `true`） |

## 实用示例

在交互式命令中使用的情形。

```php theme={null}
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Types\UserInputRequest;
use Revolution\Copilot\Types\UserInputResponse;

// 在 Artisan 命令内
Copilot::start(function (CopilotSession $session) use ($command) {
    $response = $session->sendAndWait(prompt: '进行项目配置');
    $command->info($response->content());
}, config: [
    'onUserInputRequest' => function (UserInputRequest $request) use ($command): UserInputResponse {
        if ($request->choices) {
            // 有选项时使用 choice 方法
            $answer = $command->choice(
                $request->question,
                $request->choices,
                $request->choices[0] ?? null
            );

            return new UserInputResponse(answer: $answer, wasFreeform: false);
        }

        // 自由输入
        $answer = $command->ask($request->question);

        return new UserInputResponse(answer: $answer, wasFreeform: true);
    },
]);
```

<Info>
  最新信息请参考 [GitHub 仓库](https://github.com/invokable/laravel-copilot-sdk)。
</Info>


## Related topics

- [Laravel Prompts](/zh/prompts.md)
- [会话钩子](/zh/packages/laravel-copilot-sdk/hooks.md)
- [Artisan 控制台](/zh/artisan.md)
- [Import User Dict Words](/zh/packages/laravel-voicevox/engine-api/user-dictionary/import-user-dict-words.md)
- [Add User Dict Word](/zh/packages/laravel-voicevox/engine-api/user-dictionary/add-user-dict-word.md)