What does "knowledge infrastructure" actually mean for AI agents?

Knowledge infrastructure is the system that manages what your agents know. It includes the knowledge sources (docs, Confluence, Notion, etc.), the mechanisms that keep knowledge current and consistent, the APIs agents use to retrieve knowledge, and the observability that lets you see what each agent knows and where it came from. Think of it as the plumbing between agent queries and authoritative information.

Why do agents give inconsistent answers if they're using the same model and prompts?

Because they're querying different knowledge. Agent A might be pulling from a doc updated three days ago. Agent B might be pulling from a cached version from last week. Agent C might be pulling from a different source entirely. Same model, same prompts, different knowledge = different answers. This is a knowledge infrastructure problem, not a model problem.

How do I handle cross-agent knowledge consistency without rebuilding everything?

Start by identifying your single source of truth for product knowledge - usually your primary product documentation. Make sure all agents query that source, not multiple copies or cached versions. Then implement automatic propagation so that when the source updates, all agents see the change.

What's the difference between a vector database and a knowledge layer?

A vector database stores and retrieves embeddings based on semantic similarity. A knowledge layer manages knowledge: keeping it current, detecting contradictions, understanding document structure, synchronizing across multiple agents, providing tracing and observability. A vector database is a component that might sit inside a knowledge layer - but a knowledge layer is something larger and more structured.

How does a knowledge layer fit into an existing agent architecture?

Agents replace their direct knowledge source connections with API calls to the knowledge layer. Instead of Agent A querying Confluence directly and Agent B querying Notion, both agents query the knowledge layer API. The knowledge layer abstracts the underlying sources, handles updates, detects conflicts, and serves consistent answers. You don't have to rewrite your agents - just change where they get knowledge from.

How do I know if knowledge staleness is causing my accuracy degradation?

Run a retrieval audit on your 20-30 most recent failure cases. For each failure, check whether the retrieved context was outdated, incomplete, or simply not found. If more than 60% of failures trace back to knowledge-layer problems rather than model reasoning errors, staleness is likely your primary blocker. Most teams find this is true. Almost no teams check.

What's the difference between output monitoring and retrieval observability?

Output monitoring tracks what your model says. Retrieval observability tracks what your retriever finds. Output monitoring catches hallucinations after they happen. Retrieval observability lets you diagnose why they happened, whether the right context was retrieved, whether it was current, and whether the retriever understood the document structure. You need both, but most teams only have the first.

How does hierarchical retrieval reasoning (HRR) actually work?

HRR maps relationships between documents before retrieval happens. Instead of treating every chunk as independent, it understands that section 3.2 belongs to chapter 3, which belongs to a specific product version. When a query comes in, it retrieves at the right level of the hierarchy, not just the closest embedding match. This means if you ask about a process, it retrieves the full process context, not just the paragraph that happened to match your query vector.

How long does it take to integrate a knowledge layer into an existing RAG pipeline?

For most teams, 2-6 weeks depending on how many data sources you're connecting and how clean your existing infrastructure is. The integration is usually straightforward: swap your vector database calls for knowledge layer API calls, connect your data sources, and configure your sync frequency. Teams using native connectors for Confluence, Notion, Salesforce, SharePoint, and Google Drive report no custom pipeline work required.

What if we're already using LangChain or LlamaIndex?

A knowledge layer is retrieval-agnostic. It sits upstream of your retriever and changes what your retriever searches over. You can use it with LangChain, LlamaIndex, agent frameworks, or internal architectures. Most teams add the knowledge layer by adding a single API call in their retrieval chain. Your existing orchestration stays intact.

The cornerstone reference for teams running Zendesk who want to add an AI knowledge layer alongside (not in place of) the helpdesk they already operate. Covers the integration architecture, what Brainfish does for Zendesk users across five surfaces (Zendesk AI, agent assist, self-service, Live Agent Handoff, content operations), the new Live Agent Handoff capability, setup walkthrough, customer proof from Huntress and HireVue, and a roadmap for the helpdesks coming next

The Complete Guide to Brainfish + Zendesk (2026)

Quick answer

