Agent-Connected Knowledge

The most architecturally significant integration pattern emerging in enterprise knowledge management is agent-connected knowledge: AI agents that autonomously retrieve, apply, and contribute to organizational knowledge as part of their operating loop. An agent that answers a customer question retrieves the relevant product knowledge, uses it to compose the response, and — when the answer required looking up something not in the knowledge base — flags the gap for a human knowledge curator. The knowledge system and the agent system form a closed loop: agents use knowledge to act, and their actions generate signals that improve the knowledge.

1. Agent Knowledge Retrieval Agents should retrieve knowledge through the same API used by human-facing integrations — not through a separate, less-maintained path. This ensures agents operate on the same knowledge quality as human users and that the retrieval improvement loop applies to agent-originated queries. The agent query pattern should include context: the agent's current task, the user context, and the decision the agent is trying to make. Contextual queries produce contextually relevant results.
2. Agent Knowledge Contribution Agents that generate novel responses — answers not directly retrieved from the knowledge base — should contribute those responses back to the knowledge system as candidate articles, flagged for human review. Not auto-published: the human curator reviews, validates, and approves before the candidate becomes part of the knowledge base. The agent accelerates knowledge capture. The human curator maintains quality. Neither replaces the other.
3. Agent Knowledge Freshness Requirement Agents making real-time decisions require fresher knowledge than human practitioners doing periodic research. An agent handling a customer inquiry at 3pm needs competitive intelligence that reflects the competitor's announcement at 2pm. Configure agent-facing knowledge APIs to bypass caching layers that are appropriate for human-facing integrations. Agents and humans have different freshness requirements and the integration architecture must serve both.

/**
 * Agent knowledge client — retrieves context-aware knowledge
 * and contributes candidate articles back to the KM system.
 */

interface KnowledgeQuery {
  query: string;
  agentId: string;
  taskContext: string;        // What the agent is currently doing
  userContext?: string;       // Who the agent is serving
  decisionPoint?: string;     // What decision the agent needs to make
  maxResults?: number;        // Default: 5
  maxStaleness?: number;      // Seconds. Default: 300 (5 min)
}

interface KnowledgeResult {
  content: string;
  sourceId: string;
  sourceTitle: string;
  confidence: number;         // 0.0 – 1.0
  lastUpdated: string;        // ISO timestamp
  metadata: Record<string, string>;
}

interface KnowledgeContribution {
  agentId: string;
  triggerQuery: string;
  generatedContent: string;   // The novel answer the agent produced
  usedSources: string[];      // Source IDs the agent drew on
  taskContext: string;
  flagForReview: boolean;     // Always true for agent contributions
}

async function retrieveKnowledge(
  query: KnowledgeQuery
): Promise<KnowledgeResult[]> {
  const response = await fetch('/api/km/retrieve', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...query,
      // Agents bypass the standard 5-min cache
      bypassCache: query.maxStaleness !== undefined
        ? query.maxStaleness < 300
        : false,
    }),
  });

  if (!response.ok) {
    throw new Error(`KM retrieval failed: ${response.status}`);
  }

  const results: KnowledgeResult[] = await response.json();

  // Log retrieval for improvement loop
  await logRetrieval(query, results);

  return results;
}

async function contributeKnowledge(
  contribution: KnowledgeContribution
): Promise<{ contributionId: string; reviewUrl: string }> {
  const response = await fetch('/api/km/contribute', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ...contribution,
      flagForReview: true, // Always require human review
      status: 'pending_review',
    }),
  });

  if (!response.ok) {
    // Contribution failure is non-blocking — log and continue
    console.warn('KM contribution failed:', response.status);
    return { contributionId: '', reviewUrl: '' };
  }

  return response.json();
}

async function logRetrieval(
  query: KnowledgeQuery,
  results: KnowledgeResult[]
): Promise<void> {
  // Async, non-blocking — does not affect agent performance
  fetch('/api/km/retrieval-log', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      agentId: query.agentId,
      query: query.query,
      resultCount: results.length,
      topConfidence: results[0]?.confidence ?? 0,
      timestamp: new Date().toISOString(),
    }),
  }).catch(() => {/* non-critical, swallow */});
}