Change what an agent says

A Call Agent's instructions decide what it says on every call. In this guide, you will read the agent, change its instructions, and save the complete configuration. The same steps apply to agents for outbound and inbound calls.

PUT replaces the complete configuration. It is not a partial update. Keep every setting that should remain, including voices, webhooks, participant settings, tools, and model settings. An optional setting that you leave out can clear its current value.

Before you start

  • Complete Get access. Keep that terminal open, with RESIA_API_BASE and RESIA_API_KEY set.
  • The ID of the Call Agent, not the ID of a call. Open Agents in the portal, or list your agents with GET /v1/call-agents.

Read the agent before you edit it

read -r -p 'Call Agent id: ' CALL_AGENT_ID

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --output agent-current.json

curl --fail-with-body --silent --show-error \
  "$RESIA_API_BASE/openapi.json" --output resia-openapi.json

jq --slurpfile api resia-openapi.json \
  'with_entries(select(.key as $key | $api[0].components.schemas.CallAgentWrite.properties | has($key)))' \
  agent-current.json > agent-update.json

The last command keeps fields that the API accepts for an agent update. It removes the response-only fields. GET returns these 7 fields, and PUT refuses them with 422:

  • id
  • review_status
  • is_active
  • created_at
  • submitted_at
  • active_updated_at
  • archived_at

If you do not use jq, delete these 7 fields from the response by hand. Keep every other field. All other fields of the response are writable, including model_architecture, speech_to_speech_model, and tools. Keep agent-current.json as a record of the configuration you read.

In the portal: open Agents and select the agent. The Behavior tab shows the instructions.

API reference: Read a Call Agent.

Change the instructions

Open agent-update.json in your text editor. Change instructions to describe the conversation you want. Keep the other fields unless you intend to change them. Avoid simultaneous edits by two people; a later complete update can overwrite an earlier one.

For a greeting on an inbound call, set agent_speaks_first to true. To leave a message when an outbound call reaches voicemail, set should_leave_voicemail to true. To turn off the quiet office background sound under the agent's voice, set enable_background_noise to false. To play a fixed notice, such as This call may be recorded., to each person when their line connects, set disclaimer to that text, at most 300 characters. Set it to null to remove it. None of these settings creates an inbound number assignment.

In the portal: edit Instructions on the Behavior tab. These settings are on the Settings tab.

Run calls on a speech-to-speech model

To run the agent's calls on a speech-to-speech model, set model_architecture to speech_to_speech. Set speech_to_speech_model to a supported model, such as gpt-live-1, and set in_call_llm to null. These two settings take effect at once, without review. Inbound calls require an agent assignment on a number. A speech_to_speech Call Agent can also answer your own number on a SIP connection. Its participant legs then dial through that connection's outbound details. Its calls can use a database and custom tools. Its single, orchestration, and inbound calls can bring on additional participants with dial: on_agent_request and intro: private_first. A batch call dials as a plain call, without additional participants. voices takes only voices of the model's provider. See Speech-to-speech models. agent_speaks_first applies: with true, the agent greets first. should_leave_voicemail applies to outbound calls: with true, the agent leaves its message after the mailbox beep. disclaimer applies: the call speaks it word for word when the call connects, before the agent speaks. To return to a standard agent, set both model_architecture and speech_to_speech_model to null. See Speech-to-speech models.

Use variables correctly

Use $topic or ${topic} to insert the top-level input named topic, and declare it in input_schema.properties. A variable for an input in required needs a value on each call. A variable for an optional input with no value is empty in the instructions. See Personalize each call with inputs for the rules and a worked example.

Save the complete configuration

curl --fail-with-body --silent --show-error \
  --request PUT "$RESIA_API_BASE/v1/call-agents/$CALL_AGENT_ID" \
  --header "Authorization: Bearer $RESIA_API_KEY" \
  --header 'Content-Type: application/json' \
  --data-binary @agent-update.json \
  --output agent-updated.json

jq '{id, review_status, is_active, active_updated_at}' agent-updated.json

Expected result: HTTP 200 and the same agent id. Resia may review the new instructions before they take effect. Until then, calls use the previous approved instructions. Agent settings such as webhook URLs can take effect immediately, before instruction approval. Confirm review_status is approved before a test of the new instructions. is_active can be true while the previous version is still the active one, so check review_status too.

In the portal: select Save changes. The portal sends the complete configuration for you.

API reference: Replace a Call Agent.

In the portal

Open Agents and select the agent. The Behavior tab holds the instructions, the analysis prompt, and the input and output schemas. The Settings tab holds the conversation options, voices, participants, and webhooks. In Instructions, type @ to insert a variable from the input schema, or select + Add new variable to declare a new one.

One draft covers every tab. When you change something, an Unsaved changes bar appears. Select Save changes to save the whole agent as one new version, or Revert to drop your edits. The portal sends the complete configuration for you, so the PUT warning at the top of this guide does not apply there. If someone else changed the agent after you opened it, the portal refuses the save and asks you to revert first.

If something fails

  • 422: the update has invalid JSON, a missing required field, an invalid schema, or an undeclared variable. Read the error message before you resend the update.
  • The new instructions do not run on calls: review_status is pending_review. Calls use the previous approved version until Resia approves the new one.
  • The portal refuses to save: someone else changed the agent after you opened it. Select Revert, then make your edit again.

Next steps