sshvarzman-salesforce/claude-skills

sf-service-models-api

Trust Layer GenAI integration via aiplatform.ModelsAPI from Apex.

Ver código fuente

Cómo usar

  1. Copia el comando y revisa el paquete antes de instalarlo en tu entorno de agente.
  2. Consulta las herramientas, credenciales y entornos necesarios en el documento original.
  3. Describe las entradas y el resultado deseado; contrasta la salida con las fuentes.
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-service-models-api

Antes de empezar

  • La instalación no incluye suscripción al modelo, cuota API ni permisos sobre tus archivos.
  • Las estrellas e instalaciones reflejan actividad, no una prueba independiente de calidad o seguridad.
Documento original del Skill

Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.

Models API and Trust Layer Integration

Use This Skill When

  • Designing or building Apex-side GenAI calls through aiplatform.ModelsAPI (Models REST API behind the Einstein Trust Layer).
  • Selecting which foundation model to route to for a given Service Cloud workflow.
  • Defining prompt structure, structured-output contracts, and response-parsing strategy.
  • Planning operational controls: PII handling, retries, latency budgets, governor-limit safety, and audit.

Quick Start (Code Patterns)

These four patterns cover ~90% of Models API integrations. Copy, adapt, ship. For full request/response shapes, model catalog, and retry/streaming patterns, see reference.md.

1. Apex service class skeleton

Centralize every GenAI call through one service class so prompt versioning, model swaps, and telemetry happen in one place. Use a constant for the model name; expose a test seam for mocking.

apex
public with sharing class CaseSummarizer {

    private static final String MODEL_NAME = 'sfdc_ai__DefaultGPT4Omni';

    @TestVisible
    private static String mockResponse;

    @AuraEnabled
    public static String summarize(String caseDescription) {
        if (String.isBlank(caseDescription)) return null;

        String prompt = buildPrompt(caseDescription);
        String raw = callModel(prompt);
        if (String.isBlank(raw)) return null;

        return raw.trim();
    }

    private static String buildPrompt(String caseDescription) {
        return 'You are a Service Cloud agent assistant.\n\n'
            + 'CASE DESCRIPTION:\n' + caseDescription + '\n\n'
            + 'INSTRUCTIONS:\n'
            + '- Summarize in 2 sentences max.\n'
            + '- Plain text only. No markdown, no preamble.';
    }

    private static String callModel(String prompt) {
        if (Test.isRunningTest() && mockResponse != null) {
            return mockResponse;
        }

        aiplatform.ModelsAPI modelsAPI = new aiplatform.ModelsAPI();

        aiplatform.ModelsAPI_ChatMessageRequest msg = new aiplatform.ModelsAPI_ChatMessageRequest();
        msg.role = 'user';
        msg.content = prompt;

        aiplatform.ModelsAPI_ChatGenerationsRequest body = new aiplatform.ModelsAPI_ChatGenerationsRequest();
        body.messages = new List<aiplatform.ModelsAPI_ChatMessageRequest>{ msg };

        aiplatform.ModelsAPI.createChatGenerations_Request req =
            new aiplatform.ModelsAPI.createChatGenerations_Request();
        req.modelName = MODEL_NAME;
        req.body = body;

        aiplatform.ModelsAPI.createChatGenerations_Response resp =
            modelsAPI.createChatGenerations(req);

        if (resp.Code200 == null
            || resp.Code200.generationDetails == null
            || resp.Code200.generationDetails.generations == null
            || resp.Code200.generationDetails.generations.isEmpty()) {
            return null;
        }

        return resp.Code200.generationDetails.generations[0].content;
    }
}

2. Structured output via JSON-mode prompting

When you need keys+values back (extraction, classification), specify the contract in the prompt and parse defensively. Strip code fences before deserializing — models often wrap JSON in json blocks regardless of instruction.

apex
private static String buildExtractionPrompt(String text) {
    return 'You are extracting fields from a customer message.\n\n'
        + 'TEXT:\n' + text + '\n\n'
        + 'INSTRUCTIONS:\n'
        + '- Respond ONLY with a valid JSON object with these keys:\n'
        + '  customer_name (string), severity (one of: Low, Medium, High), wants_callback (true/false).\n'
        + '- Omit a key when no clear answer exists. Do not invent values.\n'
        + '- No markdown, no code fences, no explanation.\n'
        + 'Example: {"customer_name":"Jane Doe","severity":"High"}';
}

private static Map<String, Object> parseJsonResponse(String raw) {
    if (String.isBlank(raw)) return new Map<String, Object>();
    String cleaned = raw.trim();

    if (cleaned.startsWith('```')) {
        cleaned = cleaned.replaceAll('```[a-zA-Z]*\\n?', '')
                         .replaceAll('```', '')
                         .trim();
    }

    try {
        return (Map<String, Object>) JSON.deserializeUntyped(cleaned);
    } catch (Exception e) {
        return new Map<String, Object>();
    }
}

3. Constrain enums in the prompt

For picklist-style fields, enumerate every allowed value directly. Validate after parse — never trust the model to obey.

