Reuse and update shared assistant instructions

Section ID: Guide/j94i1rg0p5#share-prompt-fragments-across-profiles

Keep a common instruction block consistent across assistants without editing every profile. This recipe creates a safety fragment, includes it in an existing nutrition-coach profile, verifies the stored sources and then updates the shared text.

The result is a reusable instruction block with a recorded fragment-set version. A fragment is prompt text, not an enforcement mechanism or a guarantee that the model follows the instruction.

Before you start

Section ID: Guide/j94i1rg0p5#get-started

Use an existing profile such as nutrition_coach and a backend secret key for the same project. Fragment and profile management take the secret key on its own, with no X-On-Behalf-Of or user JWT. The example fragment ID must not already exist.

Start with one profile and inspect its reply before adding the include to other profiles. Every later edit reaches all profiles that include the fragment; there is no per-profile rollout. Profile pins do not pin fragment content.

The example prompt uses {{.userName}}. Supply userName explicitly through prompt variables before the test send; do not rely on a declared default being inserted automatically.

Step 1: Create the block and include it in the profile

Section ID: Guide/j94i1rg0p5#create-a-fragment

Create the shared text, then use the second request below to update only the existing profile's system prompt. Keep the model and other settings in that profile. The include resolves at render time, so later fragment edits affect subsequent turns.

Request example: Create a prompt fragment. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response:

Response example: Create a prompt fragment. Example identifiers and values are illustrative; substitute authorized values.

Then include it from a profile's system prompt, via Update an agent profile:

Request example: Update an agent profile. Example identifiers and values are illustrative; substitute authorized values.

Keep the updated profile ID for the test after the source readback below.

Step 2: Check the sources and record their set version

Section ID: Guide/j94i1rg0p5#read-and-list

Read safety back to confirm the text, then list fragments and retain setVersion alongside the profile version and variables used for the test. The sample list below represents a project with previous fragment writes; use the version your project returns.

Request example: Get a prompt fragment. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {"fragment": {...}}.

Request example: List prompt fragments. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response:

Response example: List prompt fragments. Example identifiers and values are illustrative; substitute authorized values.

setVersion is the thing to notice — see below.

Select the updated profile for a conversation, set userName, and send a representative question. Follow the run to a correlated outcome using generation. Inspect the resulting behavior before reusing the include more widely.

Finished result: the stored profile includes safety, the fragment exists with the intended text, and you have a correlated test-turn outcome plus the source versions needed to investigate it. A successful turn alone does not prove that a template rendered correctly.

Recipe: change shared wording across the assistants

Section ID: Guide/j94i1rg0p5#update-a-fragment

Before editing, identify every profile and nested fragment that includes this block. Review the effect on those assistants: the update below changes the medical-advice wording for all of them on their next turn.

Request example: Update a prompt fragment. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {"fragment": {...}}.

Read the fragment and new set version after the update, then try the affected conversation again. If the wording is unsuitable, restore the earlier text through another update; reading an old set does not activate it.

Recover the text used before a change

Section ID: Guide/j94i1rg0p5#set-versions

When investigating a changed reply, use the fragment-set version recorded with that turn. Retrieve the old set, compare it with the current text and inspect the profile and variable values from the same turn.

Request example: Get a fragment set by version. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: every fragment as it existed at that version, ordered by fragmentId.

Response example: Get a fragment set by version. Example identifiers and values are illustrative; substitute authorized values.

Retire a shared block without leaving broken includes

Section ID: Guide/j94i1rg0p5#delete-a-fragment

First remove or replace the include in every dependent profile and nested fragment, then inspect a test turn. Only delete the shared block after those dependencies are handled. The request below is the final removal step, not an automatic dependency cleanup.

Request example: Delete a prompt fragment. Example identifiers and values are illustrative; substitute authorized values.

Example request headers: X-API-Key: sk_your_key_here; Content-Type: application/json. Replace the credential and user placeholders with your own authorized values.

Response: {} on success.

Check both direct and nested includes before removing the shared block. Test a dependent conversation afterward; a returned reply alone does not prove its instructions rendered.

Related

Section ID: Guide/j94i1rg0p5#related

• Agent Profiles — the profiles that include these fragments

• Import — converting an @include-based library into fragments in one call

Document ID: Guide/j94i1rg0p5