Brainfish is the AI knowledge layer that sits alongside Zendesk Support and feeds every Zendesk-native AI surface with cleaner, multi-source, continuously maintained content. The integration covers five surfaces: (1) Zendesk AI reads from Brainfish content instead of just Zendesk Guide, lifting answer accuracy in production. (2) Agent Workspace agent-assist surfaces grounded answers with traceable sources. (3) Self-service portal answers draw from the same normalized index. (4) Live Agent Handoff (GA May 2026) transfers AI conversations to human agents in the same window with full context. (5) Content operations runs continuously across Zendesk Guide plus product docs, engineering wikis, past tickets, and internal playbooks. Zendesk customers keep Zendesk, keep Zendesk AI, and add an AI knowledge layer underneath that makes both work better in production. This guide is the canonical reference for running Brainfish alongside Zendesk in 2026.

Why this guide exists

Most Zendesk customers running AI support in 2026 have hit the same ceiling. Zendesk AI is a strong product, but its production accuracy is bounded by the content it can read. Zendesk Guide articles are one source. Most teams' real answers live across Zendesk Guide, product documentation sites, engineering wikis, past tickets and macros, release notes, and internal playbooks. When Zendesk AI reads only Zendesk Guide, it answers a slice of the question set well and fails on the long tail.

The pattern most teams notice: launch accuracy is strong, then drifts. Customer questions about features documented elsewhere fail. Cross-channel inconsistency emerges (the help center says one thing, Zendesk AI another, an in-product widget a third). Wrong answers cannot be traced to specific sources. The team starts asking whether they need to switch helpdesks or change AI vendors.

For most teams the answer is neither. The structural fix is to add an AI knowledge layer underneath Zendesk that feeds Zendesk AI better content, runs continuous content operations across all sources, and surfaces in every Zendesk-native AI surface from one normalized source. That layer is what Brainfish does. This guide is the complete reference for how it works.

For the broader category framing, see What Is an AI Knowledge Layer? The Definitive Guide for 2026.

TL;DR

Brainfish runs alongside Zendesk, never in place of. Zendesk stays the system of record for tickets, queues, routing, SLAs. Brainfish is the upstream content layer that feeds Zendesk AI and every Zendesk-native AI surface.
Five integration surfaces: Zendesk AI, Agent Workspace agent-assist, self-service portals, Live Agent Handoff (new), and continuous content operations across all sources.
Live Agent Handoff is generally available as of May 2026. Transfers AI conversations to human agents in the same window with full context. No re-explaining, no blind agents.
Setup takes 1 to 2 weeks for full integration including all five surfaces. No content migration required — Brainfish reads from where content already lives.
Zendesk is the deepest Brainfish integration by design. Equivalent capabilities for Intercom, Freshdesk, and Salesforce Service Cloud are on the roadmap.

The architecture

A clean separation of concerns sits at the heart of the integration. Each system does what it does best.

Zendesk remains the system of record for cases, queues, routing, SLA management, the Agent Workspace, customer profiles, and reporting. Tickets are Zendesk's. Workflows are Zendesk's. Agent licensing is Zendesk's.

Zendesk AI remains the AI surface inside the Zendesk product (bots, suggested replies, Conversation Mining, intent detection). What changes is the content it reads.

Brainfish runs as the upstream content layer. It ingests from Zendesk Guide plus the other sources where answers actually live (product docs, engineering wikis, past tickets, release notes, internal playbooks). It normalizes that content into a single retrieval index. It runs continuous content operations across the combined index. It serves answers back to Zendesk AI, the Agent Workspace, self-service portals, and the new Live Agent Handoff capability.

The Zendesk customer keeps their Zendesk investment intact and adds the layer underneath. No helpdesk migration. No content migration. The integration is API-first and respects Zendesk's data model.

What Brainfish does for Zendesk users — five surfaces

Surface 1: Zendesk AI gets a better content source

Zendesk AI answer accuracy is a function of the content it reads. When Brainfish becomes the upstream content source, Zendesk AI sees normalized content from every source the team maintains, not just Zendesk Guide. The practical effect: Zendesk AI answer accuracy improves across the long tail of customer questions, without any change to Zendesk licensing or product surface.

For support leaders measuring AI deflection through Zendesk's reporting, this typically shows up as a step-change in resolution rate within 30 days, followed by continued improvement over 90 to 180 days as Brainfish content operations matures.

Surface 2: Agent Workspace agent-assist surfaces traceable answers

In the Zendesk Agent Workspace, agent-assist suggestions are grounded in the same normalized content the AI uses. Suggestions surface with source attribution: the agent sees which document the answer came from, what the confidence was, and can click through to verify before sending. Wrong-answer debugging moves from a multi-day investigation to a multi-minute one because every answer is traceable to a source.

This is the surface that changes most for agents in practice. Handle time on complex tickets drops because the right source surfaces faster.

