# Agentforce Labs

Build and test Salesforce agents from your coding agent. Use your own Salesforce org or connect a preconfigured LabBox through Labs.

Read as [HTML](https://labs.agentforce.com/llms.html) or [Markdown](https://labs.agentforce.com/llms.txt).

## Getting started

1. Use the user's request and supplied context. Ask only for missing details that change the result; reuse their existing Salesforce project and intended org.

2. Check `sf --version` and look for `sfdx-project.json`. Check needed flags with the installed command's `--help`; an update notice alone is not a reason to upgrade. If needed, follow the [Salesforce CLI installation guide](https://developer.salesforce.com/tools/salesforcecli) and create a project with `sf project generate --name <project-name>`.

3. Capture and parse `sf org list auth --json` inside a process; emit only the relevant alias and org ID, never raw JSON or credentials. Reuse working authentication for the intended org. A local listing is not connection proof: verify with the Organization query below before making changes. Use `--target-org <alias>` explicitly and preserve the user's default org. If login is needed, use `sf org login web --alias <alias>` where browser login is supported, or the optional Labs device flow below. A headless runtime can use device auth: the user opens the approval link in their own browser.

4. Set up the skills:

Reuse installed agentforce-generate and agentforce-test skills. Install only missing skills, preferably in the project.

For Claude Code plugins, use `claude plugin install agentforce-adlc@claude-plugins-official`; plugin skill names have the agentforce-adlc: prefix. For portable skills, use `npx skills add forcedotcom/sf-skills` and select your coding tool. Other supported options: https://github.com/SalesforceAIResearch/agentforce-adlc.

Verify the skills load. Reuse prior setup approval; ask before an unapproved global change. If discovery fails, read installed SKILL.md and references when supported; use only host-supported reload steps.

5. Follow agentforce-generate to build with Agent Script (.agent files). For an existing agent, confirm its developer name, retrieve its AiAuthoringBundle, and inspect it before editing. Reuse existing actions where appropriate.

6. Follow agentforce-test to validate the change. Start with local checks; obtain authorization before tests that deploy metadata or run live actions. Report what changed, what passed, and any remaining work.

Keep credentials, device codes, and secret responses out of chat, logs, source files, and commits. Deploy, publish, or activate only when requested, against the confirmed org. Connecting an org does not authorize changes to it.

## Optional: connect through Labs

Use this only when the user wants a Labs connection. Labs chooses their active LabBox, otherwise their connected own org, otherwise provisions a LabBox after approval. This flow cannot select an arbitrary org.

### Before requesting approval

Check only the prerequisites the chosen path needs. Reuse existing CLI auth and installed skills; do not install a new Labs CLI. Check writable Salesforce auth storage (normally ~/.sf and ~/.sfdx) and connectivity from the same command runtime that will run the CLI. Do not mistake a filesystem permission error for a missing CLI. Browser access and package-registry access are separate from CLI access to Labs and Salesforce.

A bounded, read-only Labs reachability check is: `curl --silent --show-error --output /dev/null --write-out '%{http_code}\n' --connect-timeout 5 --max-time 15 https://labs.agentforce.com/api/cli/device/code`. HTTP 405 is expected for this POST-only endpoint; it proves only that GET reached the endpoint, not that POST or the selected Salesforce host is reachable.

If the host reports a proxy/sandbox policy denial, stop that network path and name the blocked hostname and operation. A 401/403 alone does not identify whether the cause is the sandbox, edge policy, or application authorization. Do not disable proxies or TLS checks, repeat approval requests, or ask for credentials in chat to work around a denial. Use an administrator-approved network change or another authorized execution environment. If only Labs is blocked, working CLI auth for the intended org may still be reused; Salesforce itself must remain reachable. Report 429 as rate limiting and transient 5xx as service errors, not unsupported auth or invalid credentials.

### 1. Request approval

Create and poll the grant inside a process that captures responses and prints only the browser approval link/code and safe status. Do not use an HTTP tool that returns the full credential response to the model. Set SF_DISABLE_LOG_FILE=true and SFDX_DISABLE_LOG_FILE=true for credential-handling CLI child processes, and leave shell tracing off.

POST https://labs.agentforce.com/api/cli/device/code with Content-Type: application/json:

```json
{"client_name":"Your coding agent"}
```

Show the returned verification_uri_complete to the user for sign-in and approval. If absent, show verification_uri and user_code. Keep device_code private; use the returned interval and expires_in for polling and its deadline.

### 2. Poll

POST https://labs.agentforce.com/api/cli/device/token with Content-Type: application/json:

```json
{"device_code":"<returned device_code>"}
```

Run one poller and stop at the original expiry deadline.

| Response | Action |
| --- | --- |
| 400 authorization_pending | Wait the interval and retry, including while provisioning. |
| 400 slow_down | Add at least five seconds to the delay; retain the increased delay. |
| 429 | Honor Retry-After and the current polling delay. |
| Transient 502/503, 500/504 | Back off within the original deadline; honor Retry-After when present. |
| access_denied, expired_token, byoo_unavailable, or another permanent error | Stop and explain the failure. |
| 200, status ready | Stop polling and consume the credentials once. The grant cannot be replayed. |

### 3. Authenticate

Consume the response inside a private process, without returning the raw JSON as tool output, logging it, or enabling shell tracing. Choose an unused alias automatically. Before import, privately compare the returned org/username with existing CLI authorizations. A new alias does not isolate an existing username's credential file: reuse its working login, or obtain explicit authorization before replacing it. Never change the default org.

- If sf_cli.sfdx_auth_url exists, pipe it through stdin to `sf org login sfdx-url --sfdx-url-stdin - --alias <alias>`.

- Otherwise, store sf_cli.instance_url privately in INSTANCE_URL, pass sf_cli.access_token through the login process's SF_ACCESS_TOKEN environment variable and run `sf org login access-token --instance-url "$INSTANCE_URL" --alias <alias> --no-prompt`.

Verify the resulting org privately with `sf data query --query "SELECT Id, Name, IsSandbox FROM Organization" --target-org <alias> --json` before making changes. Report org.expires_at when provided as the org's availability deadline. Return to the build-and-test steps above.

## Reference

- [Start Building](https://labs.agentforce.com/start)
- [Agents](https://labs.agentforce.com/agents)
- [Build](https://labs.agentforce.com/api/docs/build.md): Choose your tool. Build Agentforce agents from a visual builder, an AI-powered IDE, or a CLI agent.
- [SF Pi](https://labs.agentforce.com/api/docs/sf-pi.md): Use SF Pi locally or launch the Labs experiment with your selected Salesforce org.
- [Agent API - Headless Communication](https://labs.agentforce.com/api/docs/agent-api.md): Control your agents programmatically via REST APIs
- [Agent Script](https://labs.agentforce.com/api/docs/agent-script.md): The programming language for AI agents. Define exactly what your agent does — and where the AI reasons.
- [Salesforce Development Skills](https://labs.agentforce.com/api/docs/skills.md): Install Salesforce skills and Claude Code plugins
- [LabBox](https://labs.agentforce.com/api/docs/org-configuration.md): A pre-configured Salesforce org with Einstein, Agentforce, Data Cloud, and messaging ready to go.

- [MCP Servers](https://labs.agentforce.com/mcp): Connect your agents to external tools and data via Model Context Protocol servers.
- [Platform MCP](https://labs.agentforce.com/api/docs/platform-mcp.md): Connect any MCP client to your org's Salesforce-hosted (Platform) MCP servers.

## Full Documentation

- [All documentation in one file](https://labs.agentforce.com/llms-full.txt)
- [Canonical public capability manifest](https://labs.agentforce.com/api/capabilities): all available tools and experiments