Deploy and test a background agent
Use this guide after configuring an agent on a managed runtime such as Willow Agents. It applies the definition to the runtime and checks that the intended job works.
For a Custom runtime, follow runtime integration and verify your harness separately. Provider-specific requirements are in the platform reference.
Before you deploy
Check that:
- the system prompt and runtime configuration are saved;
- required tools and skills are assigned and enabled;
- every required tool integration has the intended authentication identity;
- the agent is Active and its runtime is configured.
On Willow Agents, check your Willow token balance before testing. Each session uses Willow tokens.
Deploying writes fresh gateway credentials to the managed platform and replaces its previous platform token. Manual tokens are not affected, so outside callers keep working across deploys. An integration's connected account is a separate credential; see Agent credentials.
Deploy
- Open Build > Background Agents and select the agent.
- Select the deployment action in the header. Depending on state, it reads Deploy, Redeploy, or Deploy changes. The platform card under Settings > Deployment & Sync also exposes deployment.
- Wait for the deployment result.
- Open Overview and check Synced, the deployed version, and deployment time.

If deployment fails, inspect the error and use Troubleshooting.
For coding agents with configured Git repositories, deploy again after changing the repository list.
Test a tool call
- On Overview, select Test.
- Send a small request that explicitly requires an assigned tool. For a repository-reading agent, request the owner and default branch of a named repository.
- Check the response and the tool call used to obtain it. Confirm that the call succeeded and its arguments identify the intended resource.
- Open Sessions to inspect the conversation and its events. Compare the returned data with the agent's response.
- Use Monitor > Logs to inspect the corresponding gateway tool call. See Investigate with Logs.
A successful result includes a real tool response. Active and Synced describe permission and deployment state; they do not establish working application authentication.

Deploy updates
After changing the prompt, capabilities, model, or runtime configuration, save the changes and deploy again. Repeat the smallest test affected by the change.
Deploy through the API
Use Sync Background Agent to deploy through the Admin API. The endpoint retains the name /sync; see its request/response contract for details. Admin API Invoke is a separate operation with its own platform requirements.
Next steps
- Dashboard and agent state for status and sync fields.
- Give an agent access to tools if the run fails on authentication.
- Troubleshoot an agent for other failures.