User Feedback

UserFeedbackTools lets an agent pause and ask the user structured questions with predefined options.

UserFeedbackTools exposes a single ask_user tool. The agent presents structured questions with predefined options (single or multi-select), the run pauses, and execution resumes once the user provides their selections. This is a human-in-the-loop pattern for clarifying intent mid-run.

Example

1from kern.agent import Agent
2from kern.db.sqlite import SqliteDb
3from kern.models.openai import OpenAIResponses
4from kern.tools.user_feedback import UserFeedbackTools
5
6agent = Agent(
7    model=OpenAIResponses(id="gpt-5.4"),
8    tools=[UserFeedbackTools()],
9    instructions=[
10        "You are a helpful travel assistant.",
11        "When the user asks you to plan a trip, use the ask_user tool to clarify their preferences.",
12    ],
13    db=SqliteDb(db_file="tmp/user_feedback.db"),
14    markdown=True,
15)
16
17run_response = agent.run("Help me plan a vacation")

Resolving the Pause

When the agent calls ask_user, the run pauses with a user_feedback_schema. Collect the user's selections and continue the run:

1while run_response.is_paused:
2    for requirement in run_response.active_requirements:
3        if requirement.needs_user_feedback:
4            selections = {}
5            for question in requirement.user_feedback_schema:
6                # present question.header, question.question, question.options
7                # collect selected option labels (multi if question.multi_select)
8                selections[question.question] = [...]
9            requirement.provide_user_feedback(selections)
10
11    run_response = agent.continue_run(
12        run_id=run_response.run_id,
13        requirements=run_response.requirements,
14    )

Question Schema

ask_user accepts a list of AskUserQuestion objects:

Field	Type	Description
`question`	`str`	The question. Must end with a question mark.
`header`	`str`	Short label (max 12 chars), e.g. `"Destination"`.
`options`	`List[AskUserOption]`	2-4 options to choose from.
`multi_select`	`bool`	If True, the user can select multiple options.

Each AskUserOption has a label (1-5 words) and an optional description.

Toolkit Params

Parameter	Type	Default	Description
`instructions`	`Optional[str]`	defaults	Override the default LLM instructions.
`add_instructions`	`bool`	`True`	Add the instructions to the agent's system message.

User Feedback

Example

Resolving the Pause

Question Schema

Toolkit Params

Developer Resources