`sf agent preview` fails with `AgentApiNotFound` against staging (aws-stage1) orgs — `stage.api.salesforce.com` missing from endpoint fallback
- Dominant language
- No language data
- Stars
- 571
- Forks
- 80
- Avg merge
- 2d 15h
- Merged PRs (30d)
- 3
Description
### Summary
`sf agent preview` (and any command routed through `requestWithEndpointFallback` in `@salesforce/agents`) **cannot reach any agent on an org served by the `stage.api.salesforce.com` SFAP gateway** (falcon instance `aws-stage1`). The fallback only tries `api.`, `test.api.`, and `dev.api.salesforce.com`, so requests to those orgs 404 on every attempt and the CLI then throws `AgentApiNotFound`, whose message tells the user to check **permissions** — sending everyone down the wrong path. The real cause is a routing 404: the request never reaches the Agent API backend.
### Steps To Reproduce
1. Authenticate to an org whose My Domain resolves to a pod on the `aws-stage1-useast2` falcon instance (SFAP gateway `stage.api.salesforce.com`).
2. Run `sf agent preview -o -n `.
3. The session fails to start.
(Repro requires an internal `aws-stage1` staging org, so a public sample repo isn't applicable — the failure is host-routing, not project-specific. Happy to provide org details privately to a maintainer.)
### Expected result
The preview session starts, the same way it does for prod / `test.` / `dev.` orgs, and the same way the agent already previews successfully in the Agent Builder UI (which routes internally through `stage.api.salesforce.com`).
### Actual result
```
Error (AgentApiNotFound): Unable to access the Salesforce Agent APIs. Ensure the
user '' has the necessary permissions and authorization to perform this action.
```
### Additional information
Root cause (verified):
- The session-create call is `POST https://api.salesforce.com/einstein/ai-agent/v1/agents/{botId}/sessions`.
- `requestWithEndpointFallback` (`src/utils.ts`) rewrites the host across `['', 'test.', 'dev.']` on each 404 → `api.`, `test.api.`, `dev.api.salesforce.com`.
- The org's actual SFAP/Hawking gateway is `stage.api.salesforce.com` (confirmed from the org's `GatewayHawkingInfo`: `endpoint=https://stage.api.salesforce.com, falconInstance=aws-stage1-useast2`).
- Backend logs confirm the CLI's request (identified by its generated `externalSessionKey`) **never reaches the Agent API service** — it 404s at the public edge because none of the attempted hosts map to the `aws-stage1` backend. The `AgentApiNotFound` message therefore misattributes a pure HTTP 404 to a permissions problem.
Suggested fix: add `'stage.'` to the fallback list (and the host-matching regex) in `requestWithEndpointFallback`. PR incoming.
Secondary (optional): even after the host fix, consider having the `AgentApiNotFound` message state that all Agent API endpoints returned 404 and list `attemptedEndpoints`, so routing failures aren't misdiagnosed as authorization failures.
### System Information
Shell: zsh (macOS)
```json
{
"cliVersion": "@salesforce/cli/2.150.6",
"architecture": "darwin-arm64",
"nodeVersion": "node-v24.18.0",
"osVersion": "Darwin 25.6.0",
"shell": "zsh",
"pluginVersions": ["agent 2.0.5 (core)"],
"dependency": "@salesforce/agents 2.2.0"
}
```
Contributor guide
Research direction
Start in src/utils.ts at requestWithEndpointFallback and inspect the fallback host list and host-matching regex. Reproduce with an aws-stage1 staging org, then verify that sf agent preview reaches the Agent API through stage.api.salesforce.com instead of returning AgentApiNotFound.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- node.js
- Domain
- api, cli
- Issue type
- Bug
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 76/100