Agents

Create agent run

Changed on

Execute an agent run. By default, set stream to true to receive server-sent events; otherwise the response contains the final agent messages. Set execution_mode to DURABLE to persist a new run and return its initial snapshot with HTTP 201 without waiting for execution. Poll the agent-scoped GET run endpoint for progress. Durable execution continues after an HTTP disconnect, but is not automatically resumed after a QE restart or crash. An active turn becomes overdue more than 40 minutes after acceptance (a 30-minute execution timeout plus 10 minutes of grace). The next GET of the run marks the overdue turn FAILED without replay; there is no periodic sweep. Without a GET, the stored run can remain RUNNING. Failure does not prove that external tool work has stopped. Paused runs are not expired; an accepted approval continuation starts a fresh deadline. Each POST creates a new run; retrying a POST can create another execution. Submit pending approval decisions through the run responses endpoint, and cancellation can be requested through the run cancellations endpoint. A run tracks one workflow execution; automatic background-subagent wake turns are separate executions, not continuations tracked by this run ID.

post/api/agents/{agent_id}/runs

Request

  • Base URL: https://instance-name-be.glean.com
  • URL: https://instance-name-be.glean.com/api/agents/{agent_id}/runs
  • Auth: HTTP bearer

Path parameters

agent_idstring required

ID of the agent to run.

Request body

inputobject

Input fields for an input-form triggered agent.

metadataobject

Metadata to pass to the agent.

streamboolean

Whether to stream the run response as server-sent events. Not supported in DURABLE mode.

execution_mode'REQUEST_BOUND' | 'DURABLE'

REQUEST_BOUND preserves the existing wait/stream behavior. DURABLE starts a fresh, persisted execution with a 30-minute execution timeout and returns immediately. DURABLE requires stream to be false or omitted and does not accept metadata.chat_session_id. It does not bypass tool approval requirements or provide automatic QE-crash resumption. Expiry is read-triggered: the next GET of the run marks an active turn FAILED if more than 40 minutes have passed since the turn was accepted. There is no periodic sweep, so the stored run can remain RUNNING until it is read. Expiry never replays execution or expires approval-paused runs, and failure does not prove that external tool work has stopped.

Example request

{
  "messages": [
    {
      "role": "USER",
      "content": [
        {
          "text": "What is our parental leave policy?",
          "type": "text"
        }
      ]
    }
  ]
}

Response

Successful response.

request_idstring required

Platform-generated request ID for support correlation.

Changes

  • 338a3a158aa5Revision changes
    • info

      added the new optional request property

    • info

      added the success response with the status

  • 32b37bfbb7e1Revision changes
    • info

      added the optional property //// to the response with the status

    • info

      added the optional property ///////// to the response with the status