Surface 3: Self-service portal draws from the same source

The Zendesk Help Center search experience can be powered by the same Brainfish content layer that feeds Zendesk AI. Customers searching the public help center get answers grounded in the same multi-source content the AI uses internally. Cross-channel consistency is structural rather than a manual process, because the help center search, the AI chatbot, and the agent-assist view all draw from one normalized source.

The failure mode without this consistency is the one customers feel most directly: three channels give three different answers to the same question. Multi-surface serving from one source eliminates that class of problem.

Surface 4: Live Agent Handoff (new — GA May 2026)

Live Agent Handoff is the marquee new capability launching with Zendesk Relate 2026. When the Brainfish AI cannot resolve a customer question, the conversation transfers to a Zendesk human agent inside the same window. The agent inherits the full AI conversation, the retrieved sources, the confidence trajectory, and the inferred reason for handoff. The customer does not re-explain. The agent does not start blind.

The handoff stops being the damaged-experience moment of the conversation and becomes a continuation. Early customer pilots show:

Handed-off conversations recover the CSAT gap that escalations normally introduce.
Handle time on escalated tickets drops 30 to 45% because the agent inherits context.
AI-to-human handoffs become structured events with attached metadata, enabling cleaner cohort analysis in Zendesk reports.

For the full launch announcement, see Introducing Brainfish Live Agent Handoff for Zendesk.

Surface 5: Continuous content operations across all sources

The fifth surface is the operational one that prevents drift. Brainfish runs continuous content operations across the combined index of Zendesk Guide articles, product docs, engineering wikis, past tickets, release notes, and internal playbooks. Four capabilities run continuously:

Stale-content detection surfaces Zendesk Guide articles and other sources that are likely outdated, routed to the owner with a specific fix.
Coverage-gap clustering identifies repeated unanswered customer questions and clusters them so a single content fix closes a whole class of tickets.
Conflict detection flags two sources disagreeing on the same question and routes the conflict to a human owner instead of letting the AI pick randomly.
Owner routing assigns drift and gaps as accountable work, not as "someone should update docs sometime."

This is the component most chatbot vendors do not have, and the reason most AI support deployments degrade in production after launch. Continuous content operations is what keeps Zendesk AI honest in production over 6 to 12 months and beyond.

Setup walkthrough (1 to 2 weeks to production)

The full Brainfish + Zendesk integration is API-first and does not require Zendesk-side custom code or app installation in most configurations.

Week 1 — Connect and ingest. Connect Brainfish to Zendesk via the standard OAuth flow. Connect any additional content sources (product docs, wikis, files) via Brainfish's native connectors. Brainfish ingests, normalizes, and indexes content across all sources. First retrievable answers grounded in customer content arrive within hours.

Week 1–2 — Configure surfaces. Enable the surfaces the team uses: Zendesk AI feed (toggle on), Agent Workspace agent-assist (configure the Brainfish app for the workspace), self-service portal search (point search at the Brainfish endpoint), and Live Agent Handoff (configure trigger rules and target queues).

Week 2 — Content operations and observability. Brainfish content operations begins surfacing stale articles, coverage gaps, and source conflicts. The content team triages the queue with owner routing. Retrieval observability is on by default, so any wrong answer can be traced to a specific source in under a minute.

Ongoing. Continuous content operations runs in the background. Most teams report first measurable AI accuracy lift within 30 days and sustained improvement over 90 to 180 days.

‍

Why Zendesk-first

A candid note. Brainfish supports Intercom, Freshdesk, and Salesforce Service Cloud as well, but Zendesk is the deepest integration today by design. Three reasons:

1. Zendesk is the most common enterprise helpdesk. A meaningful share of the support market runs Zendesk. Building the deepest integration first against the most common surface maximizes the number of teams who can use Brainfish without changing their stack.

2. Zendesk's product surface is wide enough to require depth. Zendesk AI, Agent Workspace, self-service portals, Conversation Mining, intent detection, and the upcoming Zendesk Live integrations each have specific integration shapes. Doing one helpdesk deeply produces a cleaner pattern that can then be ported to Intercom, Freshdesk, and Salesforce.

3. Zendesk is the deepest customer signal. A large share of our customer base runs Zendesk. Building for the customer composition we have, rather than for an even spread across helpdesks, has been the right call so far.

Equivalent capabilities for Intercom Fin and Inbox, Freshdesk Freddy, and Salesforce Service Cloud Einstein are on the roadmap. Live Agent Handoff specifically will arrive for those helpdesks after the Zendesk version is in steady-state production with customers.

