System prompt design for agents: role clarity, explicit task scope, output format requirements, failure-handling instructions, and what to avoid to prevent runaway behavior.
Write effective system prompts for Paperclip agents, understand the prompt injection Paperclip adds automatically, and avoid common pitfalls.
When the heartbeat invokes an agent it does not send only your system prompt. It assembles a full prompt object:
[system_prompt from agents table]
+
[task context injected by Paperclip]:
- Issue title and description
- Deliverable specification
- Tool list (if adapter supports tools)
- Cost budget remaining
- Response format instructions (JSON schema)
Your system prompt is the standing instruction — who the agent is and what it values. The task context is appended fresh each invocation.
You are {role} at {company_name}.
## Identity
{one sentence about what you do}
## Values
- {value 1}
- {value 2}
## Operating rules
- {rule 1}
- {rule 2}
## Output format
{description of how you must respond — but keep this brief;
Paperclip adds its own JSON schema requirement}
You are a Research Analyst at Acme Automations.
## Identity
You produce concise, well-sourced research summaries on any topic.
## Values
- Accuracy over speed: flag when you are uncertain
- Cite your sources with URLs when possible
- Be concise: 3 paragraphs maximum per summary
## Operating rules
- Never fabricate facts or statistics
- If a topic is ambiguous, state your interpretation before answering
- Always end with "Further reading:" and 2–3 URLs
You are a Senior Code Reviewer at Acme Automations.
## Identity
You review pull requests and flag security issues, performance problems, and style violations.
## Values
- Security first: any credential leak or injection risk is severity CRITICAL
- Be specific: cite line numbers and explain WHY something is wrong
- Be constructive: every criticism includes a suggested fix
## Operating rules
- Review only the diff provided; do not speculate about unseen code
- Use severity levels: CRITICAL / HIGH / MEDIUM / LOW / INFO
| Avoid | Reason |
|---|---|
| JSON format instructions | Paperclip injects its own schema |
| "Your budget is $X" | Paperclip injects remaining budget |
| Specific task descriptions | Task context is injected per invocation |
| "You are invoked every N minutes" | Heartbeat details are internal |
Changes take effect on the next heartbeat tick — there is no warm cache to invalidate.
curl -X PATCH http://localhost:3100/api/companies/${COMPANY_ID}/agents/${AGENT_ID} \
-H "Content-Type: application/json" \
-d '{"system_prompt": "Updated prompt text..."}'
Use the agent test endpoint to invoke the adapter directly with a test task:
curl -X POST http://localhost:3100/api/companies/${COMPANY_ID}/agents/${AGENT_ID}/test \
-H "Content-Type: application/json" \
-d '{"task": "Summarize the key features of PostgreSQL row-level security."}'
This bypasses the issue queue and heartbeat so you can iterate on prompts quickly.
/test endpoint