Skip to main content

Building agents with Glean

A Glean agent is built and published in Glean, then run by people in the Glean app or by your application through the Agents API. This page helps you pick where to define an agent and how to call it, then points you to the detailed guide for each path.

Choose an approach​

Build in Agent Builder, then run it from code​

Agent Builder in the Glean app creates and configures agents. In Auto mode you describe the outcome you want and refine and test the agent; Workflow mode builds a fixed, step-by-step process with explicit control over its execution. See the Glean Agents documentation for building and publishing.

API runs use the published agent, so publish your edits before calling it. To get the agent ID, click Share on the agent and copy the Agent ID from the API section under Publishing options. The ID is also the 32-character value after /agents/ in the agent's URL.

Run agents with the Platform Agents API​

The Platform API is Glean's recommended API for new integrations. Its Agents API finds agents with POST /api/agents/search, reads their input and output schemas, and runs them with POST /api/agents/{agent_id}/runs. A run either streams server-sent events (stream: true) or returns the agent's final messages.

For work that should outlive the HTTP request, set execution_mode to DURABLE. The create call returns the run's initial snapshot with HTTP 201 without waiting for execution; you then:

  • Poll GET /api/agents/{agent_id}/runs/{run_id} for its state. An overdue run is marked FAILED only when it is read; without a read, the stored run can stay RUNNING.
  • When state is REQUIRES_INPUT, read pending_interactions. Each entry has type: TOOL_APPROVAL, the tool's name and description, and the exact arguments it wants to use.
  • Send an APPROVE or REJECT decision for every pending interaction_id, with the run_id in the body, to POST /api/agents/{agent_id}/responses. The same run then resumes.
  • Stop a run with POST /api/agents/{agent_id}/cancellations. Cancellation is cooperative; poll the run for its final state.

The Client API endpoints for searching agents, getting an agent or its schemas, and running agents (/rest/api/v1/agents/...) are deprecated in favor of these endpoints. See the deprecation list for removal dates.

Define agents as code​

The agent specification describes an agent as a directory of files: spec.yaml, instructions.md, and optional skills and subagents. Keep the directory in version control, zip it, and send it to the Client API Import an agent endpoint to create or update the agent.

Bring Glean into another agent framework​

If your agent runs in another host or framework, give it Glean's search, chat, and tools instead of calling a Glean agent:

Authentication and scopes​

The Agents API accepts OAuth access tokens and Glean-issued tokens. Prefer OAuth for per-user integrations. Use a Glean-issued token for global permissions with X-Glean-ActAs, or when no OAuth path exists. See Platform API authentication.

The Agents API endpoints require the agents scope. The caller must also have access to the agent, and a durable run can only be read, answered, or cancelled by the user who started it.

If an agent uses tools the caller has not authorized yet, the run is rejected with 422 and authentication_suggestions naming each tool. Have the user authorize those tools, then retry the run.