09d2ef1a37
- Restored docs/ directory that was accidentally deleted by `git add -A` in the v0.2.3 release script - Replaced generic "P" favicon with actual paperclip icon using brand primary color (#2563EB) - Added light/dark logo SVGs for Mintlify navbar (paperclip icon + wordmark) - Updated docs.json with logo configuration for dark/light mode - Fixed release.sh to stage only release-related files instead of `git add -A` to prevent sweeping unrelated changes into release commits Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
176 lines
5.2 KiB
Markdown
176 lines
5.2 KiB
Markdown
# Agent Runtime Guide
|
|
|
|
Status: User-facing guide
|
|
Last updated: 2026-02-17
|
|
Audience: Operators setting up and running agents in Paperclip
|
|
|
|
## 1. What this system does
|
|
|
|
Agents in Paperclip do not run continuously.
|
|
They run in **heartbeats**: short execution windows triggered by a wakeup.
|
|
|
|
Each heartbeat:
|
|
|
|
1. Starts the configured agent adapter (for example, Claude CLI or Codex CLI)
|
|
2. Gives it the current prompt/context
|
|
3. Lets it work until it exits, times out, or is cancelled
|
|
4. Stores results (status, token usage, errors, logs)
|
|
5. Updates the UI live
|
|
|
|
## 2. When an agent wakes up
|
|
|
|
An agent can be woken up in four ways:
|
|
|
|
- `timer`: scheduled interval (for example every 5 minutes)
|
|
- `assignment`: when work is assigned/checked out to that agent
|
|
- `on_demand`: manual wakeup (button/API)
|
|
- `automation`: system-triggered wakeup for future automations
|
|
|
|
If an agent is already running, new wakeups are merged (coalesced) instead of launching duplicate runs.
|
|
|
|
## 3. What to configure per agent
|
|
|
|
## 3.1 Adapter choice
|
|
|
|
Common choices:
|
|
|
|
- `claude_local`: runs your local `claude` CLI
|
|
- `codex_local`: runs your local `codex` CLI
|
|
- `process`: generic shell command adapter
|
|
- `http`: calls an external HTTP endpoint
|
|
|
|
For `claude_local` and `codex_local`, Paperclip assumes the CLI is already installed and authenticated on the host machine.
|
|
|
|
## 3.2 Runtime behavior
|
|
|
|
In agent runtime settings, configure heartbeat policy:
|
|
|
|
- `enabled`: allow scheduled heartbeats
|
|
- `intervalSec`: timer interval (0 = disabled)
|
|
- `wakeOnAssignment`: wake when assigned work
|
|
- `wakeOnOnDemand`: allow ping-style on-demand wakeups
|
|
- `wakeOnAutomation`: allow system automation wakeups
|
|
|
|
## 3.3 Working directory and execution limits
|
|
|
|
For local adapters, set:
|
|
|
|
- `cwd` (working directory)
|
|
- `timeoutSec` (max runtime per heartbeat)
|
|
- `graceSec` (time before force-kill after timeout/cancel)
|
|
- optional env vars and extra CLI args
|
|
- use **Test environment** in agent configuration to run adapter-specific diagnostics before saving
|
|
|
|
## 3.4 Prompt templates
|
|
|
|
You can set:
|
|
|
|
- `promptTemplate`: used for every run (first run and resumed sessions)
|
|
|
|
Templates support variables like `{{agent.id}}`, `{{agent.name}}`, and run context values.
|
|
|
|
## 4. Session resume behavior
|
|
|
|
Paperclip stores session IDs for resumable adapters.
|
|
|
|
- Next heartbeat reuses the saved session automatically.
|
|
- This gives continuity across heartbeats.
|
|
- You can reset a session if context gets stale or confused.
|
|
|
|
Use session reset when:
|
|
|
|
- you significantly changed prompt strategy
|
|
- the agent is stuck in a bad loop
|
|
- you want a clean restart
|
|
|
|
## 5. Logs, status, and run history
|
|
|
|
For each heartbeat run you get:
|
|
|
|
- run status (`queued`, `running`, `succeeded`, `failed`, `timed_out`, `cancelled`)
|
|
- error text and stderr/stdout excerpts
|
|
- token usage/cost when available from the adapter
|
|
- full logs (stored outside core run rows, optimized for large output)
|
|
|
|
In local/dev setups, full logs are stored on disk under the configured run-log path.
|
|
|
|
## 6. Live updates in the UI
|
|
|
|
Paperclip pushes runtime/activity updates to the browser in real time.
|
|
|
|
You should see live changes for:
|
|
|
|
- agent status
|
|
- heartbeat run status
|
|
- task/activity updates caused by agent work
|
|
- dashboard/cost/activity panels as relevant
|
|
|
|
If the connection drops, the UI reconnects automatically.
|
|
|
|
## 7. Common operating patterns
|
|
|
|
## 7.1 Simple autonomous loop
|
|
|
|
1. Enable timer wakeups (for example every 300s)
|
|
2. Keep assignment wakeups on
|
|
3. Use a focused prompt template
|
|
4. Watch run logs and adjust prompt/config over time
|
|
|
|
## 7.2 Event-driven loop (less constant polling)
|
|
|
|
1. Disable timer or set a long interval
|
|
2. Keep wake-on-assignment enabled
|
|
3. Use on-demand wakeups for manual nudges
|
|
|
|
## 7.3 Safety-first loop
|
|
|
|
1. Short timeout
|
|
2. Conservative prompt
|
|
3. Monitor errors + cancel quickly when needed
|
|
4. Reset sessions when drift appears
|
|
|
|
## 8. Troubleshooting
|
|
|
|
If runs fail repeatedly:
|
|
|
|
1. Check adapter command availability (`claude`/`codex` installed and logged in).
|
|
2. Verify `cwd` exists and is accessible.
|
|
3. Inspect run error + stderr excerpt, then full log.
|
|
4. Confirm timeout is not too low.
|
|
5. Reset session and retry.
|
|
6. Pause agent if it is causing repeated bad updates.
|
|
|
|
Typical failure causes:
|
|
|
|
- CLI not installed/authenticated
|
|
- bad working directory
|
|
- malformed adapter args/env
|
|
- prompt too broad or missing constraints
|
|
- process timeout
|
|
|
|
Claude-specific note:
|
|
|
|
- If `ANTHROPIC_API_KEY` is set in adapter env or host environment, Claude uses API-key auth instead of subscription login. Paperclip surfaces this as a warning in environment tests, not a hard error.
|
|
|
|
## 9. Security and risk notes
|
|
|
|
Local CLI adapters run unsandboxed on the host machine.
|
|
|
|
That means:
|
|
|
|
- prompt instructions matter
|
|
- configured credentials/env vars are sensitive
|
|
- working directory permissions matter
|
|
|
|
Start with least privilege where possible, and avoid exposing secrets in broad reusable prompts unless intentionally required.
|
|
|
|
## 10. Minimal setup checklist
|
|
|
|
1. Choose adapter (`claude_local` or `codex_local`).
|
|
2. Set `cwd` to the target workspace.
|
|
3. Add bootstrap + normal prompt templates.
|
|
4. Configure heartbeat policy (timer and/or assignment wakeups).
|
|
5. Trigger a manual wakeup.
|
|
6. Confirm run succeeds and session/token usage is recorded.
|
|
7. Watch live updates and iterate prompt/config.
|