sshvarzman-salesforce/claude-skills

sf-service-models-api

Trust Layer GenAI integration via aiplatform.ModelsAPI from Apex.

Quelltext ansehen

Verwendung

  1. Installationsbefehl kopieren und das Quellpaket vor der Installation in der eigenen Agentenumgebung prüfen.
  2. Benötigte Werkzeuge, Zugangsdaten und Hosts im Original prüfen.
  3. Eingabe und gewünschtes Ergebnis beschreiben und die Ausgabe mit den Quellen abgleichen.
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-service-models-api

Vor dem Start

  • Die Installation umfasst weder Modellabo noch API-Kontingent oder Dateizugriffsrechte.
  • Sterne und Installationen zeigen Aktivität, keine unabhängige Qualitäts- oder Sicherheitsprüfung.
Originales Skill-Dokument

Aus dem Quell-Repository gerendert; Überschriften, Beispiele, Code, Tabellen, Links und Bilder bleiben erhalten.

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

Verwandte Aufgaben

aus demselben Repository

Weitere Skills

Alle Skills
sshvarzman-salesforce
Community

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).

Installationen
1
GitHub Stars
0
Aktualisiert
15. Okt.
sshvarzman-salesforce
Community

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.

Installationen
1
GitHub Stars
0
Aktualisiert
15. Okt.
sshvarzman-salesforce
Community

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

Installationen
1
GitHub Stars
0
Aktualisiert
15. Okt.
sshvarzman-salesforce
Community

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)

Installationen
1
GitHub Stars
0
Aktualisiert
15. Okt.