> ## 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](/ko/prompts.md)
- [세션 훅](/ko/packages/laravel-copilot-sdk/hooks.md)
- [Artisan 콘솔](/ko/artisan.md)
- [Add User Dict Word](/ko/packages/laravel-voicevox/engine-api/user-dictionary/add-user-dict-word.md)
- [Import User Dict Words](/ko/packages/laravel-voicevox/engine-api/user-dictionary/import-user-dict-words.md)