Skip to main content

Configure a support conversation that stays predictable

Section: DOC-MA-conversations-configuration#configure-how-your-agent-responds.

Set up a support conversation with a chosen model, bounded replies and one unresolved turn at a time. Start with thread defaults and no active profile so each setting has one clear source. Then verify a real reply before adding profiles, tools or specialized input processing.

Finished recipe: the conversation stores the intended defaults, rejects a competing send while a turn is active, and returns a correlated test reply or an explicit failure you can diagnose.

Before you start: choose the configuration source​

Section: DOC-MA-conversations-configuration#get-started.

Create a thread with the conversation recipe and keep its ID. Replace support-chat-001 in the requests below with that ID. Use your backend secret plus the authenticated user's X-On-Behalf-Of, or the documented client credential pair.

Use an unprofiled thread for the main recipe. If you already selected a profile, its configuration can replace thread defaults; either use the profile variant or create a separate unprofiled test thread. An empty profile selector cannot clear a prior selection.

Choose an allowed model for your account. The sample settings bound the answer length; they are not a promise of identical output or a total spending budget.

Step 1: Set the model and answer length​

Section: DOC-MA-conversations-configuration#generation-config.

Use the request below to set this conversation’s model and a 2,048-token answer limit. Replace the model with one accepted by your account and keep the same conversationKey through the recipe.

curl -X POST https://api.travila.ai/api/v1/llm/update-default-generation-config \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "defaultGenerationConfig": {
    "model": "anthropic/claude-sonnet-5",
    "temperature": 0.7,
    "maxOutputTokens": 2048,
    "topP": 0.9
  }
}'

Reference: Update default generation config · Request fields.

Temperature and topP tune sampling; they do not guarantee identical replies. The GenerationConfig request fields list every public field and its request validation rules. Use the update operation reference for the complete request and response.

Set the support instructions with the generation defaults​

Section: DOC-MA-conversations-configuration#system-prompt.

Add your support instructions as defaultGenerationConfig.systemPrompt to the complete configuration from step 1, then resend that object through update-default-generation-config. This operation replaces the stored generation defaults; sending only the prompt would drop the model and answer limit you just set. For an existing conversation, read its current defaults first and retain every setting you intend to keep. Keep the instructions focused on the assistant’s help; enforce permissions for account actions in your tools and application.

Step 2: Keep one unresolved turn at a time​

Section: DOC-MA-conversations-configuration#conversation-settings.

Use REJECT_NEW for this first chat flow. Your UI can keep the submitted turn pending and offer reconnect while it resolves, rather than accepting another send whose queued outcome is harder to correlate. The configuration below also caps the generation loop.

The request sets the interrupt policy and generation limit. Keep support instructions in defaultGenerationConfig, as in step 1.

curl -X POST https://api.travila.ai/api/v1/llm/update-settings \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "settings": {
    "interruptPolicy": "INTERRUPT_POLICY_REJECT_NEW",
    "maxLoops": 4
  }
}'

Reference: Update conversation settings · Request fields.

If a second send is rejected while a run is active, reconnect to the first run; do not treat that rejection as failure of the original question.

Choose enough generations for the reply and any tools​

Section: DOC-MA-conversations-configuration#max-loops.

For a text-only test, one generation is enough. If you later add a lookup tool, allow at least the initial tool call and the following synthesis generation, then check the actual outcome at the limit.

Step 3: Keep a long support thread within its context limits​

Section: DOC-MA-conversations-configuration#context-management.

For the first short test, use the default windowing strategy. Before supporting long customer histories, choose the compaction recipe or a deliberate window size. Choose the strategy before persisting it: the current update path rejects changing an explicit strategy to another one.

Step 4: Send a test question and verify the applied configuration​

Section: DOC-MA-conversations-configuration#how-settings-combine.

Read conversation-state to inspect the stored defaults and settings. Send one representative support question, retain the returned runId, and follow generation outcomes until its result is known. If the response differs from the intended configuration, use configuration precedence to find the source that took precedence.

Finished result: the stored conversation defaults and interrupt policy match your choices, and the test turn has a correlated outcome. Do not judge configuration success from an idle conversation or a saved settings response alone. Keep the conversation/run references when the result remains uncertain.

Variant: reuse the same assistant setup across conversations​

Section: DOC-MA-conversations-configuration#agent-profiles.

Once the thread-default recipe works, create and test a reusable profile for the same project. Profile management uses the backend secret alone; the conversation calls below still require the authenticated user.

Select the saved profile when creating a conversation. The illustrations below use sample nutrition and escalation IDs; replace both with the enabled support profile you created, and choose a title for your support conversation. These names do not identify preinstalled platform profiles:

{
  "title": "Nutrition check-in",
  "activeProfileId": "nutrition_coach"
}

Reference: Create a new conversation thread · Request fields.

For an existing conversation, select an enabled replacement on a send. This selection persists for later turns:

{
  "conversationKey": "thread_abc",
  "userMessage": {
    "role": "ROLE_USER",
    "content": [
      {
        "type": "CONTENT_PART_TYPE_TEXT",
        "content": "..."
      }
    ]
  },
  "setActiveProfileId": "profile_escalation"
}

Reference: Send a message to a conversation · Request fields.

