Graphlit Agent Tools

Give your agent the Graphlit retrieval tools it needs.

Agents that answer from private knowledge need a small set of reliable abilities: retrieve the right Graphlit content, inspect the source behind a claim, and bring in fresh context when the knowledge base is missing something. @graphlit/agent-tools packages those abilities as small, framework-friendly tools backed by Graphlit.

Use these tools with any agent harness that accepts structured tool definitions and async handlers: Graphlit streamAgent(), OpenAI Agents SDK, Mastra, Claude Agent SDK, Claude Managed Agents, the Vercel AI SDK, or your own loop.

Why Use It

• Give your agent private context: retrieve from Graphlit-ingested documents, emails, events, messages, pages, posts, and files.
• Ground answers in inspectable sources: return contents://... references your app can render or inspect before the agent makes source-backed claims.
• Handle real retrieval requests: support semantic questions like "what risks did the customer mention?" and filter-only requests like "all emails in the last week."
• Bring in fresh context when needed: let the agent search the web, inspect a page without ingesting it, ingest a URL, and wait for processing before using newly added content.
• Keep control in the app: choose the tools your agent should have without adding tool discovery, an MCP wrapper, or an approval layer.

Install

npm install graphlit-client @graphlit/agent-tools

Run these tools server-side with Graphlit credentials. Do not expose Graphlit project credentials to the browser.

Tool Shape

Every tool creator returns the same three pieces:

type GraphlitAgentTool<TArgs, TResult> = {
  // Zod schema for frameworks that accept Zod or Standard JSON Schema.
  inputSchema: z.ZodType<TArgs>;

  // Graphlit tool definition. The schema is also available as a JSON string.
  tool: Types.ToolDefinitionInput;

  // Async implementation. The handler validates args with Zod before calling Graphlit.
  handler: (
    args: TArgs,
    artifacts?: StreamAgentArtifactCollector,
    abortSignal?: AbortSignal,
  ) => Promise<TResult>;
};

That shape is intentionally boring:

• Use tool plus handler with Graphlit streamAgent().
• Use inputSchema plus handler with Zod/Standard-Schema frameworks like OpenAI Agents SDK and Mastra.
• Use inputSchema.shape plus handler with Claude Agent SDK custom tools.
• Use JSON.parse(tool.schema) plus handler with JSON Schema frameworks such as Claude Managed Agents custom tools.
• Call handler(args) directly from any custom agent loop.

Tools

Prefer retrieve_contents plus inspect_content as the default RAG pair. Add analyze_prompt when you want the model to produce a visible routing contract before retrieval. Add mutating, enrichment, and generation tools only when the host app wants the agent to have those abilities.

For read-only agent comparisons or customer-facing agents that should not mutate a Graphlit project, a good default set is retrieve_contents, inspect_content, count_contents, list_resources, read_resource, web_search, inspect_page, and web_map. When exposing resource tools in a constrained app, pass allowedKinds to keep the agent inside the resource surface you intend.

Read-Only Retrieval

Agent ability	Add this tool	What it does
Analyze a prompt before tool use	createAnalyzePromptTool()	Return a compact routing contract for source scopes, subjects, evidence plan, answer shape, and next step. It does not retrieve evidence or mutate Graphlit.
Retrieve Graphlit knowledge	createRetrieveContentsTool()	Find relevant ingested content for grounded answers.
Inspect a source	createInspectContentTool()	Read fuller text, parent/child references, export URI text, or optional image descriptions from a returned contents://... source.
Count content	createCountContentsTool()	Count content matching public filters.
Query facets	createQueryContentFacetsTool()	Return content facet buckets for counts and filtering.
Retrieve communications	createRetrieveCommunicationsTool()	Find emails, events, messages, posts, issues, and pull requests by topic, participants, domains, and recency.
Retrieve conversations	createRetrieveConversationsTool()	Search Graphlit conversations.
Retrieve entities	createRetrieveEntitiesTool()	Retrieve knowledge-graph entities relevant to a prompt.
Retrieve facts	createRetrieveFactsTool()	Retrieve facts relevant to a prompt and filter.
Lookup an entity	createLookupEntityTool()	Resolve an entity by ID or name and return relationships.
Explore entities	createExploreEntityTool()	Compose entity lookup, related facts, contents, and conversations.
Retrieve images	createRetrieveImagesTool()	Retrieve image content and optionally fetch image bytes.
Retrieve memories	createRetrieveMemoriesTool()	Retrieve memory content with ContentTypes.Memory locked internally.
Query collections	createQueryCollectionsTool()	List collections.
Query feeds	createQueryFeedsTool()	List feeds.
Search the public web	createWebSearchTool()	Find current web leads without ingesting them.
Inspect a public web page	createInspectPageTool()	Return Markdown text from one public URL without ingesting it into Graphlit.
Map a site	createWebMapTool()	Discover public URLs from a site map without ingesting them.
List resource URIs	createListResourcesTool()	List Graphlit resource URIs that read_resource can dereference.
Read resource URIs	createReadResourceTool()	Read contents://, collections://, feeds://, facts://, conversations://, and entities:// resources through SDK calls.

