# 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. Ask what the user wants to build or improve. Reuse their existing Salesforce project and intended org where possible.

2. Check `sf --version` and look for `sfdx-project.json`. 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. Check `sf org list --json` privately and confirm the target org. To connect an existing org, use `sf org login web --alias <alias>`; for a Labs org, follow the optional flow below. Use `--target-org <alias>` on subsequent commands and preserve the user's default org.

4. Set up the skills:

Use agentforce-generate for building and agentforce-test for testing. Check installed skills first.

For Claude Code, use `claude plugin install agentforce-adlc@claude-plugins-official`. For portable skills, use `npx skills add forcedotcom/sf-skills` and select these skills for your coding tool. The standalone ADLC package provides other installation options: https://github.com/SalesforceAIResearch/agentforce-adlc.

Ask for approval before changing the global environment. Verify the running coding agent can discover and load agentforce-generate and agentforce-test before continuing.

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.

### 1. Request approval

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 | Back off; 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

Read the response privately, without logging or shell tracing. Choose an alias with the user:

- 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.
- [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