How background agents work
A background agent brings together a definition of a job and a runtime that can carry it out. Willow holds the agent's instructions and permitted capabilities. The selected platform provides the runtime, and the Willow gateway governs the agent's tool calls.
A machine user supplies an identity for code you already run. A background agent also has a definition: instructions, tools, skills, runtime configuration, and ways to start work. An MCP server supplies tools; assigning a tool to an agent makes it available for that agent's job.
Instructions, tools, and skills
The system prompt describes the agent's job, what information it should use, and what result it should produce. A tool is an action the agent can call, such as reading a GitHub repository. A skill supplies reusable instructions or knowledge that help it carry out the job.
Instructions guide behavior. Assigned capabilities determine what the gateway makes available. Asking an agent to use GitHub in its prompt does not give it GitHub access; it still needs the appropriate tool and authentication.
Two identities are involved in a tool call
The agent has an identity used to authenticate to the Willow gateway. The application behind a tool also needs an identity. These credentials serve different purposes.
For a GitHub tool, the agent's gateway credentials establish which agent is calling. The GitHub authentication selection establishes which GitHub account the call uses:
- Run as the initiator uses the account of the person who started the run.
- A connected account makes calls through that account.
- A shared MCP server credential can supply the server's default identity.
An assigned tool can therefore be enabled while its application authentication is still unset. Authentication also does not broaden the tool set: the agent can use only its assigned capabilities, and the connected application's permissions still apply.
For setup, see Give an agent access to tools. The credentials reference describes exact formats and authentication options.
Definition, deployment, and readiness
Creating an agent stores its definition. On a managed runtime, deploying applies that definition to the platform. Saving a prompt or changing the tool set in Willow does not by itself establish that the deployed runtime has the new configuration.
Three separate questions determine whether the job can succeed:
| Question | What answers it |
|---|---|
| Is the agent allowed to run? | Its Active state and applicable permissions/policies. |
| Does the runtime have the intended definition? | Deployment state and version, where the platform supports deployment. |
| Can it access the applications its tools need? | Tool assignment, enabled state, and integration authentication. |
Synced answers the deployment question. It does not prove that GitHub is connected or that a tool returns the expected result. A test closes that gap by running the intended job and checking the tool result.
Different platforms have different setup and execution paths. Willow Agents hosts the runtime for you; other platforms need provider configuration or a runtime you operate. See Platforms and session credits.
Runs and conversations
A test message, API trigger, schedule, or application event can start work. Slack channel rules can start a run when a message matches the configured response mode. A trigger determines when the agent receives work; the instructions determine what it does with that work.
A session records a conversation and its events. A session key correlates related messages, such as work on one ticket or a Slack thread. Reusing a key can continue the same conversation. Configuration can instead start fresh sessions: for example, Slack's stateless mode starts each message with a new session carrying the thread transcript.
The dashboard reference describes the available trigger controls and session surfaces. For your own runtime, use the harness delivery contract.
Learn by building
Follow Create your first background agent to see these parts work together. If you already have an agent, use Deploy and test an agent to check its readiness.