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. Please leave the field out altogether rather than sending an empty convid.

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. The bot writes the record when a conversation is created and reads the record 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.

Conversations expire, so a stored identifier that is no longer known is ordinary and expected.

When an agent asks a question

An agent can pause and ask the person for input. The response then carries the message to show and the list of inputs to collect. 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.

Collect the answers and call execAgent again, with the same convid and the answers as inputs, keyed by input name. 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 can only be opened in response to a click, and the answers arrive while the bot is replying to a message. The usual way round it is a message with an Answer button, with the form opening when that button is pressed.

Slow answers

Every chat application expects the app to acknowledge an event quickly. Slack allows about three seconds. Microsoft Teams allows longer, and Google Chat longer still. It is worth checking the current figure for the application you are building against, because each vendor changes it.

We would suggest not building against that figure. An agent that calls a model usually answers in about five seconds, and sometimes takes a minute or more. No window covers that.

The pattern is therefore 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 the answer 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 worth using 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. Please leave an unfinished stream open: closing it stops the agent.