Graphlit Content Mutation

These tools mutate Graphlit project state. Host applications should expose them intentionally and apply their own approval policy when needed.

Agent ability	Add this tool	What it does
Add a URL	createIngestUrlTool()	Save a public URL for later retrieval.
Add text	createIngestTextTool()	Save raw text for later retrieval.
Add links	createIngestLinksTool()	Ingest public hyperlinks extracted from existing Graphlit content.
Screenshot a page	createScreenshotPageTool()	Capture a public page screenshot into Graphlit.
Create a collection	createCreateCollectionTool()	Create a collection.
Add contents to collections	createAddContentsToCollectionTool()	Add content IDs to collections.
Remove contents from a collection	createRemoveContentsFromCollectionTool()	Remove content IDs from one collection.
Delete a collection	createDeleteCollectionTool()	Delete a collection by ID or collections://... URI.
Add a content label	createAddContentLabelTool()	Add one label to one content item.
Remove a content label	createRemoveContentLabelTool()	Remove one label from one content item.
Create a web crawl	createWebCrawlTool()	Create a Graphlit web crawl feed. Defaults to a one-time crawl.
Wait for content processing	createWaitContentDoneTool()	Wait until a content item is ready.
Wait for feed sync	createWaitFeedDoneTool()	Wait until a feed sync is ready.
Store memory	createIngestMemoryTool()	Store a Graphlit memory item. The public schema does not expose TTL.
Delete memory	createDeleteMemoryTool()	Delete memory content after verifying ContentTypes.Memory.

Enrichment And Generation

Availability depends on the Graphlit project capabilities, connectors, and credits.

Agent ability	Add this tool	What it does
Enrich companies	createEnrichCompaniesTool()	Lookup company candidates and optionally create/enrich organization entities.
Enrich persons	createEnrichPersonsTool()	Lookup person candidates and optionally create/enrich person entities.
Publish audio	createPublishAudioTool()	Generate audio content from text.
Publish image	createPublishImageTool()	Generate image content from a prompt.
Publish video	createPublishVideoTool()	Generate video content from a prompt.

This package intentionally does not export Zine/Dossium app-layer tools such as broad inspect, delivery tools (draft_email, send_email, social/channel/document/issue/calendar writers), shell/code execution, or first-party orchestration helpers. The resource tools are package-native Graphlit readers, not platform__... MCP runtime tools, and they do not read skills://, ui://, or external https:// resources.

Graphlit streamAgent

streamAgent() can use the returned Graphlit tool definitions and handlers directly.

import { Graphlit } from "graphlit-client";
import {
  createInspectContentTool,
  createRetrieveContentsTool,
  createWebSearchTool,
} from "@graphlit/agent-tools";

const client = new Graphlit(
  process.env.GRAPHLIT_ORGANIZATION_ID!,
  process.env.GRAPHLIT_ENVIRONMENT_ID!,
  process.env.GRAPHLIT_JWT_SECRET!,
);

const retrieveContents = createRetrieveContentsTool(client);
const inspectContent = createInspectContentTool(client);
const webSearch = createWebSearchTool(client);

const selectedTools = [retrieveContents, inspectContent, webSearch];

await client.streamAgent(
  "What customer emails from last week mention onboarding risk?",
  (event) => {
    // Stream events to your UI.
  },
  undefined,
  undefined,
  selectedTools.map((item) => item.tool),
  Object.fromEntries(
    selectedTools.map((item) => [item.tool.name, item.handler]),
  ),
  { maxToolRounds: 8 },
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  undefined,
  [
    "Use retrieve_contents before answering questions that depend on ingested Graphlit content.",
    "Use inspect_content when a retrieved source needs fuller text before making a source-backed claim.",
    "If retrieved evidence is weak or missing, say so plainly.",
  ].join(" "),
);

Mastra

Mastra tools accept an id, description, Zod-compatible inputSchema, and execute function. Pass the Graphlit tool's inputSchema and delegate execution to the Graphlit handler.

import { Agent } from "@mastra/core/agent";
import { createTool } from "@mastra/core/tools";
import { Graphlit } from "graphlit-client";
import {
  createInspectContentTool,
  createRetrieveContentsTool,
} from "@graphlit/agent-tools";

