sf-agent-api-review

Agent API Integration Review

Use This Skill When

• Reviewing an Agent API integration before it ships.
• Auditing an existing client for security, correctness, and resilience gaps.
• Producing a prioritized risk list for an Agentforce headless/chat integration.

Review Checklist

Authentication and secrets

• [ ] Consumer secret and token are server-side only; not in the browser or source control.
• [ ] Token refresh handled (proactive + on 401); no static/pasted tokens.
• [ ] ECA uses client credentials flow with the required scopes (api, refresh_token/offline_access, chatbot_api, sfap_api).
• [ ] Run As user has appropriate (least-privilege) access; bypassUser chosen deliberately.

Endpoints and environment

• [ ] instanceConfig.endpoint uses the My Domain URL, not the Lightning URL.
• [ ] Correct base host (api.salesforce.com, or api.gov.salesforce.com for Government Cloud).
• [ ] Agent is not type "Agentforce (Default)".

Session hygiene

• [ ] externalSessionKey is unique per conversation and logged for tracing.
• [ ] sessionId tracked; sessions explicitly ended (DELETE) with a sensible x-session-end-reason.
• [ ] Abandoned sessions are reaped; not relying solely on timeout.

Turn correctness and concurrency

• [ ] sequenceId increments monotonically per session.
• [ ] Exactly one request in flight per session (guards against 423).
• [ ] Turns serialized/queued client-side.

Messaging and streaming

• [ ] Sync vs streaming choice matches the surface.
• [ ] SSE parser buffers partial frames and splits on event boundaries.
• [ ] All streaming events handled: ProgressIndicator, TextChunk, Inform, EndOfTurn, ValidationFailureChunk.
• [ ] On ValidationFailureChunk, rendered chunks are cleared.
• [ ] Inform treated as authoritative full text.

Variables

• [ ] API-settable variables are external + "Allow value to be set by API".
• [ ] __c suffix stripped; $Context. prefix used correctly.
• [ ] Read-only/context variables not mutated post-start (except $Context.EndUserLanguage).
• [ ] Variable values validated before downstream use (SOQL/HTML/callouts).

Citations

• [ ] citedReferences empty-guarded; inlineMetadata optional-handled.
• [ ] Inline markers inserted by location from highest offset backward.
• [ ] Cited URLs validated; internal records navigated via recordId.

Error handling and resilience

• [ ] 400/401/404/423/500 mapped to specific handling.
• [ ] 120s timeout handled with client timeout + user-facing fallback.
• [ ] Transient vs deterministic failures distinguished for retry.
• [ ] traceId, sessionId, status logged on every failure.

Trust, safety, and billing

• [ ] Agent text treated as untrusted output (sanitized before render).
• [ ] isContentSafe respected.
• [ ] Credit/billing impact understood; agent-to-agent chains budgeted.
• [ ] Feedback capture wired (feedbackId → feedback endpoint) where useful.

Output Format

Report findings as:

• 🔴 Critical: security/correctness must-fix before ship (e.g., secret in browser, no concurrency guard).
• 🟡 Suggestion: resilience/quality improvement (e.g., add token pre-refresh).
• 🟢 Nice to have: polish (e.g., inline citation rendering).

Close with the top 3 risks and concrete mitigations.

Deliverables

• Completed checklist with pass/fail per item.
• Prioritized findings (Critical / Suggestion / Nice to have).
• Top 3 risks and mitigations.

Additional Resources

• Domain skills for each area: sf-agent-api-setup, sf-agent-api-session-lifecycle, sf-agent-api-messaging, sf-agent-api-variables, sf-agent-api-citations, sf-agent-api-integration-patterns, sf-agent-api-troubleshooting
• Official docs: Agent API Developer Guide