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`	Omit 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 $TOKEN" -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 as a list of parts: text (Markdown), html, or image with a `mimeType`. Present only when the call did not stream.
`askInput`	Present when the agent paused on `ask`: a message and the list of inputs to collect. See below.

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. unknownConversation is what a client receives when the conversation is unknown or has expired, or when it is paused on an ask recorded by a different agent.

Answering an ask

When resultCode is ask, the agent has paused. askInput.inputs lists the inputs. 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. Collect the answers. Then call execAgent again with the same agentName and convid, and the answers as inputs, keyed by input name. The agent resumes at the ask command. 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 $TOKEN" -H "Content-Type: application/json" \
    -d '{"agentName": "travel_booking", "convid": "'$CONVID'", "inputs": {"departure": "Boston", "seat": "aisle"}}'

Continuing a conversation

A call with a convid restores the conversation's state before the agent runs, so agent and conversation variables and prompt history are available. The agent named in the call need not be the agent that ran before; a conversation can move from one agent to another, as it does after a follow-up search. A conversation expires after its last use, 7 days on the Free plan and 90 days on Paid, unless the user pinned it.

Validating a draft

POST /api/dev/validateDraftStream runs a developer's draft against its validation query, with tracing on. The request names the draftid; the response adds validationSuccess, compileErrors and runtimeError to the fields above. The GUI's validation view is this call with stream: true.