const graphlit = new Graphlit(
  process.env.GRAPHLIT_ORGANIZATION_ID!,
  process.env.GRAPHLIT_ENVIRONMENT_ID!,
  process.env.GRAPHLIT_JWT_SECRET!,
);

const retrieveContents = createRetrieveContentsTool(graphlit);
const inspectContent = createInspectContentTool(graphlit);

const mastraRetrieveContents = createTool({
  id: retrieveContents.tool.name,
  description:
    retrieveContents.tool.description ?? "Retrieve Graphlit content.",
  inputSchema: retrieveContents.inputSchema,
  execute: async (args, context) =>
    retrieveContents.handler(args, undefined, context?.abortSignal),
});

const mastraInspectContent = createTool({
  id: inspectContent.tool.name,
  description: inspectContent.tool.description ?? "Inspect Graphlit content.",
  inputSchema: inspectContent.inputSchema,
  execute: async (args, context) =>
    inspectContent.handler(args, undefined, context?.abortSignal),
});

export const customerKnowledgeAgent = new Agent({
  id: "customer-knowledge-agent",
  name: "Customer Knowledge Agent",
  model: "openai/gpt-5.5",
  instructions: [
    "Answer from Graphlit content when the user asks about private knowledge.",
    "Use retrieve_contents to find relevant content.",
    "Use inspect_content before making answer-critical source-backed claims.",
  ].join(" "),
  tools: {
    [retrieveContents.tool.name]: mastraRetrieveContents,
    [inspectContent.tool.name]: mastraInspectContent,
  },
});

await customerKnowledgeAgent.generate(
  "Which customer emails from last week mention onboarding risk?",
);

OpenAI Agents SDK

OpenAI Agents SDK tools accept a name, description, Zod parameters, and execute function. Wrap the Graphlit handler as a function tool. Graphlit's SDK already handles its own OpenAI Responses API use internally; this adapter only exposes Graphlit retrieval as an OpenAI Agents SDK tool.

import { Agent, run, tool } from "@openai/agents";
import { Graphlit } from "graphlit-client";
import {
  createInspectContentTool,
  createRetrieveContentsTool,
} from "@graphlit/agent-tools";

const graphlit = new Graphlit(
  process.env.GRAPHLIT_ORGANIZATION_ID!,
  process.env.GRAPHLIT_ENVIRONMENT_ID!,
  process.env.GRAPHLIT_JWT_SECRET!,
);

const retrieveContents = createRetrieveContentsTool(graphlit);
const inspectContent = createInspectContentTool(graphlit);

const openaiRetrieveContents = tool({
  name: retrieveContents.tool.name,
  description:
    retrieveContents.tool.description ?? "Retrieve Graphlit content.",
  parameters: retrieveContents.inputSchema,
  async execute(args) {
    return retrieveContents.handler(args);
  },
});

const openaiInspectContent = tool({
  name: inspectContent.tool.name,
  description: inspectContent.tool.description ?? "Inspect Graphlit content.",
  parameters: inspectContent.inputSchema,
  async execute(args) {
    return inspectContent.handler(args);
  },
});

const customerKnowledgeAgent = new Agent({
  name: "Customer Knowledge Agent",
  model: "gpt-5.5",
  instructions: [
    "Answer from Graphlit content when the user asks about private knowledge.",
    "Use retrieve_contents to find relevant content.",
    "Use inspect_content before making answer-critical source-backed claims.",
  ].join(" "),
  tools: [openaiRetrieveContents, openaiInspectContent],
});

const result = await run(
  customerKnowledgeAgent,
  "Which customer emails from last week mention onboarding risk?",
);

console.log(result.finalOutput);

Claude Agent SDK

Claude Agent SDK custom tools run through an in-process MCP server. Its TypeScript tool() helper expects a Zod raw shape, so pass inputSchema.shape.

import {
  createSdkMcpServer,
  query,
  tool,
} from "@anthropic-ai/claude-agent-sdk";
import { Graphlit } from "graphlit-client";
import {
  createInspectContentTool,
  createRetrieveContentsTool,
} from "@graphlit/agent-tools";

const graphlit = new Graphlit(
  process.env.GRAPHLIT_ORGANIZATION_ID!,
  process.env.GRAPHLIT_ENVIRONMENT_ID!,
  process.env.GRAPHLIT_JWT_SECRET!,
);

const retrieveContents = createRetrieveContentsTool(graphlit);
const inspectContent = createInspectContentTool(graphlit);

