Integration decisions — reference
Integration decisions — reference
A decision-table companion to the CCAR-P Integration domain. Each table names a decision, the documented input that settles it, and the claim it does not license. Use it as a review sheet, not as a substitute for the lectures.
1. Authentication and authorization (LO2)
| Layer | Establishes | Leaves open |
|---|---|---|
| Transport credential | The identity your integration presents | Which records that identity may reach |
| Tenant resolution | Whose data the request concerns | Whether the operation is permitted |
| Operation check | That this call is allowed, now | Nothing; this is the decision |
- The API consumer obtains and refreshes the OAuth access token. A successful refresh restores the connection; it grants nothing.
- Identity attributes attached to telemetry describe your service's credential, not the end user the agent acted for.
- Put the scope check outside the model, on the resolved call. A model instruction is defence in depth, because content returned from tools and documents is untrusted and must never override the request.
Tool configuration, by intent
| Intent | Configuration |
|---|---|
| Read-only assistant | Denylist the write and destructive tools |
| Narrow explicit surface | Disable by default, then enable named tools |
| Large surface, lean context | Defer loading of descriptions — not an access control |
⚠ A configs entry naming a tool the server no longer exposes logs a backend warning and returns no error. A renamed tool silently returns to the enabled default. Re-verify named restrictions against the server's current tool list.
2. Latency (LO3)
| Term | Measures |
|---|---|
| Latency | Processing the prompt and generating an output |
| Baseline latency | Model processing, without tokens-per-second effects |
| Time to first token | From sending the prompt to the first generated token |
Order of work: engineer a prompt that meets the quality bar first, then reduce latency. Tuning prematurely can hide what top performance looks like.
| Lever | Effect | Residue |
|---|---|---|
| Model choice | Most direct lever | Must still meet the quality requirement |
| Fewer tokens in and out | Faster processing and generation | Whatever those tokens were doing |
| Output token limit | Hard cap on length | Cut may be mid-word; may need post-processing |
| Streaming | Output appears as produced | Completion time unchanged |
3. Observability (LO4)
| Signal | Carries | Default interval |
|---|---|---|
| Metrics | Token, cost, session and tool counters | 60 s |
| Log events | Prompt, request, error, tool records | 5 s |
| Traces | Interaction, model request, tool, hook spans | 5 s |
⚠ Traces need two switches, not one: their exporter and the enhanced-telemetry beta variable. Setting only the exporter produces no spans, which looks identical to an export failure.
- The CLI, run by the SDK as a child process, emits the telemetry. The SDK produces none of its own.
- Model-request, tool and hook spans are children of the enclosing interaction span. A subagent's spans nest under the parent's tool span, so a delegation reads as one trace.
- W3C trace context is propagated into the subprocess, so the agent run appears inside your application's trace.
session.idjoins several calls into one timeline. - Export failures are silent by default. A quiet collector is not evidence of health.
- Telemetry is structural by default; the agent's content is not recorded. Content opt-ins escalate to raw bodies carrying the entire conversation history, with extended-thinking content redacted. Leave them unset unless the pipeline is approved to store that data.
4. Retrieval design (LO5, LO6)
| Decision | Documented input |
|---|---|
| Retrieval unit | A chunk separated from its document can lack sufficient context; add situating context before embedding |
| Source identity | Any stable string, including an internal identifier that survives a URL change |
| Citation granularity | Break long content into logical text blocks; return only the most relevant results |
| Matcher | Semantic for meaning and paraphrase; keyword for specific terms; combine when both query shapes occur |
Two symptoms, two causes. Worse retrieval after contextualization points at truncation against a fixed embedding input limit. Higher-than-expected ingestion cost points at chunks processed out of document order, which defeats the caching the technique relies on.
Two measurements, two instruments. Retrieval quality is measured by whether the golden document appears in the first k results. Answer quality needs its own grading method: restrict the model to the provided documents, require a supporting quote per claim, and allow an honest admission of uncertainty.
| Grading method | Trade |
|---|---|
| Code-based | Fastest and most reliable; lacks nuance |
| Human | Highest quality; slow and expensive |
| Model-based | Fast and scalable; test reliability, then scale |
5. Integration mechanism (LO7)
| Constraint | Mechanism |
|---|---|
| Remote server by URL, tools only | Connector server array in the Messages API |
| Local server, or prompts and resources needed | Client-side MCP helpers with the base SDK |
| Server reachable only inside a private network | Client-side helpers, with your own MCP client inside that network |
| Deployment on Amazon Bedrock or Google Cloud | Not the connector; it is unavailable there |
Check the platform first. The connector is beta and runs on the Claude API, the Claude Platform on AWS and Microsoft Foundry. It is not available on Amazon Bedrock or Google Cloud, so the deployment target can settle the choice before anything else is asked.
It then requires a server publicly exposed over HTTP; local standard-input servers cannot be connected directly. Third-party remote servers are not endorsed by Anthropic — trust and review are the operator's responsibility.
Handoff contract. Return semantic, stable identifiers rather than opaque internal references, and only the fields the next step needs. If the receiving agent cannot confirm the same record, refuse and report rather than continue.
6. Progressive discovery (LO8)
| Pressure | Mechanism |
|---|---|
| Unused definitions loaded upfront | Tool search |
| Repeated charge for a stable prefix | Prompt caching |
| Old tool results that have served their purpose | Context editing |
| Chains of small tool calls | Programmatic tool calling |
Staged in the documented order: caching from day one; tool search past roughly 20 tools or noticeable baseline context; context editing once conversations run long enough for early results to go stale; programmatic calling for repetitive chains.
⚠ Accept a discovery rollout on task success, not on token count. A capability that stays in the catalog but is never requested does not help the user, and the documented trade adds one lookup turn that belongs inside the end-to-end timing.