Claude Agent SDK Integration – Integration Documentation

​

Overview

​

Integration Pattern

​

API Contract

• Request: skillCode, messages, optional stream, optional tools (see spec specs/pf/specs/PF-72-agent-sdk-integration.md API Design).
• Response: content, usage, model, sources?, structuredOutput?, schemaValidationFailed?, toolResults? (see spec).

​

Quick Reference

​

MCP Integration (Phase 4)

Status: ✅ Complete. Implemented per PF-72-PHASE-4-EXPANSION.

​

Allowlist

• Only allowlisted MCP servers may be invoked by ai-skill-execute.
• Allowlist is configured in edge function config or secrets (e.g. env or org-level config); no client-supplied MCP endpoints.
• At runtime, the edge function checks the skill’s requested MCP(s) against the allowlist before opening any MCP connection.

​

Skill-to-MCP mapping

• A skill declares which MCP servers it needs (e.g. via pf_ai_skills.custom_fields such as mcp_servers: string[], or dedicated columns if added later).
• buildSkillAgent (or equivalent) reads this mapping and passes only allowlisted MCP tools into the agent config.
• If a skill requests an MCP that is not allowlisted, that MCP is not attached; the agent runs with platform tools and other allowlisted MCPs only.

​

Platform engineer guide: adding a new MCP

1. Evaluate: Confirm the MCP server is compatible with the Deno edge runtime or callable via HTTP from the edge (see expansion spec Phase 4.1).
2. Security: Ensure no PHI/PII is sent in MCP requests; sanitize tool results before including in agent context (constitution §4.3.2).
3. Allowlist: Add the MCP server identifier and connection params (e.g. URL, auth) to the allowlist used by ai-skill-execute (secrets/env or org config).
4. Shared utility: Use or extend _shared/mcp-client.ts (or equivalent) for connection and tool invocation; keep allowlist check in one place.
5. Document: Add the MCP to the integration doc (this section) and to any admin/API reference that describes available MCP tools.
6. Governance: Do not allow ad-hoc or client-supplied MCP endpoints; all MCPs must be pre-configured and allowlisted.

​

References (Phase 4)

• Expansion spec: PF-72-PHASE-4-EXPANSION — user stories, data model, implementation plan, rollback.
• Constitution: §4.3 — AI integration security; no PHI/PII to external AI or MCP.

​

Code Examples

{
  "skillCode": "policy_writer",
  "messages": [{ "role": "user", "content": "Draft a privacy policy section for client data." }],
  "stream": false
}

{
  "content": "...",
  "usage": { "prompt_tokens": 120, "completion_tokens": 450, "total_tokens": 570 },
  "model": "anthropic/claude-3.5-sonnet",
  "sources": [],
  "structuredOutput": null,
  "schemaValidationFailed": false,
  "toolResults": []
}

​

Decision Tree

• Should I use ai-skill-execute or ai-assistant? → Use ai-skill-execute when a skill is selected (via useAISkillChat). Fall back to ai-assistant when no skill is active or when ai-skill-execute fails (e.g. skill not found, SDK error).
• How does skill config get applied? → Skill lookup from pf_ai_skills → load override from pf_ai_skill_overrides → mergeSkillWithOverride → SDK execution with effective prompt, model, and tools.
• What if the SDK or provider fails? → Provider fallback: retry with exponential backoff; if SDK unavailable, fall back to raw HTTP OpenRouter call per PF-59.
• When are tools like search_documents used? → Platform tools (e.g. search_documents, lookup_data, validate_schema) are invoked by the agent during execution when the skill enables tool use; results are returned in toolResults.
• How are MCP servers used (Phase 4)? → Only allowlisted MCPs; skills declare required MCPs via custom_fields (or schema). Edge function wires allowlisted MCP tools into the agent; no PHI/PII in MCP requests. See MCP Integration (Phase 4).

​

Pattern Library

​

Common Mistakes

​

Deprecation (raw HTTP path)

• Sunset date: 2026-05-24 — no new features should use this path.
• Removal target: 2026-08-22 (extensions require explicit justification).
• Migration: Call ai-skill-execute or use the SDK path; do not rely on the legacy HTTP path for new features.
• Runtime: When the deprecated path is invoked, both ai-assistant and ai-document-analyze emit a structured warn-level log with context: { model, reason, sunset, migration }.
• Implemented in: PF-72 WS5 (2026-02-24). Both functions now try Anthropic REST API first for Anthropic models, falling back to OpenRouter with deprecation warnings.

​

Pre-Flight Checklist

• Spec conformance: Implementation matches specs/pf/specs/PF-72-agent-sdk-integration.md (API Design, FR/NFR).
• Logging and usage capture: All calls logged to pf_ai_usage_logs with feature=skill_code; token/cost/duration recorded.
• PHI detection: PHI detection runs before agent execution (PF-27 behavior preserved).
• Model and tool fallback: Fallback to ai-assistant when ai-skill-execute fails; provider fallback (raw HTTP) when SDK unavailable; schemaValidationFailed and toolResults handled in client.

​

Integration Matrix

• CROSS_CORE_INTEGRATIONS.md: PF-72 is platform-internal only; row added under Platform Integration Layers for traceability.

​

References

• Spec: PF-72 Agent SDK Integration
• Phase 4 expansion: PF-72-PHASE-4-EXPANSION (MCP Integration)
• PF-27: Platform AI — Platform Integration Layers
• PF-59: AI Provider Migration (OpenRouter) — PF-59
• PF-62: AI Skills System — PF-62 Spec
• PF-60: PF-60 RAG Infrastructure