Running an agent
The bot calls execAgent with the agent name and the person's question. The question goes in inputs under the name query.
{ "agentName": "hr_policy",
"inputs": { "query": "how much vacation have I accrued" },
"convid": "…" }Leave convid out to start a conversation. The response carries the new identifier. Pass that identifier on every later call to continue the same conversation. Leave the field out altogether rather than sending an empty string, which is rejected.
Threads and conversations
A chat application identifies a thread in its own way. Slack uses a workspace, a channel and the timestamp of the first message. Teams and Google Chat each have their own identifiers.
The bot keeps its own record of which thread belongs to which conversation. It writes the record when a conversation is created and reads it on every later message in that thread. Search2o holds no link to the chat application.
How a run ends
The response carries a result code. A bot handles four cases.
| Result | What the bot does |
|---|---|
success | The run finished. Show the output; see Showing the answer. |
ask | The agent is asking for input. See below. |
unknownConversation | The conversation is no longer known. Forget the stored identifier, start a new conversation, and continue. This is not an error to report. |
| Anything else | The run failed. Tell the person, using error.message when there is one. |
When an agent asks a question
An agent can pause and ask the person for input. The response then carries one or more blocks, each a form of its own: the message to show and the list of inputs to collect. An agent usually sends one block; an agent whose parallel branches asked sends one block per branch. Each input has a type: a line of text, a password, a longer block of text, a choice of one, or a choice of several. Every chat application can render all five in a form, and several blocks as several sections of one form.
Collect the answers and call execAgent again with the same convid and the answers as inputs, under the block's key, as input name to answer; see Answering an ask. The agent continues from where it paused. An input marked as hidden is not shown to the person; send it back unchanged. See the ask command.
Slack needs one extra step. A form there opens only in response to a click, and the ask arrives while the bot is handling a message event. Post a message with an Answer button, and open the form when that button is pressed.
Slow answers
Every chat application expects the bot to acknowledge an event quickly. Slack allows about three seconds; Microsoft Teams and Google Chat allow longer. Whatever the figure, an agent that calls a model usually answers in about five seconds and sometimes takes a minute or more, so no window covers it.
The pattern is the same on all three. Acknowledge the event at once. Post a short message saying the answer is coming. Post or edit the real answer when it arrives.
Each application has its own way to send that later message. In Slack, post a message and edit it with chat.update. In Teams, keep the conversation reference and send a proactive message, or update the activity. In Google Chat, create a message in the space with the Chat API. All three also have a typing or progress indicator to use while the person waits.
When a conversation turns out to have expired, the bot starts a new one and runs the question again. Reuse the message already posted rather than posting another. Otherwise the person sees two messages saying an answer is coming, for one question.
The agent server can stream progress while an agent runs, and a bot can use the progress to update the message it posted. Keep an unfinished stream open: closing it stops the agent.