사용 방법
- 설치 명령을 복사하고 자신의 에이전트 환경에 설치하기 전에 소스 패키지를 확인하세요.
- 필요한 도구, 인증 정보, 지원 환경은 원본 문서에서 확인하세요.
- 입력과 원하는 산출물을 설명하고 출처와 결과를 대조하세요.
npx skills add https://github.com/sshvarzman-salesforce/claude-skills --skill sf-agent-api-troubleshooting시작 전 확인
- 설치에는 모델 구독, API 한도, 파일 접근 권한이 포함되지 않습니다.
- 별점 수와 설치 수는 활동 지표이며 독립적인 품질·보안 검증이 아닙니다.
원본 Skill 문서
원본 저장소의 제목, 예시, 코드, 표, 링크, 이미지를 유지해 표시합니다.
Agent API Troubleshooting
Use This Skill When
- An Agent API call returns a non-2xx status and you need the likely cause and fix.
- A call times out or reports an unexpected media-type / config error.
- Diagnosing Government Cloud endpoint mismatches.
Error Matrix
| Status | Meaning | Likely cause | Fix |
|---|---|---|---|
| 400 Bad Request | Malformed request | Message contains "{VALUE} is not a valid agent ID" | Verify the agent ID (re-fetch via BotDefinition or Legacy URL) |
| 401 Unauthorized | Auth problem | Bad/expired token, flow not enabled | Re-mint token; confirm client credentials flow + Run As user |
| 404 Not Found | Wrong token or endpoint | Incorrect host/path; gov cloud on standard host | Verify endpoint; gov cloud must use api.gov.salesforce.com |
| 423 Locked | Session already locked | Concurrent request on the same session | Serialize turns; only one request in flight per session |
| 500 Internal Server Error | Server-side / config error | See sub-causes below | Match the message/error field below |
HTTP 500 sub-causes
| Message/Error field contains | Cause | Fix |
|---|---|---|
| "Unsupported Media Type" | Wrong Content-Type | Set Content-Type: application/json |
EngineConfigLookupException | Wrong domain in start session | Use the Current My Domain URL for instanceConfig.endpoint (not Lightning URL) |
HttpServerErrorException | Wrong agent ID in endpoint | Use the correct agent ID (see sf-agent-api-setup) |
| (timeout) | Call exceeded 120s | The API times out at 120s and returns 500; add client timeout + retry/fallback |
| other | Setup incomplete | Re-verify Get Started setup steps |
Diagnostic Workflow
- Capture status code, response
message/errorfields, andtraceId(from streaming events / logs). - Classify using the matrix above.
- Verify inputs in order: token validity → base host (standard vs gov) → agent ID →
instanceConfig.endpoint(My Domain) → headers (Content-Type,Accept). - Check concurrency if 423 — is another turn still in flight for this session?
- Re-test the isolated call (curl / Postman) before changing client code.
Guardrails
- Log
traceId,sessionId, and the HTTP status on every failure — support cases needtraceId. - Never retry a 423 immediately in a tight loop; wait for the in-flight turn to complete.
- Distinguish transient 500 (timeout, server) from deterministic 500 (config, media type) before retrying.
- On Government Cloud, a 404 usually means the standard host was used — switch to
api.gov.salesforce.com. - Re-minting the token fixes most 401s; if not, the flow/Run As configuration is wrong.
Deliverables
- A triage note per failure: status, cause, fix, and whether it's transient or deterministic.
- A retry/backoff policy that treats 423 and deterministic 500s as non-retryable-as-is.
Additional Resources
- Setup and correct endpoints:
sf-agent-api-setup - Concurrency/session rules:
sf-agent-api-session-lifecycle - Resilience design:
sf-agent-api-integration-patterns - Official docs: Agent API Troubleshooting, Considerations
