Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.encoreos.io/llms.txt

Use this file to discover all available pages before exploring further.

Feature ID: PF-72
Version: 1.0
Last Updated: 2026-03-13
Status: ✅ Complete (Phases 1–4); Phase 4 (MCP) implemented per PF-72-PHASE-4-EXPANSION

​
Overview

PF-72 (Claude Agent SDK Integration) adds skill-aware agent execution via a new edge function ai-skill-execute and migrates existing AI edge functions to use the SDK. All integration is within Platform Foundation; there are no cross-core dependencies.

​
Integration Pattern

Pattern Type: Platform internal — consumes existing PF capabilities only. PF-72 depends on:
DependencySpecUsage
Platform AI basePF-27PHI detection, usage logging (pf_ai_usage_logs), module context
AI Provider (OpenRouter)PF-59Model routing, error handling, fallback when SDK unavailable
AI Skills SystemPF-62Skill and override loading (pf_ai_skills, pf_ai_skill_overrides); category-based tool sets; mergeSkillWithOverride logic
RAG InfrastructurePF-60Semantic search for search_documents tool and skill use_rag

​
API Contract

Consumer: Frontend via useAISkillChat hook. Endpoint: POST /functions/v1/ai-skill-execute
  • 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).
No events are published or consumed by PF-72.

​
Quick Reference

I need to…PatternLocation
Call skill-aware agent from frontendUse useAISkillChat hookSpec API Design
Invoke agent executionPOST /functions/v1/ai-skill-executeSpec API Design
Request fieldsskillCode, messages, optional stream, optional toolsSpec API Design
Response fieldscontent, usage, model, sources?, structuredOutput?, schemaValidationFailed?, toolResults?Spec API Design
DependenciesPF-27, PF-59, PF-62, PF-60Integration Pattern table above
Pattern typePlatform internal (skill-aware agent)Overview
Configure MCP for a skill (Phase 4)Allowlist + skill-to-MCP mapping; no PHI to MCPMCP Integration (Phase 4)

​
MCP Integration (Phase 4)

Status: ✅ Complete. Implemented per PF-72-PHASE-4-EXPANSION.
Phase 4 adds Model Context Protocol (MCP) server support so the agent can call external tools (e.g. Context7, Supabase MCP) in a governed way. All behavior is constrained by constitution §4.3 (AI calls through edge functions only; no PHI/PII to external services). MCP_ENABLED=false by default — set MCP_ENABLED=true only after MCP servers are configured and validated.

​
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

Request: ai-skill-execute 
{
  "skillCode": "policy_writer",
  "messages": [{ "role": "user", "content": "Draft a privacy policy section for client data." }],
  "stream": false
}
Response: ai-skill-execute 
{
  "content": "...",
  "usage": { "prompt_tokens": 120, "completion_tokens": 450, "total_tokens": 570 },
  "model": "anthropic/claude-3.5-sonnet",
  "sources": [],
  "structuredOutput": null,
  "schemaValidationFailed": false,
  "toolResults": []
}
When schemaValidationFailed === true, structuredOutput is absent; use content (e.g. Markdown fallback) and show a warning. When tools were invoked, toolResults contains { tool, result } entries. Frontend: useAISkillChat and mergeSkillWithOverride The frontend calls useAISkillChat(skillCode, …). When a skill is selected, the hook calls ai-skill-execute with that skillCode and messages. The edge function loads the skill and any org override, runs mergeSkillWithOverride (server-side), then executes via the SDK. The returned payload includes content, usage, model, and when applicable sources, structuredOutput (only if schemaValidationFailed is false), schemaValidationFailed, and toolResults. Merge affects which prompt, model, and tools are used; toolResults reflect the actual tool invocations during execution.

​
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

PatternWhen to useTradeoffs
Platform internal skill-aware agentAI must execute with skill-specific prompt, model, and tools (e.g. compliance policy writer, document search). Consumer calls useAISkillChat; edge function ai-skill-execute loads skill, runs mergeSkillWithOverride, executes via SDK, optionally runs tools like search_documents.Centralizes skill execution in edge; avoids client-side skill application only. Requires PHI detection and usage logging before execution; fallback path when skill not found or SDK fails.

​
Common Mistakes

MistakeImpactMitigation
Ignoring schemaValidationFailed in responseClient may try to parse content as structured when it fell back to MarkdownCheck schemaValidationFailed === true and show warning or retry; do not assume structuredOutput is present when this flag is set
Not handling toolResultsTool invocations (e.g. search_documents) are invisible to UI; citations or actions missingRead toolResults from response and surface sources or follow-up actions
Forgetting RAG fallbackWhen use_rag=true and PF-60 returns no sources, agent runs without RAG contextEnsure skill still produces useful output when RAG returns empty; document expected behavior in spec
Missing schema validation on requestInvalid tools or messages shape causes runtime errorsValidate request body (e.g. skillCode required, messages array) before calling ai-skill-execute

​
Deprecation (raw HTTP path)

The raw HTTP OpenRouter path used inside ai-assistant and ai-document-analyze (when SDK is unavailable or non-Anthropic model) is deprecated.
  • 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

Before releasing or integrating with ai-skill-execute:
  • 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