Reusable instructions

Write an organization-wide rule once and attach it to any agent; it is appended to the agent

Reusable instructions are named blocks of markdown that belong to your organization rather than to one agent: rules like email normalization, symbol read-back, or retry limits that every agent should follow. Attach an instruction to an agent with the reusable_instruction_ids field on Agents. At call start ThunderPhone appends each attached instruction to the end of that agent's prompt as a section headed ## <name>, in the order the instructions were created. Editing an instruction changes every agent it is attached to from their next call; deleting one detaches it everywhere and leaves each agent's own prompt untouched.

Unlike knowledge, instructions are not looked up through a tool during the call. They are part of the system prompt on every call the agent handles: inbound and outbound phone calls, web widget sessions, realtime sessions that name an agent, and test calls from the agent builder. Because they are prompt text, they count toward the agent's prompt-size surcharge: the first 5,000 estimated prompt tokens of the combined prompt are included, and each further block of 10,000 tokens adds a per-minute charge.

In the dashboard, manage instructions on the Instructions page and attach them from the Reusable instructions section of the agent builder (Attach instructions), then deploy the agent. The rest of this page covers the same flow over the API.

Endpoints#

Instruction object#

{
  "id": "0f4d6e2a-3b1c-4c8e-9a7d-2f5e6b8c9d10",
  "name": "Email normalization",
  "content": "When a caller gives an email address, read it back letter by letter and say \"at\" for @ and \"dot\" for periods before moving on.",
  "agent_count": 3,
  "created_at": "2026-09-21T18:24:10.113Z",
  "updated_at": "2026-09-21T18:24:10.113Z"
}

Create an instruction#

curl -X POST https://api.thunderphone.com/v1/reusable-instructions \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Retry limits",
    "content": "Ask for a piece of information at most twice. If it is still unclear, offer a callback instead of asking a third time."
  }'

Returns the instruction object with 201 Created. Both name and content must be non-blank; a blank value returns 400 with the field named. PATCH accepts either field on its own. Requests for an instruction id that belongs to another organization return 404.

Attach to an agent#

Attachment is an agent draft field, so it follows the same stage-then-deploy flow as every other agent setting:

curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"reusable_instruction_ids": ["0f4d6e2a-3b1c-4c8e-9a7d-2f5e6b8c9d10"]}'
 
curl -X POST https://api.thunderphone.com/v1/agents/12/deploy \
  -H "Authorization: Bearer sk_live_..."

The list replaces the agent's complete attachment set; send [] to detach everything, or omit the field (or send null) to leave it unchanged. Every id must belong to your organization, otherwise the PATCH returns 400. Test calls from the agent builder use the staged set; production calls use the deployed set. The agent response embeds the attached rows as reusable_instructions and the staged ids as draft_reusable_instruction_ids. POST /v1/agents accepts the same reusable_instruction_ids field and attaches immediately, since a new agent has no draft.

Deleting an instruction detaches it from every deployed agent immediately. If an agent has a staged reusable_instruction_ids list that still names the deleted id, its next deploy fails with 400 on reusable_instruction_ids and asks you to update or discard the draft, rather than silently deploying a smaller set than you reviewed. Version history records which instruction ids an agent had attached at each deploy, not their text: editing an instruction is not a new agent version, and the new text is used from the next call.

Test an instruction#

Attach the instruction in the agent builder (or with the PATCH above) and place a test call from the builder; test calls use the staged attachment set, so you do not need to deploy first. The section is appended after the agent's own prompt, so ask the agent about something the instruction covers and check the behavior. The composed prompt is not returned by the API: the agent's prompt field stays exactly what you wrote, and the attached instructions are listed separately as reusable_instructions.