‍

Add Brainfish alongside your Zendesk.

→ Book a Brainfish demo

‍

import time
import requests
from opentelemetry import trace, metrics
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
from opentelemetry.sdk.metrics.export import ConsoleMetricExporter, PeriodicExportingMetricReader

# --- 1. OpenTelemetry Setup for Observability ---
# Configure exporters to print telemetry data to the console.
# In a production system, these would export to a backend like Prometheus or Jaeger.
trace.set_tracer_provider(TracerProvider())
tracer = trace.get_tracer(__name__)
span_processor = SimpleSpanProcessor(ConsoleSpanExporter())
trace.get_tracer_provider().add_span_processor(span_processor)

metric_reader = PeriodicExportingMetricReader(ConsoleMetricExporter())
metrics.set_meter_provider(MeterProvider(metric_readers=[metric_reader]))
meter = metrics.get_meter(__name__)

# Create custom OpenTelemetry metrics
agent_latency_histogram = meter.create_histogram("agent.latency", unit="ms", description="Agent response time")
agent_invocations_counter = meter.create_counter("agent.invocations", description="Number of times the agent is invoked")
hallucination_rate_gauge = meter.create_gauge("agent.hallucination_rate", unit="percentage", description="Rate of hallucinated responses")
pii_exposure_counter = meter.create_counter("agent.pii_exposure.count", description="Count of responses with PII exposure")

# --- 2. Define the Agent using NeMo Agent Toolkit concepts ---
# The NeMo Agent Toolkit orchestrates agents, tools, and workflows, often via configuration.
# This class simulates an agent that would be managed by the toolkit.
class MultimodalSupportAgent:
    def __init__(self, model_endpoint):
        self.model_endpoint = model_endpoint

    # The toolkit would route incoming requests to this method.
    def process_query(self, query, context_data):
        # Start an OpenTelemetry span to trace this specific execution.
        with tracer.start_as_current_span("agent.process_query") as span:
            start_time = time.time()
            span.set_attribute("query.text", query)
            span.set_attribute("context.data_types", [type(d).__name__ for d in context_data])

            # In a real scenario, this would involve complex logic and tool calls.
            print(f"\nAgent processing query: '{query}'...")
            time.sleep(0.5) # Simulate work (e.g., tool calls, model inference)
            agent_response = f"Generated answer for '{query}' based on provided context."
            
            latency = (time.time() - start_time) * 1000
            
            # Record metrics
            agent_latency_histogram.record(latency)
            agent_invocations_counter.add(1)
            span.set_attribute("agent.response", agent_response)
            span.set_attribute("agent.latency_ms", latency)
            
            return {"response": agent_response, "latency_ms": latency}

# --- 3. Define the Evaluation Logic using NeMo Evaluator ---
# This function simulates calling the NeMo Evaluator microservice API.
def run_nemo_evaluation(agent_response, ground_truth_data):
    with tracer.start_as_current_span("evaluator.run") as span:
        print("Submitting response to NeMo Evaluator...")
        # In a real system, you would make an HTTP request to the NeMo Evaluator service.
        # eval_endpoint = "http://nemo-evaluator-service/v1/evaluate"
        # payload = {"response": agent_response, "ground_truth": ground_truth_data}
        # response = requests.post(eval_endpoint, json=payload)
        # evaluation_results = response.json()
        
        # Mocking the evaluator's response for this example.
        time.sleep(0.2) # Simulate network and evaluation latency
        mock_results = {
            "answer_accuracy": 0.95,
            "hallucination_rate": 0.05,
            "pii_exposure": False,
            "toxicity_score": 0.01,
            "latency": 25.5
        }
        span.set_attribute("eval.results", str(mock_results))
        print(f"Evaluation complete: {mock_results}")
        return mock_results

# --- 4. The Main Agent Evaluation Loop ---
def agent_evaluation_loop(agent, query, context, ground_truth):
    with tracer.start_as_current_span("agent_evaluation_loop") as parent_span:
        # Step 1: Agent processes the query
        output = agent.process_query(query, context)

        # Step 2: Response is evaluated by NeMo Evaluator
        eval_metrics = run_nemo_evaluation(output["response"], ground_truth)

        # Step 3: Log evaluation results using OpenTelemetry metrics
        hallucination_rate_gauge.set(eval_metrics.get("hallucination_rate", 0.0))
        if eval_metrics.get("pii_exposure", False):
            pii_exposure_counter.add(1)
        
        # Add evaluation metrics as events to the parent span for rich, contextual traces.
        parent_span.add_event("EvaluationComplete", attributes=eval_metrics)

        # Step 4: (Optional) Trigger retraining or alerts based on metrics
        if eval_metrics["answer_accuracy"] < 0.8:
            print("[ALERT] Accuracy has dropped below threshold! Triggering retraining workflow.")
            parent_span.set_status(trace.Status(trace.StatusCode.ERROR, "Low Accuracy Detected"))

