Search behavior
A search returns the agents that match a query, best first. What an interface does with those matches, run the best one at once or show them for the user to choose from, is the interface's own behavior, not an account setting. The bundled UI takes it from the agent server's configuration; an interface of your own decides for itself.
What an interface can do with the matches
A search returns one or two agents, or none; see How matching behaves. The interface then chooses how to act:
| Behavior | What happens |
|---|---|
| Run the best match | The top agent runs at once. The fastest path, and it never asks the user to choose. |
| Run only a lone match | A single match runs at once. When two come back, they are offered as a choice. |
| Show the matches | The matches are always shown and the user chooses. Nothing runs until the user chooses. |
When nothing matches, the interface says so rather than running anything.
Follow-ups
A follow-up is a query typed into a conversation that already exists. An interface can search it like a new query and keep the agent that answered last as a fallback or among the choices, or it can keep the whole conversation on the agent that started it. See Follow-ups.
The bundled UI
The UI reads its behavior from the uiConfig object of the agent server configuration it is served by, so each agent server in an account can behave differently. By default the best match runs at once, and a follow-up is searched again with the previous agent as the fallback. A change takes effect when the agent server restarts and each user reloads the UI.
search.searchBehavior, for a new search:
| Value | What happens |
|---|---|
executeTopMatch | Run the best match. The default. |
executeOnlyMatch | Run only a lone match. |
showResults | Show the matches, even when only one matched. |
search.followupBehavior, for a follow-up in a conversation. The previous agent is the one that answered last:
| Value | What happens |
|---|---|
executeTopMatch | Run the best match. When nothing matches, the previous agent runs. The default. |
executeOnlyMatch | Run only a lone match. When two come back, the user chooses, with the previous agent offered alongside them. When nothing matches, the previous agent runs. |
showResults | Show the matches, with the previous agent offered alongside them. The user chooses. |
executePrevious | Always run the previous agent. Nothing is searched. |
search.tag is sent with every search the UI makes, follow-ups included. Empty searches every tag. See Tags.
Your own interface
The search call returns only the ranked matches. What a chat integration, an agent skill or a client of your own runs is its choice. A chat bot that always runs the best match feels like a conversation. One that shows the matches feels like a search page. Either works, as long as it stays consistent.