sf-agent-api-integration-patterns

Agent API Integration Patterns

Use This Skill When

• Choosing an integration pattern for the Agent API (website, headless, connector, agent-to-agent).
• Structuring a reusable client: token management, session lifecycle, message loop, streaming, retries.
• Setting the security and resilience posture before building.

Integration Patterns

Reference Client Architecture

Structure any integration around four layers:

1. Token service — mints and caches the client-credentials token, refreshes before expiry, and keeps the secret server-side.
2. Session manager — starts sessions (externalSessionKey per conversation), tracks sessionId + sequenceId, and ends sessions.
3. Message loop — serializes turns per session (one request in flight), builds the message body, attaches variables.
4. Response handler — parses sync Inform or consumes the SSE stream; renders citations; captures feedbackId.

[Client UI / Job] → [Message loop] → [Session manager] → [Token service] → Agent API
                         ↑                                   (cache token)
                   [Response handler] ← SSE / JSON ←─────────────┘

Browser-safe pattern (website)

• Never expose the consumer secret or token to the browser.
• Front-end talks to your backend; backend brokers the token and proxies Agent API calls.
• Stream from backend to browser (SSE/WebSocket) if real-time rendering is needed.

Resilience Checklist

• Token refresh: refresh on 401 and proactively before expiry.
• Concurrency: queue turns per session; a concurrent request returns 423.
• Timeout: the API times out at 120s → surfaced as 500; set client timeouts and a user-facing fallback.
• Retries: retry idempotent failures (network, 500 transient) with backoff; do not blindly resend a message that may have partially processed.
• Session cleanup: DELETE sessions on conversation end; reap abandoned sessions.
• Government Cloud: switch base host to api.gov.salesforce.com.

Guardrails

• Server-side secret/token custody only — treat the browser as hostile.
• One in-flight request per session; serialize turns.
• Use the My Domain URL for instanceConfig.endpoint, not the Lightning URL.
• Agent API usage consumes credits (see Generative AI Usage and Billing) — budget agent-to-agent chains carefully.
• Not supported for "Agentforce (Default)" agents — confirm agent type before integrating.
• Log traceId, sessionId, and externalSessionKey for every turn to support debugging and audit.

Deliverables

• Chosen integration pattern with rationale (surface, sync vs streaming, credit impact).
• A layered client design (token / session / message / response) with concurrency and retry policy.
• A security posture doc (secret custody, token brokering, PII handling).
• A resilience matrix covering 401 / 423 / 500 / timeout / session cleanup.

Additional Resources

• Setup and tokens: sf-agent-api-setup
• Session and messaging mechanics: sf-agent-api-session-lifecycle, sf-agent-api-messaging
• Context passing: sf-agent-api-variables
• Error handling: sf-agent-api-troubleshooting
• Pre-ship review: sf-agent-api-review
• Official docs: Agent API Developer Guide, Considerations