Running agents

POST /api/exec/execAgent runs a named agent. The call returns when the agent finishes, or streams the run as it happens.

The request

Field	Meaning
`agentName`	The agent to run.
`inputs`	A JSON object. The agent reads it as `sys.inputs`. The value under `query` is what the agent reads as `sys.query`; the search box sends the user's text there.
`convid`	Leave it out to start a new conversation. Send the id from an earlier response to continue that conversation.
`stream`	`false` (the default) returns one response when the agent finishes. `true` streams the run; see Streaming.

$ curl -s -X POST http://127.0.0.1:9020/api/exec/execAgent \
    -H "Authorization: Bearer $SEARCH2O_SERVICE_KEY" -H "Content-Type: application/json" \
    -d '{"agentName": "morning_briefing",
         "inputs": {"query": "what changed overnight", "team": "payments"}}'

The response

Field	Meaning
`resultCode`	How the run ended; the values are listed below.
`convid`	The conversation. Send it back to continue.
`agentName`	The agent that ran.
`output`	The agent's output: `agentName` and `parts`, a list of parts. A part is text (Markdown), html, or an image with a `mimeType`. Present only when the call did not stream.
`askInput`	Present when the agent paused on `ask`: one or more blocks, each with a message and the list of inputs to collect. See below.
`error`	Present when the run failed: `message`, written to be shown to the user, and `path`, the command where the error happened, when there is one.

Result codes

Value	Meaning
`success`	Agent completed successfully (Not included in error report)
`ask`	Agent ended in a ask command (Not included in error report)
`callFailed`	Call to an external system failed
`failCommand`	Agent ended with a fail command
`errorInAgent`	Agent has some coding error
`unknownConversation`	Conversation is unknown or expired, or it is paused on an ask by a different agent
`timedOut`	Agent timed out, based on the max agent runtime setting
`stopped`	User cancelled the agent execution
`mustLogin`	Session timed out in the middle of an agent execution
`unexpected`	An unknown exception was raised in the agent

success and ask are the two normal endings. Every other code is recorded in the error report. A client receives unknownConversation when the conversation is unknown or has expired, when it is paused on an ask by a different agent, or when the agent that asked has been republished since, so the answers can no longer be used. The message says which. Start a new conversation.

Answering an ask

When resultCode is ask, the agent has paused. askInput is a dictionary of blocks. A block is one form: a message to show and inputs, the list of inputs to collect. Each input has a name, a type, a label, a description, the options and a default. The types are str, password, text, chooseOne and chooseMany.

An agent that asked outside a parallel command sends one block, under the key ask_. An agent whose parallel branches asked sends one block per branch, keyed by the branch's name in the command, such as askme and askme.2. A branch that ran a parallel command of its own nests its blocks under its key. A block is distinguished from a nested group by its inputs value, which is a list.

An ask outside a parallel command

{ "success": true, "convid": "7mMA1nl1QmwwGw1teIQe3r", "agentName": "travel_booking",
  "resultCode": "ask",
  "askInput": {
    "ask_": {
      "message": "A few details to book the trip:",
      "inputs": [
        { "name": "departure", "type": "str", "label": "Departure city", "description": "",
          "options": [], "default": null, "hidden": false },
        { "name": "seat", "type": "chooseOne", "label": "Seat", "description": "",
          "options": ["aisle", "window"], "default": "aisle", "hidden": false } ] } } }

Collect the answers. Then call execAgent again with the same agentName and convid, and the answers as inputs under the same keys: one dictionary of input name to answer per block. The agent resumes at the ask command, or at every paused branch when the blocks came from a parallel command. Answers sent without their block key are not applied, and the same ask is returned again. The pause survives any delay: the answers may arrive the next day, from another client.

$ curl -s -X POST http://127.0.0.1:9020/api/exec/execAgent \
    -H "Authorization: Bearer $SEARCH2O_SERVICE_KEY" -H "Content-Type: application/json" \
    -d '{"agentName": "travel_booking", "convid": "'$CONVID'",
         "inputs": {"ask_": {"departure": "Boston", "seat": "aisle"}}}'

Two blocks from a parallel command can be answered together or one at a time: the agent asks again for the blocks it did not receive, and keeps the answers it did. A hidden input is sent back unchanged, inside its block.

Answering two branches at once

{ "agentName": "city_lookup", "convid": "55Di6Y8xy3KKozbwDsUOAc",
  "inputs": { "askme": { "city": "Paris" }, "askme.2": { "city": "Oslo" } } }

Continuing a conversation

A call with a convid restores the conversation's state before the agent runs: agent and conversation variables and the prompt history. The agent named in the call does not need to be the one that ran before; a conversation moves from one agent to another, as it does after a follow-up search. A conversation expires 7 days after its last use, unless the user pinned it. The paid service has no such limit.

Validating a draft

POST /api/dev/validateDraftStream runs a developer's draft against its validation query, with tracing on. The request names the draftid and takes the same inputs and stream fields. The response adds validationSuccess, validationErrors and runtimeError to the fields above. The UI's validation view is this call with stream: true. An ask during validation arrives as the same blocks, and a call with followup: true and the answers in inputs continues the run.