Glean Agent Toolkit — Usage Guide

Installation

Base install (no framework adapters):

pip install glean-agent-toolkit

With a specific framework adapter:

pip install "glean-agent-toolkit[openai]"     # OpenAI Agents SDK
pip install "glean-agent-toolkit[langchain]"   # LangChain / LangGraph
pip install "glean-agent-toolkit[crewai]"      # CrewAI
pip install "glean-agent-toolkit[adk]"         # Google Agent Development Kit

All adapters at once:

pip install "glean-agent-toolkit[all]"

Quick Start with get_tools()

get_tools() is the primary API. It returns the nine built-in Glean tools converted to a specific framework's format.

from glean.agent_toolkit import get_tools

# The built-in Glean tools for a framework
tools = get_tools("openai")       # list of OpenAI FunctionTool objects
tools = get_tools("langchain")    # list of LangChain StructuredTool objects
tools = get_tools("crewai")       # list of CrewAI BaseTool objects
tools = get_tools("adk")          # list of Google ADK FunctionTool objects

By default only the built-in glean* tools are returned. Custom @toolspec tools require explicit opt-in: builtin=False (custom only), builtin=None (everything), or list them in include=.

Filtering tools

# Only include specific tools
tools = get_tools("openai", include=["glean_search", "glean_chat"])

# Exclude specific tools
tools = get_tools("langchain", exclude=["glean_outlook_search"])

Passing credentials explicitly

tools = get_tools(
    "openai",
    api_token="your-glean-api-token",
    server_url="https://your-company-be.glean.com",  # full URL incl. https://
)

server_url must include the http(s):// scheme; a bare hostname fails fast with a clear error.

configure() — process-wide defaults

import glean.agent_toolkit

glean.agent_toolkit.configure(
    api_token="your-glean-api-token",
    server_url="https://your-company-be.glean.com",  # or instance="your-company"
)

tools = glean.agent_toolkit.get_tools("langchain")  # uses the configured defaults

configure() sets a process default used whenever no explicit context/client/credentials are supplied (tools, adapters, and get_tools() all honor it, sharing one HTTP client). It is idempotent and overridable per call.

Advanced: GleanContext — Client Lifecycle

GleanContext is the dependency injection object that provides Glean API client access to every tool. It is the first parameter of every tool function, but adapters bind it automatically so LLM frameworks never see it. Most users only need env vars or configure(); use GleanContext for explicit client lifecycle control (close()/context manager) or multiple Glean instances in one process.

from glean.agent_toolkit.context import GleanContext

# From environment variables (GLEAN_API_TOKEN, GLEAN_SERVER_URL)
ctx = GleanContext()

# Explicit credentials
ctx = GleanContext(api_token="...", server_url="...")

# Or use instance name instead of server_url
ctx = GleanContext(api_token="...", instance="your-instance")

# Or inject a pre-built Glean client
from glean.api_client import Glean
client = Glean(api_token="...", server_url="...")
ctx = GleanContext(client=client)

# Get the underlying Glean API client
glean_client = ctx.get_client()

Available Tools

All tools are registered under the glean.agenttoolkit.tools package. Each tool function name is the import name; each tool's name attribute (used by LLMs) is prefixed with glean.

Explicit imports

from glean.agent_toolkit.tools import (
    search,
    chat,
    read_document,
    web_search,
    calendar_search,
    employee_search,
    code_search,
    gmail_search,
    outlook_search,
)

The old gleanchat import name still works but is deprecated (emits DeprecationWarning); the tool ID stays gleanchat.

Per-Tool Direct Usage

Every tool function can be called directly. The first parameter is always ctx: GleanContext | None = None, followed by keyword-only arguments after *.

from glean.agent_toolkit.tools import search
from glean.agent_toolkit.context import GleanContext

ctx = GleanContext()

# Call the tool directly
result = search(ctx, query="quarterly results", page_size=5)

Adapter convenience methods

Each decorated tool function has adapter methods attached:

from glean.agent_toolkit.tools import search

openai_tool   = search.as_openai_tool()     # OpenAI FunctionTool
langchain_tool = search.as_langchain_tool() # LangChain Tool
crewai_tool   = search.as_crewai_tool()     # CrewAI BaseTool
adk_tool      = search.as_adk_tool()        # Google ADK FunctionTool

Results and Error Handling

Direct Python calls to a tool function return a ToolResult TypedDict, and never raise (missing credentials included):

from glean.agent_toolkit.tools._common import ToolResult

# ToolResult structure:
{
    "status": "ok" | "error",
    "result": <payload> | None,       # present on success
    "error": <message> | None,        # present on failure
    "error_type": <ErrorType> | None, # classification on failure
    "suggested_action": <action> | None,
}

Framework adapters (gettools(), .as*tool()) unwrap this envelope before handing results to the framework: on success they deliver the raw result payload (JSON-serialized where the framework expects strings); on failure a compact {"error", "errortype", "suggested_action"} dict. Custom tools that return non-envelope values pass through unchanged.

Error types

Checking results

result = search(ctx, query="roadmap")
if result["status"] == "ok":
    documents = result["result"]
else:
    print(f"Error ({result['error_type']}): {result['error']}")
    print(f"Suggested: {result['suggested_action']}")

Framework-Specific Examples

OpenAI Agents SDK

from agents import Agent, Runner
from glean.agent_toolkit.tools import search

agent = Agent(
    name="KnowledgeAssistant",
    instructions="You help users find company information using Glean search.",
    tools=[search],  # Pass the tool function directly
)

result = Runner.run_sync(agent, "Find our Q4 planning documents")
print(result.final_output)

LangChain

from langchain.agents import AgentExecutor, create_react_agent
from langchain_openai import ChatOpenAI
from glean.agent_toolkit import get_tools

tools = get_tools("langchain")
llm = ChatOpenAI(model="gpt-4")
# ... set up prompt and agent as usual
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

CrewAI

from crewai import Agent, Crew, Task
from glean.agent_toolkit.tools import search

researcher = Agent(
    role="Corporate Researcher",
    goal="Find relevant company information",
    tools=[search.as_crewai_tool()],
)

Google ADK

from google.adk.agents import Agent
from glean.agent_toolkit.tools import search, employee_search

root_agent = Agent(
    name="company_assistant",
    model="gemini-2.0-flash",
    tools=[search.as_adk_tool(), employee_search.as_adk_tool()],
)

Async Support

Built-in tools are natively async end to end: framework async invocation (await tool.ainvoke(...) in LangChain, oninvoketool in the OpenAI Agents SDK, run_async in ADK) flows through the Glean SDK's async HTTP client with no thread-pool round-trip.

For direct async use of a tool spec:

from glean.agent_toolkit.tools import search

result = await search.tool_spec.async_function(query="roadmap")

Custom @toolspec tools may be async def; the coroutine becomes the native async path. Custom sync tools get an asyncio.tothread async wrapper automatically. Caveat: calling an async def tool synchronously works outside an event loop (sync bridge via asyncio.run) but raises a clear RuntimeError inside a running event loop — use the async path there.

Environment Variables

Required

You can use GLEANINSTANCE instead of GLEANSERVER_URL if preferred.

Optional — Retry Configuration

Set these before constructing any GleanContext or calling get_tools().