const claudeRetrieveContents = tool(
  retrieveContents.tool.name,
  retrieveContents.tool.description ?? "Retrieve Graphlit content.",
  retrieveContents.inputSchema.shape,
  async (args) => {
    const result = await retrieveContents.handler(args);

    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
      structuredContent: result,
    };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } },
);

const claudeInspectContent = tool(
  inspectContent.tool.name,
  inspectContent.tool.description ?? "Inspect Graphlit content.",
  inspectContent.inputSchema.shape,
  async (args) => {
    const result = await inspectContent.handler(args);

    return {
      content: [{ type: "text", text: JSON.stringify(result) }],
      structuredContent: result,
    };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } },
);

const graphlitServer = createSdkMcpServer({
  name: "graphlit",
  version: "1.0.0",
  tools: [claudeRetrieveContents, claudeInspectContent],
});

for await (const message of query({
  prompt: "Summarize the customer emails from last week about onboarding risk.",
  options: {
    mcpServers: { graphlit: graphlitServer },
    allowedTools: [
      "mcp__graphlit__retrieve_contents",
      "mcp__graphlit__inspect_content",
    ],
  },
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

Claude Managed Agents

Claude Managed Agents custom tools are client-executed: Claude emits a structured tool request, your application runs the Graphlit handler, then sends the result back to the session.

import Anthropic from "@anthropic-ai/sdk";
import { Graphlit } from "graphlit-client";
import {
  createInspectContentTool,
  createRetrieveContentsTool,
} from "@graphlit/agent-tools";

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY!,
});

const graphlit = new Graphlit(
  process.env.GRAPHLIT_ORGANIZATION_ID!,
  process.env.GRAPHLIT_ENVIRONMENT_ID!,
  process.env.GRAPHLIT_JWT_SECRET!,
);

const graphlitTools = [
  createRetrieveContentsTool(graphlit),
  createInspectContentTool(graphlit),
];

const handlers = Object.fromEntries(
  graphlitTools.map((item) => [item.tool.name, item.handler]),
);

const agent = await anthropic.beta.agents.create({
  name: "Customer Knowledge Agent",
  model: "claude-opus-4-8",
  tools: graphlitTools.map((item) => ({
    type: "custom" as const,
    name: item.tool.name,
    description: item.tool.description ?? `Run ${item.tool.name}.`,
    input_schema: JSON.parse(item.tool.schema),
  })),
});

const session = await anthropic.beta.sessions.create({
  agent: agent.id,
  environment_id: process.env.ANTHROPIC_ENVIRONMENT_ID!,
});

const stream = await anthropic.beta.sessions.events.stream(session.id);

await anthropic.beta.sessions.events.send(session.id, {
  events: [
    {
      type: "user.message",
      content: [
        {
          type: "text",
          text: "Which customer emails from last week mention onboarding risk?",
        },
      ],
    },
  ],
});

for await (const event of stream) {
  if (event.type === "agent.custom_tool_use") {
    const handler = handlers[event.name];
    if (!handler) continue;

    const result = await handler(event.input);

    await anthropic.beta.sessions.events.send(session.id, {
      events: [
        {
          type: "user.custom_tool_result",
          custom_tool_use_id: event.id,
          content: [{ type: "text", text: JSON.stringify(result) }],
        },
      ],
    });
  }

  if (
    event.type === "session.status_idle" &&
    event.stop_reason?.type === "end_turn"
  ) {
    break;
  }
}

Realistic Retrieval Examples

retrieve_contents supports both semantic retrieval and filter-only content lookup.

For a prompt such as "show me all emails from last week," the tool can be called without a text search:

await retrieveContents.handler({
  type: "EMAIL",
  inLast: "P7D",
  limit: 25,
});

For RAG over specific content text, pass search:

await retrieveContents.handler({
  search: "onboarding risk renewal blocker",
  type: "EMAIL",
  inLast: "P30D",
  limit: 10,
});

For upcoming calendar context:

await retrieveContents.handler({
  type: "EVENT",
  inNext: "P7D",
  limit: 20,
});

When answer-critical evidence needs more context, inspect the contents://... reference returned by retrieval:

await inspectContent.handler({
  resourceUri: "contents://content-id-from-retrieve-contents",
  mode: "markdown",
});

Notes

• Tool schemas are authored with Zod and converted to Graphlit ToolDefinitionInput.
• Public options reuse graphlit-client SDK types where possible, including Types.ContentFilter, Types.EntityReferenceInput, Types.RetrievalStrategyInput, and Types.RerankingStrategyInput.
• Returned retrieval results include contents://... resource URIs for UI source rendering and follow-up inspection.
• This package is a set of explicit tools. It does not include tool discovery, tool bundles, MCP server hosting, approval middleware, or app-specific routing.