Multi-step agent with governed tools

Build a Glean agent that plans, retrieves, and acts through a governed custom tool — with a safe fallback when the tool is denied.

~2 hrAdvanced

Problem

A chatbot that only answers questions is half an agent. Attach a governed Tool and it can act — file a ticket, update a record — but only for people who are actually allowed to, with a graceful fallback for everyone else instead of a hard failure.

Architecture

Agentplan → retrieve → act

Glean retrievalgrounded in the index

Custom toolgoverned write action

Prerequisites

Agent builder access in your Glean instance

Permission to register a custom tool (or admin help)

A Glean token with AGENTS scope for API invocation

Steps

1

Scaffold the project

npx tiged --mode=git gleanwork/glean-cookbook/recipes/multi-step-agent multi-step-agent

2

Install dependencies

cd multi-step-agent/tool-server && pip install -r requirements.txt && cd ../invoke-agent && pip install -r requirements.txt

3

Run the tool server

Listens on port 8080. Keep this running in its own terminal — the agent calls it over HTTP once registered.

cd multi-step-agent/tool-server && python server.py

4

Register the tool

Manual, UI-only step — there is no API to create a tool. In Admin > Platform > Tools > Add, register the tool and upload multi-step-agent/tool-server/openapi.yaml as its API spec.

5

Create the agent

Manual, UI-only step. In Agent Builder: paste the recipe's instructions, turn retrieval on, attach the tool you just registered. Copy the agent's ID for the next step.

6

Set credentials

Fill in GLEAN_API_TOKEN, GLEAN_INSTANCE, and GLEAN_AGENT_ID (the ID from the previous step).

cd multi-step-agent/invoke-agent && cp .env.example .env

7

Run it

python main.py

8

Verify

Run as a permitted user (Acme-Engineering) and confirm the ticket actually gets filed; run as a non-permitted user and confirm a graceful no-write fallback summary instead of a hard failure.

Take it further

Add a second governed tool (e.g., escalate to PagerDuty) and let the agent choose between them based on severity.

Switch to run_stream() and parse the SSE text yourself for a live-updating UI.

Combine with permissions-aware-rag's retrieval pattern if you want the agent's grounding to come from your own index instead of Glean's default retrieval.

Scaffold starter code

Copies a prompt your AI assistant can build from.

At a glance

SurfacesAgents, Tools

StatusProduction pattern

Time~2 hr

Required scopes

AGENTSTOOLS

Code assets

Governed custom Tool — files an incident ticket, restricted to Acme-EngineeringInvoke the agent via agents.run, demo both the permitted and denied branches