> 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.md).

# Context Graphs

Structured state machines that define conversation flow, decision points, and safety boundaries for agent workflows.

Context graphs define the authored workflow available to an agent: states, transitions, objectives, guidance, boundaries, and state-bound tool specifications. Model-driven navigation still has probabilistic failure modes, so use simulations and runtime safety controls rather than treating graph text as a formal guarantee.

A Context Graph describes the work; the [world model](https://docs.concurrence.com/data/world-model.md) supplies selected facts about the people and resources involved. The [agent](https://docs.concurrence.com/agent/agents.md) supplies broader identity and guidance. Read the architecture and authoring sections first, then use the state and tool sections for the execution details.

A service runs a Context Graph unless its agent version carries a [direct program](https://docs.concurrence.com/agent/direct-programs.md), one authored set of instructions and tool grants that runs with no graph.

## The State-Based Architecture

Context graphs differ from scripted dialog trees and unconstrained prompt-only agents in three ways:

1. **States, not scripts**: The graph defines states and transitions, not a fixed sequence of utterances. Model-driven states select among authored actions and exits from the available conversation context.
2. **Variable authoring detail**: Different regions can carry different amounts of objective, guidance, boundaries, guardrails, and tool configuration. These instructions steer behavior, but they do not by themselves make model output deterministic.
3. **Incomplete by design**: Context graphs define workflow shape but not the full performance. The complete picture combines the graph's structure, the agent's identity and directives, state-level guidance, available tools, selected memory context, and channel policy.

The agent navigates the graph by evaluating which state to enter next based on the conversation so far, the patient's data, and the constraints defined on each transition.

Context graphs allow agents to:

* **Make safety intent reviewable** - place escalation guidance, boundary constraints, and state-specific guardrails next to the workflow step they govern.
* **Carry workflow state across turns** - track the current state and, for data-collection states, collected and remaining fields.
* **Vary guidance by task risk** - author more explicit constraints for sensitive steps and broader objectives for exploratory ones.
* **Reuse structure across supported channels** - apply channel overrides where voice and text behavior should differ.
* **Inspect observed paths** - use traces and simulation evidence to find untested or poorly performing states.

## From Protocol to Practice

Context graphs can encode clinical protocols and service workflows as state machines that an author reviews against the source protocol. Explicit states and exits make authored intent and observed navigation paths inspectable. They do not expose hidden model reasoning or replace clinical, compliance, and release review.

## Varying Constraint by State

"Context density" is an authoring heuristic, not a persisted state property. Authors vary constraint using the fields the runtime actually reads: objectives, actions, navigation guidance, boundary constraints, typed guardrails, exit conditions, tool bindings, and turn policy. A multi-state `gpt_realtime` session reasons from the current action state only. It reads that state's objective, actions, guidelines, tool bindings, boundary constraints, guardrail descriptions, and navigation guidance, with the graph's global guidance. The model requests a move through `change_state`, which offers the current state's exits. The model can miss a move and stay in the current state.

Use more explicit guidance and narrower exits for sensitive steps, and broader objectives for conversational steps. Validate the resulting behavior in simulations, because added prompt detail is not equivalent to deterministic phrasing or a hard policy control.

## Bounded Multi-State Traversal

On the platform-managed runtime, navigation within a turn can leave an action state, pass through decision and annotation states, and land on an engageable action or data-collection state. Decision states select an authored exit, and annotation states inject authored internal guidance without a user-facing turn. The navigator detects loops and enforces an iteration cap instead of allowing an arbitrary number of internal transitions.

<figure><img src="https://3635224444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvcLyiHRcwv7g83p6vxAd%2Fuploads%2Fgit-blob-37f3ee5e10f75671690c00552005b00d200a5743%2Fcontext-graph-traversal.svg?alt=media" alt="An illustrative Context Graph traversal moves from an action state through an authored decision and an annotation or data-collection path to a next action. Traversal is bounded and does not make model decisions deterministic."><figcaption><p>Illustrative path. The authored graph determines the eligible transitions.</p></figcaption></figure>

Initial and terminal states are configured as action states. A turn can nevertheless engage through a data-collection state, so do not infer that every user-visible turn begins and ends on an action state. Traces record observed states, transitions, and actions. They do not expose hidden chain-of-thought reasoning.

### GPT Realtime Action-State Graphs

`gpt_realtime` accepts one action state or 2 to 12 action states with unique names and exit targets that exist in the graph. For a multi-state graph, both `new_user_initial_state` and `returning_user_initial_state` must name the first state. The platform applies a model-requested move and waits for the voice provider to acknowledge the new state's instructions and tools before continuing. Test each intended move with representative caller requests.

A `gpt_realtime` service runs its enabled [dynamic behaviors](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors.md). `preload`, `wait_for`, `surface_spec_template`, `turn_policy`, and `channel_overrides` have no effect on `gpt_realtime`. Outbound calls require a single action state. `eleven_realtime` requires exactly one action state, with no enabled dynamic behaviors and no `navigate_on_completion`. Neither family accepts typed guardrails on an action state, so write those rules as the state's boundary constraints. See [GPT Realtime Multi-State Workflows](https://docs.concurrence.com/developer-guide/platform-api/workspaces/voice-configuration#gpt-realtime-multi-state-workflows).

## Integration with Memory and State Guidance

Context graphs do not run in isolation. At each state, the agent can receive selected [Functional Memory](https://docs.concurrence.com/agent/memory.md) context and applies the state's authored guidance, turn policy, and tool specifications, subject to the [runtime-specific scope](#gpt-realtime-action-state-graphs). Conditional behavior should be visible in states and transitions so teams can review and simulate it directly. Guidance that should apply on some caller turns across several states can be a [dynamic behavior](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors.md) that a service pins.

{% content-ref url="/pages/Kii5Ga5iQp6e9fEKbQ0t" %}
[Dynamic Behaviors](https://docs.concurrence.com/agent/context-graphs/dynamic-behaviors.md)
{% endcontent-ref %}

## State Types Reference

Each state type serves a specific purpose in managing conversation flow and agent behavior.

| State Type          | Purpose                                                                               | Typical Use                                                                                                         |
| ------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| **Action**          | Deliver user-facing responses within guardrails                                       | Conversational turns, report delivery                                                                               |
| **Decision**        | Select among authored exits using current inputs                                      | Routing between workflows, escalation decisions                                                                     |
| **Annotation**      | Inject preset guidance into the agent's reasoning, then advance to a fixed next state | Steer reasoning between states without an extra model turn (for example, inject a reminder before a sensitive step) |
| **Data Collection** | Collect structured fields from the caller with surface fallback                       | Insurance intake, demographic verification, medication lists                                                        |

Data-collection states define fields to gather, a completion transition, turn limits, and an optional [surface](https://docs.concurrence.com/channels/surfaces.md) fallback. The fallback can build a form from remaining fields after the configured number of turns; creation and delivery still depend on entity context and a supported Surface channel.

The same graph can support voice and text runtimes, but channel capabilities and delivery semantics differ. Use channel overrides and test each enabled channel separately.

### Designing a State

Each state definition should answer five questions before it ships to production:

1. **Objective** - What outcome must be true before the state can exit?
2. **Guidance** - Which ordered actions or prompts keep the model on the intended path?
3. **Boundaries** - Which behaviors are forbidden, especially for safety or compliance?
4. **Exit criteria** - What explicit signals trigger each transition, and which state follows?
5. **Tooling and memory configuration** - Which tool calls are exposed in this state, and should active memory retrieval be skipped?

State tool-call specs gate workflow tools bound to that state. Runtime-provided system tools and shared platform tools can also be exposed when the service and channel enable them, so state bindings are not a universal inventory of every callable tool. On the platform-managed runtime, turn policy can further block supported system tools such as forwarding.

### Binding Conversation Context

A service can declare named string or number inputs that an application supplies when starting a conversation. A state's tool binding selects which matching parameters receive those stored values, so the model does not need to supply them. This is application input for that conversation, separate from world-model facts, Functional Memory, and verified identity.

The service owns the accepted schema; the graph owns the binding. Bindings can fill direct-tool parameters and companion-skill inputs, hide them from the model, and override model-supplied values. Aliases map a parameter to a differently named accepted context key and reject execution when that source is missing. On voice calls, a binding to a declared key that the call did not start with fails closed until the key is set on the live call, and companion-skill inputs cannot bind such a key. Result persistence and tool authorization remain separate controls. Follow [Pass Context to Tool Parameters](https://docs.concurrence.com/developer-guide/guides/conversation-context) for setup, supported paths, and channel-identity limitations.

### Action State Extensions

Action states support several optional workflow controls. The asynchronous and channel-specific controls include:

* **Wait conditions** - A state can declare a `wait_for` condition that holds graph navigation until the condition clears (e.g., a surface submission or human approval). The engine retains the current state and supplies waiting guidance to the response model. That guidance can permit questions, reassurance, or small talk. It is not a deterministic restriction on generated wording.
* **Surface templates** - A state can include a surface spec that requests [surface](https://docs.concurrence.com/channels/surfaces.md) creation on state entry. Creation requires valid entity context and a successful platform request.
* **Channel overrides** - Per-channel overrides for objective and action guidelines. When the same context graph runs across voice and SMS, overrides let each channel tailor behavior without duplicating the entire state definition.
* **Completion-gated navigation** - A tool call spec can set `navigate_on_completion`. After a successful result, the engine re-evaluates navigation without waiting for another user message. An error result, such as an integration endpoint's 4xx or 5xx response, is not a successful result. The navigator can remain in the state or select another valid state, so this option does not guarantee that every completion advances.
* **Code entry** - A tool call spec can set `expects_code`. While that tool is the next step in the conversation, voice turn detection waits longer before it decides the caller has finished, so a caller can read a code in groups with pauses between them. It defaults to `false` and changes only how voice turns end.

### Tool Dispatch Configuration

Each tool a state binds carries three independent dispatch axes that control *when* the tool runs, *how* its result re-enters the conversation, and *whether* the work is tied to the turn that asked for it. All three default to the historical behavior, so existing services are unaffected.

* **Execution** - `blocking` (default) awaits the tool inline within the turn, so its result is in hand before the agent continues. `background` dispatches it off-turn so the agent keeps the floor and the result arrives later. Use `background` for work that can take longer than the caller should wait in silence.
* **Delivery** - `interrupt` (default) surfaces the result as soon as it is ready, as a fresh continuation turn. `queue` folds the result silently into the next user turn instead. Two combinations are rejected when you save the context-graph version: a `background` tool may not use `queue` (a fire-and-forget result that never surfaces is a silent dead-end), and a tool in the terminal state may not be `background` (there is no later turn to deliver into).
* **Lifecycle** - `independent` (default) lets a `background` task continue after the launching turn, but later delivery still depends on the channel and conversation remaining deliverable. `coupled` ties the task to the turn that launched it: if the user sends another message or the conversation closes first, the task is cooperatively superseded and its result is dropped. This axis is currently meaningful for background work on text and chat paths. Voice uses its own teardown behavior.

The lifecycle axis decides what happens to a `background` result once the conversation has moved on:

<figure><img src="https://3635224444-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FvcLyiHRcwv7g83p6vxAd%2Fuploads%2Fgit-blob-a85dd74505b20e007f19418fcb42bd3dae926d0b%2Fbackground-result-lifecycle.svg?alt=media" alt="A background tool’s lifecycle determines whether a result remains eligible. Independent results survive a newer turn; coupled results can be discarded when their originating turn is superseded. Delivery follows its separate binding."><figcaption><p>Eligibility does not mean immediate speech. Delivery mode is configured separately.</p></figcaption></figure>

### Tool Result Persistence

A state-tool binding also controls which arguments and results remain in conversation history and later prompts:

| Mode           | Conversation journal                                                  | Later prompts                                                      |
| -------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------ |
| **Accumulate** | Retains each call's arguments and result                              | Renders the retained results, subject to normal context management |
| **Override**   | Still retains every call                                              | Renders only the latest result per tool name                       |
| **Ephemeral**  | Retains redacted execution metadata, without raw arguments or results | Excludes those entries from reconstruction                         |

Accumulate is the default. Override reduces repeated prompt context but does not delete earlier results from storage.

Ephemeral persistence requires workspace authoring enablement and is supported only on the inline text and simulation path. When its runtime rendering capability is enabled, raw arguments and results can inform the current reasoning transaction. With rendering disabled, the transaction still runs and journals redacted metadata, but the raw payload is not supplied to the model. Voice, background, and external realtime sessions reject an ephemeral graph during initialization. Ephemeral bindings must use interrupt delivery, and queue delivery is rejected.

This setting governs the tool payload in the conversation journal and prompt reconstruction. It is not a deployment-wide zero-retention policy: a tool's destination, an external write, or information repeated in the agent's response has its own handling rules.

## Automated Optimization Through Agent Forge

[Agent Forge](https://docs.concurrence.com/reference/agent-forge.md) lets coding agents inspect, author, validate, and apply Context Graph configuration. Use simulation and production evidence to propose changes, then review the diff and rerun relevant suites before promotion. Forge does not make graph optimization automatic or guarantee that a configuration change improves outcomes.

{% hint style="info" %}
**API naming:** The Classic API represents Context Graphs as `service_hierarchical_state_machine` resources. See [Agents and Context Graphs](https://docs.concurrence.com/developer-guide/classic-api/core-api/agents-and-context-graphs). Platform services bind separate agent and Context Graph versions through version sets. See [Services](https://docs.concurrence.com/developer-guide/platform-api/workspaces/services).
{% endhint %}


---

# 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.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.
