API tools

Mock tools taught agent behavior; production agents call real services — your ticket system, your order API, your RAG pipeline. The pattern for every integration is the same: a thin adapter that translates between the messy real service and the clean contract the model sees. The adapter is where reliability lives.

Adapter responsibilities (every tool, every time)

• Timeouts + bounded retries. A hung API call hangs the whole agent turn. Timeout at seconds, retry once with backoff on transient failures, then return a teaching error — 'order service timed out twice; try once more later in the task or escalate'. The agent handles what it's told about.
• Result shaping. The order API returns 4KB of JSON; the agent needs six fields. Shape aggressively in the adapter — every unneeded field is context spent and a distraction planted. (You learned this as chunk hygiene; it's the same budget.)
• Pagination and caps. A search tool that can return 500 results must not. Cap at a handful, return a total_found count, and let the agent narrow — 'refine your query' beats a context flood.
• Auth stays in the adapter. The agent never sees API keys, connection strings, or session tokens — tools use credentials; models use tools. No credential should ever appear in a message list.
• Idempotency keys on writes. If the agent retries issue_refund after an ambiguous timeout, the customer must not be paid twice. Pass a deterministic idempotency key (ticket + action) so the service dedupes. This one habit prevents the classic agent money-bug.

Your RAG pipeline becomes a tool (the promised moment)

from types import SimpleNamespace
from rag import retrieve, answer, parse_answer, confidence  # your Building RAG pieces

def search_docs(query: str, category: str | None = None) -> dict:
    """Adapter over the HarborDocs pipeline from Building RAG.

    RAG has no category filter — pass-through/ignored unless you add one
    to your pipeline. RAG also returns the answer and the confidence grade
    SEPARATELY, so this adapter runs both stages and merges them."""
    # 1. Retrieve context. retrieval_info carries top_score, score_gap,
    #    distinct_docs_in_top3, ...; chunks maps source_id -> chunk text.
    #    retrieve() here bundles Building RAG's retrieval-v1 stage
    #    (embed -> search -> assemble); in that course the logic lives inside
    #    the pipeline, so factor it into a retrieve() helper or inline it.
    context_block, chunks, retrieval_info = retrieve(query)

    # 2. Generate, then parse+verify into the answer dict (answer, citations
    #    [{source_id, quote, verified}], answerable, all_verified).
    raw = answer(query, context_block)
    result = parse_answer(raw, chunks, retry=lambda: answer(query, context_block))

    # 3. Compute the confidence grade SEPARATELY — it is not a key on result.
    #    Build the trace the same way the RAG lesson does, then merge it in.
    trace = SimpleNamespace(**{**retrieval_info, **result})
    grade = confidence(trace)                             # HIGH / MEDIUM / LOW

    return {
        "answer": result["answer"],
        "citations": [c["source_id"] for c in result["citations"]],
        "confidence": grade,                              # merged in here
        "answerable": result["answerable"],
    }
# The agent is told: 'confidence LOW or answerable false means the docs
# don't settle this — do not treat the answer as policy; escalate instead.'

Building RAG returns the answer and the confidence grade separately — answer() + parse_answer() produce the answer dict, and confidence(trace) computes the grade from a trace built out of the retrieval and verification stages; this adapter runs both and merges them. The citations' source_id shape transfers cleanly; confidence does not exist as a key until you add it here. And notice what transfers: the confidence signal you calibrated in Building RAG becomes a decision input for the agent — grounded answers get acted on, LOW-confidence ones trigger escalation. Layered systems pay compound interest.