apex
private static final Set<String> VALID_SEVERITIES = new Set<String>{ 'Low', 'Medium', 'High' };

String severity = (String) parsed.get('severity');
if (severity != null && !VALID_SEVERITIES.contains(severity)) {
    severity = null; // drop invalid
}

4. Test mock pattern

Make the model call mockable so tests run offline and deterministically.

apex
@IsTest
static void summarize_returnsModelOutput() {
    CaseSummarizer.mockResponse = 'Customer reports a flat tire on I-95. Roadside dispatched.';

    Test.startTest();
    String result = CaseSummarizer.summarize('Caller says they have a flat tire on I-95...');
    Test.stopTest();

    System.assertEquals(
        'Customer reports a flat tire on I-95. Roadside dispatched.',
        result
    );
}

Model Selection Framework

  1. Classify the task
  • Generation, classification, extraction, summarization, embedding, or chained reasoning.
  1. Match task to model class
  • Default to the org-provided GPT-class model (sfdc_ai__DefaultGPT4Omni) for general extraction and summarization.
  • Choose a long-context or reasoning-tier model only when justified by transcript length, multi-doc context, or chain-of-reasoning needs.
  • Reserve embeddings models for retrieval and similarity, not for generation.
  1. Confirm availability and entitlement
  • Verify the chosen model is enabled for the org and the running user's permission set.
  • Check Trust Layer policies for the data the prompt will carry (PII masking, retention, zero-data-retention routing).

See reference.md for the full model catalog and selection cheat sheet.

Guardrails

  • Send only the minimum data needed; rely on Trust Layer masking, never on prompt-side instruction, to protect PII.
  • Treat model output as untrusted: validate before writing to records, never eval, never inject into SOQL or HTML.
  • Cap context size deterministically (truncate by speaker turn or by token budget) — do not let user input determine call cost.
  • Fail closed on validation errors: surface the unparsed answer to a human, never silently write a malformed value.
  • Version every prompt; treat prompt changes as code changes with review and changelog.
  • One model call ≈ one HTTP callout = one transaction's callout limit slot. Batch carefully.

Deliverables

  • Model selection rationale with task class, model tier, and Trust Layer policy notes.
  • Prompt contract document (persona, instruction, data envelope, output schema, examples).
  • Apex service class boundary that encapsulates the API call, retries, telemetry, and parsing.
  • Operational plan: latency budget, timeout, retry policy, failure routing, and prompt-version changelog.

Additional Resources

  • Full model catalog, request/response shapes, embeddings API, retry patterns, and limits: reference.md
  • Companion skill for the transcript source that feeds prompts: sf-service-voice-toolkit
  • Companion skill for the composite intake pattern: sf-service-ai-intake

Relacionados por tarea

del mismo repositorio

Más Skills

Todos los Skills
sshvarzman-salesforce
Comunidad

activating-datacloud

Salesforce Data Cloud Act phase. Use this skill when the user manages activations, activation targets, data actions, or downstream delivery of Data Cloud audiences and data. TRIGGER when: user manages activations, activation targets, data actions, or downstream delivery of Data Cloud audiences and data. DO NOT TRIGGER when: the task is segment creation (use segmenting-datacloud), data retrieval/search work (use retrieving-datacloud), or STDM/session tracing (use observing-agentforce).

instalaciones
1
GitHub Stars
0
Actualizado
15 oct
sshvarzman-salesforce
Comunidad

agentforce-skills-research

Research Agentforce configuration patterns — topics, actions, instructions, CLTs, knowledge, planner behavior. Searches Salesforce docs, Trailhead, internal repos (git.soma), Slack channels, and Google Docs to find working examples, known issues, and best practices.

instalaciones
1
GitHub Stars
0
Actualizado
15 oct
sshvarzman-salesforce
Comunidad

harmonizing-datacloud

Salesforce Data Cloud Harmonize phase. Use this skill when the user works with DMOs, mappings, relationships, identity resolution, unified profiles, data graphs, or universal IDs. TRIGGER when: user works with DMOs, mappings, relationships, identity resolution, unified profiles, data graphs, or universal IDs. DO NOT TRIGGER when: the task is only about streams/DLOs (use preparing-datacloud), segments/insights (use segmenting-datacloud), retrieval/search (use retrieving-datacloud), or STDM/sessio

instalaciones
1
GitHub Stars
0
Actualizado
15 oct
sshvarzman-salesforce
Comunidad

preparing-datacloud

Salesforce Data Cloud Prepare phase. Use this skill when the user creates or manages Data Cloud data streams, DLOs, transforms, or Document AI configurations. TRIGGER when: user creates or manages Data Cloud data streams, DLOs, transforms, or Document AI configurations, or asks about ingestion into Data Cloud. DO NOT TRIGGER when: the task is connection setup only (use connecting-datacloud), DMOs and identity resolution (use harmonizing-datacloud), or query/search work (use retrieving-datacloud)

instalaciones
1
GitHub Stars
0
Actualizado
15 oct