Integration, retrieval and protocol selection

Text description

• Ingest and parse: Load source content and convert it into usable structure.
• Chunk and enrich: Create retrievable units and attach metadata needed for search and control.
• Index and retrieve: Build searchable representations, retrieve candidates, and optionally rerank them.
• Generate with evidence: Supply selected evidence to Claude and retain attribution when auditability requires it.

Episode Eight connects the Professional architecture to enterprise systems and authoritative knowledge. By the end, you should be able to design a diagnosable retrieval pipeline, preserve identity and source applicability, select an integration protocol proportionally, and separate retrieval failure from generation failure. Now connect that architecture to changing documents, services, and permissions. Integration is where attractive model behaviour collides with identity, data shape, stale content, network boundaries, and operational scale. We will begin with retrieval-augmented generation, or R A G. A retrieval-augmented generation pipeline, usually shortened to R A G, normally ingests source content, parses it, divides it into retrievable units, enriches metadata, creates searchable representations, indexes them, retrieves candidates, optionally reranks them, and supplies selected evidence to Claude.

The generated answer should retain source attribution where the use case requires auditability. Why is chunking an architectural decision rather than a preprocessing detail? Because chunk boundaries determine whether retrieved context contains enough coherent meaning without carrying excessive irrelevant material. There is no universal chunk size. Contracts may be chunked by clauses and schedules. Policies may be chunked by headings with effective-date metadata. Call transcripts may use speaker turns and time windows. Source code may use functions, classes, modules, and dependency relationships. Preserve parent-child relationships so a retrieved clause can recover its section and document context. Metadata should support the queries and controls the system actually needs.

Text description

• Trusted caller identity: Authentication establishes which user, service, or workload is calling.
• Permission and applicability filters: Enforce tenant, role, case, document, effective-period, and other relevant controls.
• Ranked authorised evidence: Rank the permitted candidates by relevance and source authority.
• Claude context: Only selected, authorised, and applicable evidence reaches the model.

For Harbour Resolution that may include case type, jurisdiction, product, policy version, effective period, confidentiality, source authority, and tenant. Should Claude receive every chunk with high semantic similarity? No. Retrieval should filter by permissions and applicability, then rank evidence by relevance and authority before generation. Semantically similar content can still be obsolete, unauthorised, or legally inapplicable. Authorisation must be applied before restricted content enters the model context. Do not retrieve broadly and ask Claude to ignore records the user cannot access. The retrieval service should use trusted identity and enforce tenant, role, case, and document-level controls. Authentication establishes who or what is calling. Authorisation decides which operation and data that identity may access.

Text description

• Lexical search: Best suited to exact identifiers, rare terms, policy numbers, and quoted phrases.
• Semantic search: Best suited to conceptual similarity and paraphrased questions.
• Hybrid retrieval: Combines lexical and semantic search for mixed enterprise queries.
• Reranking and expansion: Can improve ordering or broaden discovery, but adds computation and may let queries drift.

The agent must not supply its own trusted role claim inside a tool argument. Service-to-service calls should use scoped credentials, short-lived tokens where supported, and traceable workload identity. Now compare retrieval methods. Lexical search is strong for exact identifiers, rare terms, policy numbers, and quoted phrases. Semantic vector search is strong for conceptual similarity and paraphrase. Hybrid retrieval combines both and often improves mixed enterprise queries. Reranking spends additional computation to order a candidate set more precisely. Query expansion or decomposition can help broad questions, but it can also drift away from the user's actual need. Every additional stage should be evaluated on representative queries.

What retrieval strategy suits a request for policy P R dash one four seven? Exact or lexical lookup with metadata filtering should dominate, because the identifier is precise. What about a request asking whether staff can contact a vulnerable customer through an authorised representative? Semantic or hybrid retrieval across policy concepts may be appropriate, followed by authority and effective-date filtering. The Professional guide explicitly asks you to match retrieval strategy to data shape and query pattern. It also asks you to evaluate progressive discovery versus monolithic context. Progressive discovery starts with a compact catalogue, index, or tool surface and retrieves deeper detail only when needed.

Text description

• Direct API: Fits a stable, purpose-built service contract owned by the application.
• CLI: Fits local automation and command-oriented workflows, with environment and shell risks controlled.
• MCP: Fits a shared capability that needs standard discovery and invocation across compatible AI clients.
• Agent-to-agent protocol: Fits independently governed agents, while adding identity, state, protocol, and trust complexity.

Monolithic context places a large body of information or capability definitions in the request upfront. Which is better? It depends on corpus size, task predictability, latency, repeated reuse, and the cost of a missed discovery step. However, large changing enterprise corpora usually favour retrieval over indiscriminate inclusion. A small stable policy packet reused across requests may benefit from prompt caching rather than a complex R A G stack. Do not build vector search simply because the workload contains documents. Now choose an integration mechanism. A direct A P I is appropriate when the application owns a stable purpose-built service contract. A command-line interface, or C L I, is useful for local automation, developer tools, and existing command-oriented workflows, but it carries environment and shell risks.

M C P provides a standard model-facing discovery and invocation layer across compatible clients and servers. Agent-to-agent communication can coordinate independently operating agents, but adds identity, protocol, state, and trust complexity. How should the architect choose? Choose the simplest mechanism that meets interoperability, discovery, security, latency, lifecycle, and ownership requirements. Protocol novelty is not business value. A private internal service used by one application may need only a well-designed A P I adapter. A shared enterprise capability intended for multiple A I clients may justify an M C P server. A batch process may call a C L I inside an isolated build environment. Two independently governed agents exchanging work may need an explicit agent protocol and signed task state rather than informal text handoffs.

Capability bloat is a central integration risk. An agent configured with dozens of irrelevant tools is slower to reason, harder to evaluate, and more dangerous when compromised or confused. Group capabilities by role and workflow stage. Use allowlists, per-tool configuration, and separate agents or services for materially different privilege. A support-drafting agent does not need user deletion just because the backend A P I supports it. Observability must cross every integration boundary. Record a trace identifier, authenticated principal, prompt and configuration version, model selection, retrieval query, selected sources, tool calls, timings, token use, errors, validation results, and human outcome where policy permits. Protect sensitive content in logs and define retention deliberately.

Text description

• Check source preparation: Compare ingestion counts, parse failures, chunk structure, metadata, and index version.
• Inspect retrieval controls: Check filters, retrieved candidates, source freshness, permissions, and applicability.
• Confirm assembled context: Verify that the correct, coherent evidence reached Claude in a useful order.
• Investigate generation: Then examine instructions, conflicting evidence, ignored exceptions, and claim verification.

A single total-latency metric cannot show whether delay came from retrieval, model generation, tool calls, retries, or approval queues. Distributed tracing or correlated event logs make stage-level diagnosis possible. Now imagine answers became wrong after a policy refresh. First compare ingestion counts, parse failures, chunk structure, metadata, embedding or index version, filter behaviour, retrieved candidates, and source freshness. Only after confirming the supplied context should you blame the generation prompt or model. What if retrieval returns correct chunks but Claude ignores the key exception buried in one of them? Investigate context ordering, chunk coherence, prompt instructions, conflicting evidence, and whether a verification pass checks claims against sources.

Retrieval success and answer faithfulness are separate metrics. Episode Eight is complete when a wrong answer can be traced through ingestion, metadata, permission filtering, retrieval, reranking, context assembly, and generation. For source navigation, use the embeddings, search-result and citation, legal summarisation, authentication, Model Context Protocol connector, and cloud-integration references. In the next episode we will build evaluations that isolate retrieval, generation, tools, safety, latency, and cost instead of treating quality as one mysterious score.