Skip to main content

Reuse and update shared assistant instructions

Section: DOC-MA-profiles-prompts-prompt-fragments#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: DOC-MA-profiles-prompts-prompt-fragments#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: DOC-MA-profiles-prompts-prompt-fragments#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.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/create \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "fragment": {
    "fragmentId": "safety",
    "name": "Safety rules",
    "content": "Never give medical advice. Refer the user to a clinician when asked."
  }
}'

Reference: Create a prompt fragment · Request fields.

Response:

{
  "fragment": {
    "fragmentId": "safety",
    "name": "Safety rules",
    "content": "Never give medical advice. Refer the user to a clinician when asked."
  }
}

Reference: Create a prompt fragment · Response fields.

Then include it from a profile's system prompt, via POST /api/v1/agent-profiles/update:

{
  "profileId": "nutrition_coach",
  "profile": {
    "generationConfig": {
      "systemPrompt": "{{template \"safety\" .}}\n\nYou are a nutrition coach for {{.userName}}."
    }
  },
  "updateMask": "generationConfig.systemPrompt"
}

Reference: Update an agent profile · Request fields.

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

Step 2: Check the sources and record their set version​

Section: DOC-MA-profiles-prompts-prompt-fragments#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.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/get \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "fragmentId": "safety"
}'

Reference: Get a prompt fragment · Request fields.

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

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/list \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "page": 1,
  "pageSize": 25
}'

Reference: List prompt fragments · Request fields.

Response:

{
  "fragments": [
    {
      "fragmentId": "safety",
      "name": "Safety rules",
      "content": "Never give medical advice. Refer the user to a clinician when asked."
    }
  ],
  "totalCount": 1,
  "hasMore": false,
  "setVersion": 7
}

Reference: List prompt fragments · Response fields.

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: DOC-MA-profiles-prompts-prompt-fragments#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.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/update \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "fragmentId": "safety",
  "fragment": {
    "content": "Never give medical or dosage advice. Refer the user to a clinician."
  },
  "updateMask": "content"
}'

Reference: Update a prompt fragment · Request fields.

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: DOC-MA-profiles-prompts-prompt-fragments#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.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/get-set \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "setVersion": 7
}'

Reference: Get a fragment set by version · Request fields.

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

{
  "setVersion": 7,
  "fragments": [
    {
      "fragmentId": "safety",
      "name": "Safety rules",
      "content": "Never give medical advice. Refer the user to a clinician when asked."
    }
  ]
}

Reference: Get a fragment set by version · Response fields.

Retire a shared block without leaving broken includes​

Section: DOC-MA-profiles-prompts-prompt-fragments#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.

curl -X POST https://api.travila.ai/api/v1/prompt-fragments/delete \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
  "fragmentId": "safety"
}'

Reference: Delete a prompt fragment · Request fields.

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.

Section: DOC-MA-profiles-prompts-prompt-fragments#related.

  • Agent Profiles — the profiles that include these fragments
  • Import — converting an @include-based library into fragments in one call

Document ID: DOC-MA-profiles-prompts-prompt-fragments. Section identities and revisions.