# --- Run the Example ---
if __name__ == "__main__":
    support_agent = MultimodalSupportAgent(model_endpoint="http://model-server/invoke")
    
    # Simulate an incoming user request with multimodal context
    user_query = "What is the status of my recent order?"
    context_documents = ["order_invoice.pdf", "customer_history.csv"]
    ground_truth = {"expected_answer": "Your order #1234 has shipped."}

    # Execute the loop
    agent_evaluation_loop(support_agent, user_query, context_documents, ground_truth)
    
    # In a real application, the metric reader would run in the background.
    # We call it explicitly here to see the output.
    metric_reader.collect()

Frequently Asked Questions

How is success measured on a Brainfish + Zendesk deployment?

Five metrics: Zendesk AI deflection rate (trending up), sustained answer accuracy on a rolling sample (high 90s target), first contact resolution rate (trending up), AI-to-human handoff CSAT recovery (target: parity with non-escalated conversations), and content operations throughput (drift rate trending down, coverage gaps closed per week trending up).

Does Brainfish work with Zendesk's enterprise plans (Enterprise, Enterprise Plus)?

Yes. Brainfish supports all Zendesk Support tiers, including Enterprise and Enterprise Plus. The integration respects Zendesk's enterprise governance features (SSO, audit trails, data residency, role-based access). Brainfish ships SOC 2 Type II, ISO 27001, GDPR, customer-managed encryption keys, and regional data residency as default capabilities.

Does the Brainfish + Zendesk integration require a custom Zendesk app installation?

Most integration surfaces work via the standard Zendesk APIs and OAuth, with no custom app development needed. The Agent Workspace agent-assist surface uses the Brainfish Zendesk app available in the Zendesk marketplace. Custom workflows that integrate with Zendesk Sunshine or Zendesk Sell can be configured if a team needs them.

Do we need to migrate content into Brainfish to use it with Zendesk?

No. Brainfish reads content in place from Zendesk Guide and other sources. No content migration into a Brainfish CMS is required. Zendesk Guide remains the authoring surface for Zendesk Guide articles; Brainfish ingests them alongside other sources (product docs, wikis, past tickets, internal playbooks) into a normalized retrieval index.

How long does the Brainfish + Zendesk integration take to deploy?

Most teams reach full Brainfish + Zendesk production deployment in 1 to 2 weeks. Week one connects content sources and configures the Zendesk AI feed and Agent Workspace surfaces. Week two enables Live Agent Handoff and content operations. First measurable AI accuracy lift typically shows up inside 30 days; sustained gains compound over 90 to 180 days.

What is Brainfish Live Agent Handoff for Zendesk?

Brainfish Live Agent Handoff is a capability that transfers a customer from the Brainfish AI to a Zendesk human agent inside the same conversation window. The full AI exchange (messages, retrieved sources, confidence scores) loads into the agent's view automatically. The customer never re-explains and the agent never starts blind. Generally available to Brainfish + Zendesk customers as of May 2026.

Does Brainfish replace Zendesk AI?

No. Zendesk AI (bots, suggested replies, Conversation Mining, intent detection) continues to operate inside Zendesk. Brainfish feeds Zendesk AI a normalized, multi-source content index that improves Zendesk AI's production accuracy. Zendesk AI remains the AI surface inside Zendesk; Brainfish is the upstream content layer that determines what Zendesk AI can read.

Does Brainfish replace Zendesk?

No. Brainfish is an AI knowledge layer that sits alongside Zendesk Support as upstream content infrastructure. Zendesk remains the system of record for tickets, queues, routing, SLAs, the Agent Workspace, and reporting. Brainfish reads from Zendesk Guide as one content source, feeds Zendesk AI and other Zendesk-native AI surfaces, and runs content operations across the combined index without changing the Zendesk product.

Share this post

Daniel Kimber

May 18, 2026

CEO & Co-founder, Brainfish

The Complete Guide to Brainfish + Zendesk 2026