Skip to content
TriedDocs
Deploy

Environments and version binding

Point phone numbers and API calls at environment tags such as prod and staging, so publishing and rollbacks move live traffic without editing each number.

Every agent has versions. The latest version is an editable draft; Publish freezes it. An environment tag is a named pointer (for example prod, staging or canary) to one published version, with its own dynamic variable values. Phone numbers and API calls can target a tag instead of a version number. Moving the tag to another version moves all of that traffic at once; moving it to an older version is a rollback.

Versions in short#

  • The latest version is a draft you can edit. Published versions are read-only.
  • Publish freezes the draft and starts a new one.
  • You can have several drafts and create a draft from any version (POST /create-agent-version/:agent_id with base_version).
  • Unpublished drafts can be deleted (DELETE /agent-versions/:agent_id/:version); published versions cannot.

Open the Versions and environments panel with the clock icon in the agent builder header. The Versions tab lists versions with their tags; Compare shows the differences between two versions as a Summary or a JSON diff.

Compare versions modal showing three changed fields between V0 (published, prod and staging) and the V1 draft

Environment tags#

Open the Environments tab. Each tag card shows the version it points at and Dynamic variables for calls that use this tag.

The Environments tab with prod, staging and canary tags and per-tag dynamic variables

Use the default tags#

The first time an agent's tags are read, Tried creates prod (pointing at the latest published version) and staging (pointing at nothing).

Add a tag#

Type a name in new tag, e.g. canary and click Add tag. Names are lowercase letters, digits, - and _, starting with a letter, up to 32 characters. An agent can have up to 10 tags.

Point it at a version#

Pick a published version in the tag's dropdown, or Latest published to follow every publish. Tags can only point at published versions.

Set tag variables#

Click Add variable to give the tag its own values, for example a different booking_api URL for staging.

The prod tag cannot be deleted. Other tags can be removed with the bin icon.

Tag variables#

Tag variables are added to every call that resolves through the tag. They have the lowest priority among call variables: contact fields, variables in the request, collected variables and live overrides all win over them. The call's metadata.environment_tag records which tag was used.

Bind a phone number to a tag or version#

On Phone Numbers, the Agent version card has Outbound calls and Inbound calls selectors:

Option Meaning
Agent setting (latest draft unless pinned) No binding. Calls use the version in the agent weights, or the latest version.
Latest published Always the newest published version.
Tag: prod (V0) Whatever version the tag points at.
Fixed: V3 That published version, permanently.
A number whose outbound calls are bound to the prod tag

The binding is stored per number with GET /phone-number-bindings/:n and PUT /phone-number-bindings/:n:

curl -X PUT "https://api.tried.com.au/phone-number-bindings/%2B61255501234" \
  -H "Authorization: Bearer $TRIED_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "inbound_version_ref": "prod", "outbound_version_ref": "staging" }'

Set a field to null to remove that binding.

When the binding applies#

  • Inbound: whenever the weighted pick and the inbound webhook did not choose a concrete agent_version. If the reference does not resolve (for example the tag points at nothing and there is no published version), the call uses the latest version and a warning is logged.
  • Outbound: on POST /v2/create-phone-call when the request has no override_agent_version, and either names override_agent_id or the number has exactly one outbound agent.

Version references in API calls#

Anywhere these endpoints take a version, you can pass a reference instead of a number:

Endpoint Field
POST /v2/create-phone-call override_agent_version
POST /v3/create-web-call agent_version
POST /v2/register-phone-call agent_version
GET /get-agent/:agent_id version query
Reference Resolves to
3 or "3" Version 3
latest The newest version, usually the draft
latest_published The newest published version
a tag name The tag's version; a tag that points at nothing resolves to the latest published version

GET /resolve-agent-version/:agent_id?ref=prod shows what a reference resolves to.

Tags API#

Method and path Purpose
GET /agents/:agent_id/tags List tags (creates prod and staging on first read)
POST /agents/:agent_id/tags Create { name, version?, dynamic_variables? }
PATCH /agents/:agent_id/tags/:name Move (version) or replace dynamic_variables
DELETE /agents/:agent_id/tags/:name Delete (not prod)
GET /agent-versions/:agent_id Versions with the tags on each
GET /compare-agent-versions/:agent_id?base=&target= Diff two references (default latest_published against latest)

A release workflow#

  1. Edit the draft and test it in the builder.
  2. Publish. Move staging to the new version and test on a staging number.
  3. Move prod to the new version. Every number bound to prod switches on the next call.
  4. If something goes wrong, move prod back to the previous version.