使用方法
- 复制安装命令，在自己的智能体环境安装前先检查源码包。
- 从原始文档核对所需工具、凭据和支持的宿主。
- 说明输入材料与期望交付物，并对照来源检查输出。
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-agent-api-integration-patterns开始前需了解
- 安装不包含模型订阅、API 额度或访问文件的权限。
- 仓库星数和安装量反映活跃情况，不等于独立质量或安全测试。
仓库原始内容
按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。
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
| Pattern | Description | Delivery | Notes |
|---|---|---|---|
| Website chat | Embed agent chat on a site/app | Streaming | Token brokered server-side; browser never sees the secret |
| Headless automation | Automate functionality without UI | Sync | Server-to-server; ideal for jobs/workflows |
| Platform connector | Connect to Slack, Teams, custom workflows | Sync or streaming | Standardized REST calls per platform SDK |
| Agent-to-agent | One agent invokes another | Sync | Build an agentic ecosystem; watch credit consumption |
Reference Client Architecture
Structure any integration around four layers:
- Token service — mints and caches the client-credentials token, refreshes before expiry, and keeps the secret server-side.
- Session manager — starts sessions (
externalSessionKeyper conversation), trackssessionId+sequenceId, and ends sessions. - Message loop — serializes turns per session (one request in flight), builds the message body, attaches variables.
- Response handler — parses sync
Informor consumes the SSE stream; renders citations; capturesfeedbackId.
[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
401and 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,
500transient) 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, andexternalSessionKeyfor 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
