> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Background Agents

> Bind unattended callers to one workspace and recover the same remote Play execution.

[Human guide: work with your agent →](https://deepline.com/docs/human/sdk-v2/background-agents.md)

Run a tested Play from an unattended caller without losing its workspace or
run identity. Start with one foreground run before enabling recurring work.

## Before you start

Have a checked, published Play and input that matches its contract. Choose an explicit `staleAfterSeconds` policy for each durable call. Edition 11 requires it. For a
daily read refresh, consider `86_400` only when the tool permits result reuse;
use `0` when each invocation needs current provider data.
An agent process, a Play schedule, and an inbound webhook are different triggers.
Choose the one that owns the work.

## 1. Bind the working folder

Authorize the operator in the intended folder. Use the supported folder binding:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline org list --json
deepline org set "Acme" --auth-scope folder --json
deepline org status --json
deepline auth status --json
```

Replace `Acme` with an accessible workspace. The CLI owns `.env.deepline`.
Do not write a sample API key into that file or rely on a mutable global
workspace selection for unattended jobs.

For CI, use protected runner secrets and
[GitHub deployment guidance](https://deepline.com/docs/sdk-v2/github-deployments.md).

## 2. Prove one foreground execution

Inspect your published Play before supplying its input. `account-refresh` below
represents a Play you have already authored and published:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline describe account-refresh --json
```

Run the reviewed input through the [calling procedure](https://deepline.com/docs/sdk-v2/calling-plays.md).
Save its returned run ID before waiting. Inspect row outcomes and scoped usage.
Do not assume a Play accepting an `accounts` array also accepts `--csv`.

## 3. Preserve execution identity

A worker restart should observe the saved run rather than blindly start another:

```bash theme={"languages":{"custom":["/languages/deepline-prompt.json"]}}
deepline runs get <run-id> --full --json
deepline billing usage --run-id <run-id> --json
```

Use [Production integration](https://deepline.com/docs/sdk-v2/production-integration.md) for durable polling,
callbacks, cancellation, and destination reconciliation.
A local timeout does not cancel remote work.

## 4. Add the recurring entry point

Use [Webhooks and schedules](https://deepline.com/docs/sdk-v2/webhooks-and-schedules.md) for Play-owned triggers.
Use your worker's scheduler only when that caller owns timing and recovery.
An agent watching a folder is custom application logic, not an automatic Play feature.

> [!TIP]
>
> The intended workspace is verified, one pilot passed, and its run ID survives
> caller restart. The recurring trigger uses the same reviewed input contract.

Configure the authored per-run credit cap where applicable. Inspect workspace
limits separately. Ask your agent to explain which component owns retries
before enabling unattended external writes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.