Read back the selected profile and inspect a later reply. Recheck the intended tool selection when changing profiles.

Variant: personalize the profile for this customer​

Section: DOC-MA-conversations-configuration#prompt-variables.

Use profile variables for facts such as the customer's name or current plan tier. Declare the matching placeholders in the profile, set the actual values on this conversation, then send a new turn. These values persist until changed; update them when the application fact changes.

First set the customer’s name and current plan. When the plan changes later, use the second request to select only that variable in the update mask, then verify it on the next turn.

curl -X POST https://api.travila.ai/api/v1/llm/update-prompt-variables \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
  "conversationKey": "support-chat-001",
  "variables": {
    "userName": "Jane",
    "planTier": "pro"
  }
}'

Reference: Update prompt variables · Request fields.

Response: {"settings": {...}} — the merged conversation settings.

{
  "conversationKey": "support-chat-001",
  "variables": {
    "planTier": "enterprise"
  },
  "updateMask": "planTier"
}

Reference: Update prompt variables · Request fields.

Check the next turn after a value changes​

Section: DOC-MA-conversations-configuration#render-timing.

After changing planTier to enterprise, send a new question on the same conversation and check that the reply uses the updated plan. Variables render when the next turn starts; changing a value does not rewrite a reply already in progress.

Change or clear only the intended variables​

Section: DOC-MA-conversations-configuration#updatemask-semantics.

For a plan change, keep updateMask: "planTier" so unrelated values such as the customer’s name stay unchanged. To clear a variable, include its name in the mask and omit its value from the update. Read the settings back before the next send. The mask rules distinguish a selected-but-absent value from a variable that was not selected.

Supply required values before sending​

Section: DOC-MA-conversations-configuration#required-variables-and-defaults.

For this existing-conversation recipe, inspect the selected profile’s variable definitions and set userName and planTier explicitly if required. Current sends do not repeat the required-variable check, so your application must verify the values before sending, especially after changing profiles or their definitions.

When creating a thread with a selected profile, creation rejects a missing required variable without a nonempty default. A declared nonempty default suppresses that creation error but is not inserted into the prompt. Set the intended values explicitly, then verify the test reply.

Recover a conversation whose profile is unavailable​

Section: DOC-MA-conversations-configuration#when-the-active-profile-cannot-be-used.

Restore an enabled profile or select an enabled replacement before sending the customer’s question again. Keep the original conversation and inspect any already accepted turn separately.

Variant: choose what another send does during a run​

Section: DOC-MA-conversations-configuration#interrupt-policy.

Keep REJECT_NEW unless your application has a reason to replace, queue or ignore competing messages. Decide what the user sees before selecting a different policy; the queue and ignore paths do not mean that the new question produced a reply.

Variant: add only the services this assistant needs​

Section: DOC-MA-conversations-configuration#mcp-server-selection.

For a support assistant that needs an account lookup, first connect and test the server using agent tools. Select the server here, then repeat the send/tool/result recipe. A connected account alone does not add its tools to every conversation.

Variants for particular inputs and response formats​

Section: DOC-MA-conversations-configuration#advanced-generation-options.

Start with the plain text recipe. Add the options below only for a concrete input or response requirement, and inspect the returned run outcome after each change. Use the complete generation schema for all accepted fields.

Read a PDF or include web search​

Section: DOC-MA-conversations-configuration#plugins.

When the user supplies a PDF, select a supported parsing engine for that file. When the question needs web evidence, configure the search plugin separately. Attach the source through the normal conversation request and inspect whether the answer actually received the needed content.

Guide a bounded multi-step reply​

Section: DOC-MA-conversations-configuration#turn-context-turncontext.

For a reply that needs supporting tools, choose the generation limit first. Turn context is enabled by default and tells the model the generation number and remaining turns, with tool guidance based on that remaining allowance. Inspect whether the final reply explains unfinished work when the limit is reached.

Fail the request when a required file is unavailable​

Section: DOC-MA-conversations-configuration#file-resolution-fileresolution.

For a report summary that cannot be useful without the report, use the attachment recipe to select FILE_RESOLUTION_FAILURE_MODE_FAIL_GENERATION before the send. If resolution fails, the run fails before provider generation. Follow its correlated outcome: an asynchronous send can already have been accepted before the file failure occurs.

Ask for replies in the customer’s chosen language​

Section: DOC-MA-conversations-configuration#language-preference-languagepreference.

Choose the customer’s language, save the preference and send a representative question. Inspect the returned language instead of treating a saved setting as proof of the answer.

Variant: show optional reasoning beside the answer​

Section: DOC-MA-conversations-configuration#reasoning.

Add a reasoning panel only when the product needs provider-exposed reasoning alongside the answer. Follow the reasoning-panel recipe, choose a model that supports the requested controls and keep the answer usable when reasoning is absent.

Unsupported settings may be ignored or rejected. Returned CONTENT_PART_TYPE_REASONING content is provider-defined; it is not guaranteed access to full internal reasoning. Use the generation configuration reference for reasoning fields, defaults and accepted values.

Recover an unsupported model selection​

Section: DOC-MA-conversations-configuration#available-models.

Choose a model accepted for the account and suitable for the input. After an explicit selection rejection, correct the choice before submitting the task again.

Document ID: DOC-MA-conversations-configuration. Section identities and revisions.