---
title: "Connect Guru to AI Agents: Verify Cards, Audit Quality, and Sync Data"
slug: connect-guru-to-ai-agents-verify-cards-audit-quality-and-sync-data
date: 2026-10-07
author: Nidhi KN
categories: ["AI & Agents"]
excerpt: "Connect Guru to your AI Agents using Truto's /tools endpoint. Learn how to fetch tools programmatically, handle rate limits, and automate knowledge workflows."
tldr: "A step-by-step engineering guide to connecting Guru to AI agents. Learn how to fetch Truto's LLM-ready proxy APIs, bind them to LangChain, manage API rate limits, and build autonomous workflows for knowledge verification and auditing."
canonical: https://truto.one/blog/connect-guru-to-ai-agents-verify-cards-audit-quality-and-sync-data/
---

# Connect Guru to AI Agents: Verify Cards, Audit Quality, and Sync Data


You want to connect Guru to an AI agent so your system can independently read knowledge cards, verify stale documentation, execute asynchronous chat operations, and audit team analytics based on historical context. Here is exactly how to do it using Truto's `/tools` endpoint and SDK, bypassing the need to build and maintain a custom Guru integration from scratch.

Giving a Large Language Model (LLM) read and write access to your Guru instance is an engineering headache. You either spend weeks building, hosting, and maintaining a custom connector to handle complex card verification states, or you use a managed infrastructure layer that handles the boilerplate for you. If your team uses ChatGPT, check out our guide on [connecting Guru to ChatGPT](https://truto.one/connect-guru-to-chatgpt-manage-cards-knowledge-agents-and-answers/), or if you are building on Anthropic's models, read our guide on [connecting Guru to Claude](https://truto.one/connect-guru-to-claude-automate-answers-folders-and-team-analytics/). For developers building custom autonomous workflows, you need a programmatic way to fetch these tools and bind them to your agent framework.

This guide breaks down exactly how to fetch AI-ready tools for Guru, bind them natively to an LLM using LangChain (or any framework like LangGraph, CrewAI, or Vercel AI SDK), and execute complex knowledge management workflows. For a deeper look at the architecture behind this approach, refer to our research on [architecting AI agents and the SaaS integration bottleneck](https://truto.one/architecting-ai-agents-langgraph-langchain-and-the-saas-integration-bottleneck/).

## The Engineering Reality of the Guru API

Giving an LLM access to [external knowledge bases](https://truto.one/connect-google-drive-to-ai-agents-automate-file-discovery-and-search/) sounds simple in a prototype. You write a Node.js function that makes a fetch request to a search endpoint and wrap it in an `@tool` decorator. In production against complex systems like Guru, this approach collapses. 

The Guru API introduces several specific integration challenges that break standard REST assumptions. If you hardcode these interactions into your agent, you will spend your sprints writing defensive integration code instead of improving your model's reasoning capabilities.

### The Asynchronous Polling Trap for Chat and Ask Endpoints

LLMs operate synchronously in a request-response cycle. However, Guru's advanced knowledge agent and chat functionalities operate asynchronously. When you initiate a query using the `create_a_guru_chat_ask_async` endpoint, the API does not immediately return the answer. Instead, it returns an HTTP 202 Accepted status indicating that the answer is still processing. 

If you expose the raw API to an AI agent, the agent will frequently hallucinate that the HTTP 202 response object is the final answer, or it will rapidly poll the endpoint in a tight loop, triggering rate limits. Your tool layer must normalize this async behavior, providing distinct tools for initiating a request and deterministically checking its status, abstracting the raw HTTP polling mechanics away from the LLM.

### The Complexity of Card Verification States

Guru's primary value proposition is its trusted knowledge model, heavily relying on a verification state machine (unverified, verified, needs verification). This state is not simply a boolean flag on a card object. 

Modifying a card's verification state requires specific payloads sent to specific bulk update endpoints, often requiring knowledge of the current verifiers, teams, and verification intervals. For example, replacing a card's verifiers completely overwrites the existing list, meaning your agent must first fetch the extended card data, append the new verifier, and submit the entire array back. Exposing this orchestration directly to the model context results in corrupted knowledge graphs.

### Strict Card Manager Query Language (CMQL)

When searching for cards programmatically, the standard free-text search is often insufficient for administrative tasks. Guru provides a powerful Card Manager search API, but it requires a deeply nested, strictly typed JSON query specification. Standard LLMs are trained to expect intuitive, flat JSON objects. If an agent attempts to invent a CMQL payload without strict schema constraints, the Guru API will reject it immediately. By utilizing a unified tool layer, Truto collapses these schemas into validated inputs, preventing the LLM from inventing operators or nesting structures incorrectly.

## Building Multi-Step Workflows

To build a reliable agent, you must abstract the underlying API mechanics into a standardized toolset. [Every integration on Truto is represented as a comprehensive JSON object](https://truto.one/how-do-mcp-servers-auto-generate-tools-from-api-documentation/) mapping the underlying product's API behavior. Truto maps these into a REST-based CRUD API known as Proxy APIs, which handle authentication and schema validation.

By utilizing the `/tools` endpoint, you can dynamically fetch these Proxy APIs as LLM-ready tools. This is framework-agnostic, meaning you can bind these tools to LangChain, Vercel AI SDK, or CrewAI seamlessly.

### Handling Rate Limits in Agentic Loops

When connecting autonomous agents to external APIs, [rate limiting is the most common point of failure](https://truto.one/how-to-handle-third-party-api-rate-limits-when-an-ai-agent-is-scraping-data/). Agents can execute loops incredibly fast, easily exceeding strict vendor limits. 

It is critical to understand a factual architectural constraint: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream Guru API returns an HTTP 429 Too Many Requests, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`) per the IETF specification. The caller is completely responsible for implementing retry and exponential backoff logic. Do not assume the integration layer will absorb these errors for you.

### Example: LangChain Agent with TrutoToolManager

Here is how you fetch Guru tools programmatically and bind them to an agent, implementing proper error handling for rate limits.

```typescript
import { ChatOpenAI } from "@langchain/openai";
import { AgentExecutor, createOpenAIToolsAgent } from "langchain/agents";
import { ChatPromptTemplate } from "@langchain/core/prompts";
import { TrutoToolManager } from "truto-langchainjs-toolset";

async function runGuruVerificationAgent() {
  // 1. Initialize the LLM
  const llm = new ChatOpenAI({
    modelName: "gpt-4o",
    temperature: 0,
  });

  // 2. Initialize Truto Tool Manager for the specific integrated account
  const trutoManager = new TrutoToolManager({
    apiKey: process.env.TRUTO_API_KEY,
    accountId: "guru_integration_account_id_123"
  });

  // 3. Fetch specific tools needed for the workflow
  // We request tools by their distinct operation names
  const tools = await trutoManager.getTools({
    toolNames: [
      "create_a_guru_search_cardmgr",
      "guru_cards_bulk_update", 
      "get_single_guru_card_extended_by_id"
    ]
  });

  // 4. Create the prompt template
  const prompt = ChatPromptTemplate.fromMessages([
    ["system", "You are a knowledge base administrator. Your job is to find cards that need verification, retrieve their extended details, and mark them as verified if they meet criteria."],
    ["human", "{input}"],
    ["placeholder", "{agent_scratchpad}"],
  ]);

  // 5. Bind tools and create the agent
  const agent = await createOpenAIToolsAgent({
    llm,
    tools,
    prompt,
  });

  const executor = new AgentExecutor({
    agent,
    tools,
    maxIterations: 10,
  });

  // 6. Execute with custom rate limit handling
  try {
    const result = await executor.invoke({
      input: "Find up to 5 cards in the Engineering collection that are unverified, check their details, and verify them."
    });
    console.log(result.output);
  } catch (error) {
    if (error.response && error.response.status === 429) {
      const resetTime = error.response.headers.get('ratelimit-reset');
      console.error(`Rate limited by Guru. Must backoff until ${resetTime}. Agent loop aborted.`);
      // Implement your custom backoff/retry queue logic here
    } else {
      throw error;
    }
  }
}
```

### System Flow

```mermaid
sequenceDiagram
    participant App as Host Application
    participant Agent as AI Agent
    participant Truto as Truto Proxy API
    participant Upstream as Guru API

    App->>Agent: Prompt: "Verify unverified cards"
    Agent->>Truto: Invoke create_a_guru_search_cardmgr
    Truto->>Upstream: POST /cards/search
    Upstream-->>Truto: 429 Too Many Requests
    Note right of Truto: Truto passes 429 directly to caller<br>with IETF ratelimit-reset header.
    Truto-->>Agent: Throw 429 Error
    Note left of Agent: Caller handles backoff<br>and retries the invocation.
    Agent->>Truto: Retry create_a_guru_search_cardmgr
    Truto->>Upstream: POST /cards/search
    Upstream-->>Truto: 200 OK (Card List)
    Truto-->>Agent: Validated JSON Response
    Agent-->>App: Return workflow summary
```

## Hero Tools for Guru

While Truto exposes dozens of endpoints for the Guru integration, building an autonomous agent requires focusing on the highest-leverage capabilities. Do not overwhelm your LLM's context window with endpoints it will never use. 

Here are the critical tools to bind to your agent for knowledge management and auditing operations.

### Search Cards via Card Manager

**Tool Name:** `create_a_guru_search_cardmgr`

This tool allows the agent to search Guru cards using a structured JSON query payload. It supports complex filtering by title, tag, owner, verifier, verification state, folder IDs, and collection IDs, combined with search terms and sorting. Because it uses strict schema validation, the LLM is forced to output valid query operators, preventing hallucinated search queries.

> "Search the 'Sales Engineering' collection for cards with the tag 'pricing-2026' that currently have an 'UNVERIFIED' verification state. Return the first page of results."

### Get Extended Card Details

**Tool Name:** `get_single_guru_card_extended_by_id`

Fetching a standard card object often leaves out critical metadata needed for administrative decisions. This tool loads a single Guru card with extended details, including the card's teams (boards) and collaborators. This is strictly required if the agent intends to evaluate who holds editing or verification rights before making a change.

> "Fetch the extended details for card ID '3f8a9b1c-XXXX' so we can see who the current collaborators and teams are before we update the content."

### Verify a Card

**Tool Name:** `guru_cards_bulk_update`

This tool specifically marks a card as verified in Guru by its ID. Verification is a core metric in Guru; allowing an agent to automatically verify programmatic content (like API specs or database schema cards) immediately boosts trust scores across the team without manual human intervention.

> "The database schema documentation for the 'Users' table matches our current production state. Go ahead and verify card ID '7d9e1a2b-XXXX'."

### Update Card Content and Settings

**Tool Name:** `guru_card_extendeds_bulk_update`

This is a heavy-duty writing tool. It allows the agent to update a Guru card's content, title, sharing status, tags, and verifiers in a single call. Note that modifying tags or verifiers via this tool replaces the entire existing array, so the agent must read the current state first if it wishes to append data.

> "Update the content of the 'Quarterly Objectives' card to include the Q3 bullet points we generated. Ensure the share status remains 'TEAM' and keep the existing 'leadership' tag."

### Ask Knowledge Agent Asynchronously

**Tool Name:** `create_a_guru_chat_ask_async`

Routes a complex question to a Guru Knowledge Agent in the background. Because Guru takes time to synthesize answers from multiple documents, this tool initiates the job and returns an operation ID. The LLM must be instructed to use this tool first, receive the ID, and then poll for the result, respecting the asynchronous architecture of the underlying system.

> "Submit a question to the HR Knowledge Agent asking 'What is the updated 2026 parental leave policy?' and give me the job ID so we can track it."

### List Team Analytics

**Tool Name:** `list_all_guru_team_analytics`

Extracts analytics events for a specific Guru team, paginated up to 500 events per call. This is highly useful for agentic auditing workflows, where an AI is tasked with finding which collections are highly viewed versus which are abandoned, allowing the agent to suggest archiving stale content.

> "Pull the analytics events for the 'Customer Success' team for the last 30 days so I can generate a report on which knowledge cards are getting the most traffic."

For the complete schema definitions and the full inventory of available endpoints, view the [Guru integration page](https://truto.one/integrations/detail/guru).

## Workflows in Action

Here is what autonomous knowledge management looks like in production when these tools are combined into agentic workflows.

### Scenario 1: Automated Knowledge Base Pruning

IT administrators spend hours tracking down obsolete documentation. An AI agent can run on a schedule to audit the knowledge base, identify abandoned cards, and notify owners or verify machine-generated documentation.

> "Audit the 'Engineering Runbooks' collection. Find any cards that have been unverified for more than 90 days. For each card, fetch the extended details to find the primary collaborator, and then generate a list of stale documentation to review."

**Execution Steps:**
1. The agent calls `create_a_guru_search_cardmgr`, passing a structured JSON query filtering by the specific collection ID and `verificationState = UNVERIFIED`, sorted by the last verified date.
2. The API returns a paginated list of stale cards.
3. For each card in the list, the agent loops through and calls `get_single_guru_card_extended_by_id` to retrieve the collaborators array.
4. The agent compiles the data and formats a markdown report mapping each stale card to its last known owner.

### Scenario 2: Autonomous Support Tier 1 Resolution

Customer support platforms can trigger an AI agent whenever a new ticket arrives. The agent can consult Guru's internal knowledge base asynchronously before drafting a response to the customer.

> "A customer just asked how to configure SAML SSO. Ask the Technical Support Knowledge Agent in Guru for the step-by-step process. Wait for the response, and then draft a reply to the customer based strictly on the verified knowledge."

**Execution Steps:**
1. The agent calls `create_a_guru_chat_ask_async`, passing the customer's question as the payload to the specific agent ID. It receives an HTTP 202 Accepted and a `thread_id`.
2. The agent knows it must wait. It executes a loop calling `get_single_guru_chat_ask_async_by_id` using the thread ID. 
3. It receives an HTTP 202 status a few times. (If rate limits trigger, it backs off using the `ratelimit-reset` header).
4. Finally, the API returns an HTTP 200 with the synthesized answer and the source document IDs.
5. The agent parses the answer and generates the final support reply, citing the specific Guru documents.

> Ready to connect your AI agents to Guru without the integration headaches? Truto provides unified tools with zero data retention and enterprise-grade SLA. Book a demo today.
>
> [Talk to us](https://truto.one/book-a-demo/)

## Moving Past Integration Maintenance

Building an AI agent is fundamentally an exercise in state management and reasoning. Every hour your engineering team spends reading API documentation, tracking down pagination cursor bugs, or parsing opaque rate limit headers is an hour stripped away from improving your core product.

By leveraging Truto's `/tools` endpoint, you decouple your AI agent logic from the underlying vendor API quirks. Your LLM interacts with a strictly typed, schema-validated proxy layer that prevents hallucinated parameters and ensures deterministic execution. Whether you are automating stale card cleanup or orchestrating complex async knowledge queries, standardizing the integration layer is the only way to scale agentic workflows reliably in production.