> For the complete documentation index, see [llms.txt](https://docs.concurrence.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors.md).

# Dynamic Behaviors

Reusable guidance that a service pins and a model chooses to apply on the caller turns where it seems to fit: how it is chosen, how long it stays, and what it cannot do.

A dynamic behavior is guidance that a model chooses to apply on the caller turns where it seems to fit. It says when it applies, with a condition and examples of what a caller says, and what the reply does while it applies, with an instruction. One behavior can serve several states of a service, and it changes through its own versions rather than through a Context Graph version.

{% hint style="info" %}
**Where to go next:** [Dynamic Behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors) in the developer guide covers the API, and [Author Dynamic Behaviors](https://docs.concurrence.com/developer-guide/platform-api/workspaces/authoring-dynamic-behaviors) covers how to write them. The Classic API has a separate resource with different fields. See [Dynamic Behaviors (Classic API)](https://docs.concurrence.com/developer-guide/classic-api/core-api/dynamic-behaviors) and [If You Use Classic Dynamic Behaviors](#if-you-use-classic-dynamic-behaviors).
{% endhint %}

## The Library and Pins

A workspace keeps its behaviors in a library of **sets**. A set is one behavior: a name, optional tags, and numbered **versions**. A version cannot be edited. The next change is the next version.

A service does not run a set. A version set on the service **pins** an exact version of each set it uses, with a flag for whether the pin is enabled and, optionally, the states it applies in. Calls and conversations run the service's `release` version set.

| Level   | Holds                                                                    | Changes by                                                                |
| ------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------- |
| Set     | Name and tags                                                            | Renaming, retagging, archiving, or restoring. No version is written.      |
| Version | Condition, examples, instruction, mode, sticky turns, note               | Writing the next version. A version cannot be edited.                     |
| Pin     | Set, version, enabled flag, states, in order, on a service's version set | Saving the version set: moving, disabling, reordering, or clearing a pin. |

This split has three consequences:

* A later version of a set changes nothing a service runs until its pin moves.
* Rolling back is moving the pin to an earlier version. That version's condition, examples, and instruction read exactly as they were written. The set's name, which the selector also reads, is the set's current name.
* A behavior is switched off per service, by disabling its pin. A disabled or moved pin applies to calls and conversations that load the service's configuration afterward, and a call or conversation already in progress can keep the configuration it loaded. A set has no off switch, and a set that any version set pins cannot be archived.

A service whose version sets pin no enabled behavior runs every turn as it would without the library.

## How a Behavior Is Chosen

On each caller turn, a model called the selector chooses one behavior or none from the behaviors offered on that turn, so at most one behavior is in force at a time. A caller turn is a caller's spoken turn on a call or a caller's message in a text conversation. The selector reads the recent conversation, including tool results. It reads what the platform knows about the caller, which is the same context the reply reads. It also reads the current state's name and objective, the current time, the behavior in force, and how many caller turns it has held. For each offered behavior, it reads its set's name, condition, and examples.

The offered behaviors are the enabled pins that apply in the state the conversation is in when the turn starts. A pin with no states applies in every action and data collection state. Decision and annotation states offer none.

The instruction, tags, version note, mode, and sticky turns do not reach the selector. There is no keyword or similarity matching and no priority field (pin order can break a tie but is not one), so the name, condition, and examples must carry everything that sets one behavior apart from its neighbors.

The choice is a model's judgment. A behavior may not apply on a turn that matches its condition, and may apply on one that does not. Guidance in a prompt does not make a reply deterministic. When several behaviors fit, the selector is asked to choose the closest, and to keep the behavior in force while the topic continues, so the result can depend on what was already in force.

Greetings, injected events, silence check-ins, and tool results start no choice. The behavior in force carries across them.

## What the Reply Follows

Of a behavior, only the instruction reaches the reply. A behavior with no instruction can be chosen and recorded, and it adds nothing to the reply. Because one behavior is in force at a time, applying it ends the behavior that was in force, and that behavior's guidance stops.

The instruction reaches the reply when the conversation is in an action or data collection state that the pin applies in. It also reaches the navigation of an action state that the pin applies in, as that state's last guideline, below every other guideline and guardrail.

| Mode            | What the instruction does in the reply                                                                                       |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `add` (default) | Adds guidance that yields to every action guideline. Where the two conflict, the reply is told to follow the guideline.      |
| `replace`       | Stands in for the reply's action guidelines: the graph's, the state's, and the channel override's are left out of the reply. |

In both modes the reply keeps the state's objective, the graph's and the state's boundary constraints, and the state's guardrails. The reply is told which guidance wins when two conflict. The platform's core instructions, the crisis resource guidance, the empathy priority when it applies, and every action guideline (the boundary constraints and guardrails included) take precedence over the instruction. The instruction takes precedence over the agent's persona, its behavioral and communication guidance, and progress toward the state's objective. Boundary constraints and guardrails steer the model, and the platform does not enforce them on the reply, so verify them against representative scenarios. Replace mode changes the reply only: navigation keeps all of its guidelines in both modes.

Writing or pinning a replace-mode version needs the same workspace permissions as `add` mode: a workspace `admin` or `owner`. See [Permissions](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors#permissions).

## Scoping to States

A pin's `states` list narrows a behavior to part of the workflow. An empty list means every action and data collection state. A behavior is offered only on caller turns that start in a state it applies in.

Each name must be an action or data collection state of the Context Graph version the version set runs. The platform checks this when the pin is saved. It also refuses a Context Graph version that drops a state a pin names, for version sets that follow the graph's latest version. See [Checks on a Pin](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors#checks-on-a-pin).

## How Long a Behavior Stays

`sticky_turns`, from 1 to 5, is the fewest caller turns a behavior stays in force once applied, counting the turn it was applied on. With 3, a behavior is in force on the turn it applies and the next two, and on the fourth a choice of none ends it, unless the selector says with enough confidence that it still applies.

Within that minimum, only another behavior that the selector chooses with enough confidence replaces it. After it, a behavior stays only while the selector keeps choosing it or says with enough confidence that it still applies, and it ends when the caller moves on. There is no maximum: a behavior that is kept on every turn stays as long as the topic continues. An answer that carries no confidence (`confidence` is `null` in the record) counts as having enough.

For example, with a Billing questions behavior at `sticky_turns` of 3, one possible conversation runs:

| Caller turn                               | What the selector does     | Outcome                       |
| ----------------------------------------- | -------------------------- | ----------------------------- |
| "Why did I get a bill for my last visit?" | Chooses Billing questions. | `applied`                     |
| "Are you open on Saturday?"               | Chooses none.              | `held`                        |
| "And is parking free?"                    | Chooses none.              | `held`                        |
| "Thanks, that's all."                     | Chooses none.              | `none`, and the behavior ends |

If the selector gives no usable answer, no behavior applies. The behavior in force stays through its minimum and ends afterward.

A behavior in force also ends when:

* A caller turn starts in a state where its pin does not apply.
* The platform recognizes that the caller asks for a person. That turn runs no choice, and its reply is rendered as on a service with no behaviors.
* The turn is at the highest empathy tier, Hold Space. See [Empathy Adaptation](https://docs.concurrence.com/agent/reasoning-engine.md#empathy-adaptation).
* The platform recognizes that a caller describes a medical emergency or self-harm. No behavior applies for the rest of that conversation.
* An operator takes over a call or authors a text turn.

Recognizing an emergency or a request for a person is a pattern check on the caller's words, in English and Spanish. It covers a limited set of phrasings and can miss others, and on a turn it misses, the behavior in force stays in force and the choice runs. See [Runtime Safety](https://docs.concurrence.com/operations-and-safety/runtime-safety.md).

## Limits That Shape Design

* **Timing differs between text and calls.** On text channels the reply waits for the turn's choice, so a behavior chosen on a turn shapes that turn's reply. A service with enabled behaviors can take longer to answer a text message than the same service without them. On platform-managed voice (`concurrence`), the reply does not wait by default: a choice ready when navigation finishes can shape that reply, and a slower one takes effect from a later reply. A service can configure a bounded wait for the choice before a platform-managed voice reply starts, which can increase response time. Speech-to-speech sessions do not use this wait. A choice still running when the caller speaks again is dropped, and the behavior in force stays as it was.
* **Navigation sees a behavior from the next caller turn.** Navigation, which moves the conversation between states, starts before the turn's choice lands, so a behavior chosen on a caller turn does not steer the navigation that starts that turn. It steers an action state's navigation from the next caller turn. It also steers the navigation that runs after a tool result later in the same exchange, such as [completion-gated navigation](https://docs.concurrence.com/agent/context-graphs.md#action-state-extensions), once the choice has landed.
* **A behavior limited to a state is not offered on the turn that enters it.** The offered behaviors depend on the state the conversation is in when the turn starts, before that turn's navigation. A behavior limited to a state is offered from the next caller turn. Guidance needed on the first turn in a state belongs in that state's own guidelines or in a behavior with no states.
* **On `gpt_realtime`, a behavior takes effect from a later reply.** The agent starts its reply as the caller stops speaking, before that turn's choice is made, so a behavior chosen on a caller turn usually shapes the replies from the caller's next turn. See [Speech-to-Speech Voice Families](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors#services-on-gpt-realtime).
* **Behaviors run on some voice families, not all.** Behaviors run on text channels and on three voice families: the `concurrence` cascade (platform-managed voice), `gpt_realtime`, and `gpt_live` (GPT-Live). `eleven_realtime`, `grok_voice`, and `phonic` run no behaviors: a service whose voice runtime is one of them cannot pin an enabled behavior, and the write is refused. See [Choosing a Realtime Voice Family](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration#choosing-a-realtime-voice-family) for each family's workflow scope.

## What a Behavior Is Not

* **Not routing.** A behavior adds no transition and no exit condition, and it cannot force a move to another state. Transitions come from the Context Graph's exit conditions. Its instruction is also a guideline in an action state's navigation from the next caller turn, so it can influence which action or exit navigation picks. Write instructions about how to reply, not where to go.
* **Not tool binding.** A behavior changes guidance only. It does not add, remove, or replace the agent's tools.
* **Not a safety mechanism.** A behavior is text in a model's prompt, chosen by a model's judgment. Express safety-critical behavior in the Context Graph, tool permissions, and escalation instructions, then verify it against representative scenarios, as [Runtime Safety](https://docs.concurrence.com/operations-and-safety/runtime-safety.md) describes.

## If You Use Classic Dynamic Behaviors

The Classic API has its own dynamic behavior sets, with triggers and actions. The closest Platform counterparts are:

| Classic                                                            | Closest Platform counterpart                                          | What to do                                                                               |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| A set holds a list of conversation triggers and a list of actions. | A set is one behavior: a condition, examples, and an instruction.     | Create one set for each behavior you want to carry over.                                 |
| Triggers are matched to a message by similarity.                   | The selector reads a condition and examples on each caller turn.      | Write the condition as a sentence about the caller and the examples as what callers say. |
| `inject-instruction` with `overrides_instructions` of `false`.     | `add` mode.                                                           | Copy the instruction text into the version.                                              |
| `inject-instruction` with `overrides_instructions` of `true`.      | `replace` mode, which stands in for the reply's action guidelines.    | Start in `add` mode.                                                                     |
| `change-tool-candidates`.                                          | None: a behavior does not change the agent's tools.                   | Bind the tools on the state in the Context Graph.                                        |
| `is_active` on a set.                                              | `enabled` on each pin.                                                | Disable the pin on each service.                                                         |
| Version sets apply a set to a service.                             | A version set pins an exact version of each set.                      | Pin the version each service runs.                                                       |
| Invocation history.                                                | The behavior on each reply and, on a call, each caller turn's choice. | Read them as [See What Applied](#see-what-applied) describes.                            |

Library writes allow 10 requests per minute for each credential and route, so a script that carries over many behaviors backs off on `429`. See [Limits](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors#limits).

A Classic behavior that carries a safety rule, such as an emergency protocol, is not a good fit for a Platform behavior: a behavior is not a safety mechanism, and no behavior applies once the platform recognizes an emergency. Put the rule in the Context Graph's boundary constraints, guardrails, and escalation instructions.

## See What Applied

Every reply the agent generates from the conversation records the behavior it was rendered with. A line the agent did not generate that way, such as a filler, an emergency script, a correction, or an operator's words, records none, even while a behavior is in force. A call also records what each caller turn's choice did, including the turns where no behavior applied and why, and that per-turn record is on the call detail for about a day after the call. See [Read What Applied](https://docs.concurrence.com/developer-guide/platform-api/workspaces/dynamic-behaviors#read-what-applied).

## Related Pages

* [Context Graphs](https://docs.concurrence.com/agent/context-graphs.md) define the states that behaviors apply in.
* [Runtime Safety](https://docs.concurrence.com/operations-and-safety/runtime-safety.md) describes the controls that guidance does not replace.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
