forcedotcom / forcedotcom/cli

`sf agent preview` fails with `AgentApiNotFound` against staging (aws-stage1) orgs — `stage.api.salesforce.com` missing from endpoint fallback

Open Beginner friendly
#3,645 2 comments 0 reactions 0 assignees View on GitHub
area:afdx owned by another team
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.