# Context Graphs
{% hint style="info" %}
**API Name**: In the REST API and SDKs, Context Graphs are represented as `service_hierarchical_state_machine` resources. See the [Developer Guide](https://docs.amigo.ai/developer-guide/core-api/agents-and-context-graphs) for endpoint details.
{% endhint %}
{% hint style="success" %}
**For Developers**: See the [REST API reference](https://docs.amigo.ai/developer-guide/core-api/agents-and-context-graphs) for endpoint details, request/response schemas, and SDK code examples.
{% endhint %}
Context graphs (API: `service_hierarchical_state_machine`) define how agents navigate a problem space. They capture the shape of a workflow - its boundaries, decision points, required actions, and safety constraints - while giving the agent room to adapt within each state. The agent follows the graph's structure but decides how to handle each step based on the patient's situation.
## 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. The agent picks its path through the graph based on what it observes at runtime.
2. **Variable constraint levels**: Different regions of the graph apply different levels of constraint. A medication-dosing state locks the agent to exact phrasing; a general check-in state gives it room to adapt.
3. **Incomplete by design**: Context graphs are intentionally partial - they define the shape of a service but not the full performance. The complete picture emerges when three elements combine: the context graph (problem structure and constraints), the agent's identity (expertise, communication style, professional judgment), and dynamic behaviors (runtime adaptations to specific situations). Think of it like theater: the context graph is the stage and blocking, the agent is the actor, and dynamic behaviors are the director's notes. None works alone.
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:
* **Enforce safety boundaries where they matter** - medication instructions, escalation triggers, and compliance checks stay locked down regardless of conversation flow.
* **Carry state across a multi-turn conversation** - the agent knows which steps are done, which are pending, and what data it still needs to collect.
* **Flex in low-stakes regions** - open-ended coaching or exploratory discussion states let the agent's personality and clinical judgment drive the interaction.
* **Reuse across channels** - the same graph runs on voice, SMS, and web chat; channel overrides handle the differences.
* **Improve from production data** - navigation patterns show which paths produce good outcomes and which states need redesign.
## Building Structured Services with Context Graphs
Context graphs encode clinical protocols and service workflows as structured state machines that agents traverse while delivering consistent care. They define what needs to happen, when it should happen, and how to handle the variations that arise in real patient interactions.
### Core Components of Service Delivery
Every healthcare service, from initial triage to ongoing care management, consists of fundamental building blocks that context graphs organize into coherent pathways:
1. **Service Entry Points**
* Initial patient engagement and needs assessment
* Understanding the patient's current situation and goals
* Determining the appropriate service pathway based on clinical criteria
2. **Clinical Decision Points**
* Moments where the agent must evaluate patient information and choose the best path forward
* Integration with clinical guidelines and protocols
* Escalation triggers for complex cases requiring human expertise
3. **Care Delivery States**
* The actual provision of information, guidance, or interventions
* Personalized responses based on patient history and preferences
* Consistent application of clinical best practices
4. **Transition Management**
* Smooth handoffs between different phases of care
* Coordination with other services or human providers
* Maintaining continuity throughout the patient journey
### From Protocol to Practice
Context graphs bridge the gap between static clinical protocols and dynamic patient interactions. They ensure that agents:
* **Follow Evidence-Based Guidelines** while adapting to individual patient needs
* **Maintain Clinical Standards** across all interactions, regardless of complexity
* **Document Decision Rationale** for compliance and quality assurance
* **Learn from Patterns** to improve service delivery over time
## Context Density Variance
Context density controls how much freedom the agent has in a given state. High-density states pin the agent to specific phrasing and narrow exit conditions. Low-density states set a goal and boundaries but let the agent decide how to get there.
Different parts of a workflow call for different density levels:
* **High-density** - strict protocol adherence with little room for deviation (e.g., regulatory disclosures, medication instructions, safety procedures).
* **Medium-density** - guided interaction with room to adapt to the patient's responses (e.g., coaching frameworks, clinical assessments).
* **Low-density** - open-ended interaction where the agent's judgment and personality lead (e.g., exploratory discussions, motivational conversations).
You set the density per state, so a single graph can move from a tightly controlled compliance disclosure into a free-form coaching conversation and back.
**Example: Varying Context Density**
**High-Density (Medical Instruction)**
{% code overflow="wrap" %}
```
User: "How should I store this medication?"
Agent: "Keep your medication in the refrigerator between 2-8°C (36-46°F).
Never freeze it.
After first use, it can be stored at room temperature below 30°C (86°F) for up to 28 days.
Always keep the cap on when not in use to protect from light."
```
{% endcode %}
**Medium-Density (Coaching Conversation)**
{% code overflow="wrap" %}
```
User: "I struggle with hunger in the evenings."
Agent: "Evening hunger can be challenging.
What types of foods typically appeal to you during those times?
Knowing your preferences helps us find suitable strategies that work with your lifestyle."
```
{% endcode %}
**Low-Density (Exploratory Discussion)**
{% code overflow="wrap" %}
```
User: "I need to figure out how to make time for self-care."
Agent: "Self-care looks different for everyone.
What activities genuinely recharge you?
Maybe we can find small pockets in your day that might work?"
```
{% endcode %}
## Multi-State Traversal: The Agent's Hidden Journey
Between two user-visible messages, the agent can traverse multiple internal states - decision nodes, memory recalls, reflections - before surfacing a response. The user never sees these intermediate steps.
### The Action State Guarantee
Every user interaction follows a fundamental rule: **agents always start and end on action states**. This means:
* Users always receive concrete, actionable responses
* The agent can take an arbitrary number of internal steps before responding
* Each action state can itself contain multiple sub-actions (tool calls, data lookups)
* Internal complexity stays invisible to the user
{% @mermaid/diagram content="flowchart LR
A1\["\[A] Action\n(user sees response)"] --> D\["\[D] Decision\n(internal routing)"]
D --> R\["\[R] Reflection\n(internal analysis)"]
D --> A2\["\[A] Action\n(user sees response)"]
R --> A2
style A1 fill:#f9f9f9,stroke:#333
style A2 fill:#f9f9f9,stroke:#333
style D fill:#fff,stroke:#999,stroke-dasharray: 5 5
style R fill:#fff,stroke:#999,stroke-dasharray: 5 5" %}
### Traversal Patterns
Between action states, agents navigate through internal states that compose into different processing patterns:
* **Simple**: `[A] action → [A] action` (direct response)
* **Analytical**: `[A] action → [D] decision → [R] reflection → [A] action` (thoughtful evaluation)
* **Memory-Enhanced**: `[A] action → [C] recall → [D] decision → [A] action` (historically-informed response)
* **Complex**: `[A] action → [R] reflection → [C] recall → [D] decision → [A] action` (deep processing)
### Three-Level Navigation Intelligence
Agents navigate these complex paths using three complementary information levels that provide both sparse global views and dense local resolution:
{% stepper %}
{% step %}
**Conceptual Level: The "Why"**
Rich service descriptions providing the "why"
* Sparse, conceptual global understanding of the entire service
* Philosophy, methodology, and overall approach
* Enables understanding of purpose across all states
{% endstep %}
{% step %}
**Structural Level: The "What"**
Abstract topology showing the "what"
* Zoomed-out global map of all possible states and transitions
* Bird's-eye view of the entire problem space
* Allows seeing multiple steps ahead
{% endstep %}
{% step %}
**Local Level: The "How"**
Detailed state guidelines providing the "how"
* Dense, high-resolution view of current state
* Specific objectives, actions, and boundaries
* Precise execution instructions
{% endstep %}
{% endstepper %}
These three levels let the agent plan several steps ahead using the structural map while executing the current step with full local detail.
### Example: Invisible Therapeutic Processing
**User**: "I've been feeling really stuck in my career lately"
**Internal Journey**:
1. `[A] get_therapeutic_agreement_get_focus` - Captures the client's concern about career
2. `[C] recall` - Retrieves past career discussions and goals from previous sessions
3. `[R] reflect_on_therapeutic_agreement` - Analyzes patterns between past aspirations and current stuck feeling
4. `[D] assess_focus_significance` - Evaluates the personal meaning of this career concern
5. `[A] get_therapeutic_agreement_get_outcome` - Explores what "unstuck" would look like for them
**User Experience**: A flowing conversation that feels deeply personalized, with the therapist demonstrating understanding of their career journey without revealing the complex analytical process happening between responses.
## Integration with Memory and Dynamic Behaviors
Context graphs do not run in isolation. At each state, the agent pulls from [Functional Memory](https://docs.amigo.ai/agent/memory) and applies behavioral rules - the graph provides the structure, memory supplies the context, and behavioral configuration adapts how each state operates.
1. **User model integration**: The user model feeds into every navigation decision. When the agent enters a state, retrieved memory - past preferences, clinical history, prior conversation outcomes - shapes which path it takes and how it applies state-level guidance.
2. **Memory layer interaction**: Different memory layers activate at different points in the graph:
* **Working memory** - active memories retrieved during state traversal feed immediate reasoning.
* **Conversation history** - recent interactions inform the current state and can trigger recall of older memories.
* **Long-term memory** - historical patterns retrieved through recall states. New information collected during the conversation can also update or recontextualize stored memories.
3. **Behavioral adaptation**: Each context graph state carries its own turn policy - controlling which tools are available, how end-of-turn detection behaves, what response constraints apply, and when escalation triggers fire. Dynamic behaviors (API: `dynamic_behavior_set`) define additional adaptation rules at the workspace level: trigger conditions (keywords, intent categories, emotion tiers, specific states), actions (turn policy overrides, instruction injection, tool exposure changes), cooldown periods, and priority ordering. This is how a medication safety signal can inject specialized verification guidance without modifying the graph structure itself.
## 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** | Choose optimal path based on real-time inputs | Routing between workflows, escalation decisions |
| **Annotation** | Tag context for downstream processing | Segment transcripts, mark compliance events |
| **Data Collection** | Collect structured fields from the caller with surface fallback | Insurance intake, demographic verification, medication lists |
Data collection states define a set of fields to gather, a completion transition, and an optional surface fallback - if the caller cannot provide the data verbally, the agent generates a [surface](https://docs.amigo.ai/channels/surfaces) form and sends it via the appropriate channel. Field configuration includes max turns before fallback triggers.
All four state types apply equally across voice and text channels - the same context graph runs on both.
### 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?
Tool availability is state-gated: the agent only sees tools listed in the current state's tool call specs. There is no global tool pool. If a tool is not in the current state's specs, the agent cannot see or call it.
### Action State Extensions
Action states support four extension fields for asynchronous workflows - particularly useful when an agent needs to send a patient a form and wait for the response before continuing.
* **Wait conditions** - A state can declare a `wait_for` condition that pauses the context graph. The agent stays in the current state, constrained to empathetic small-talk, until the condition clears (e.g., a surface submission or human approval).
* **Surface templates** - A state can include a surface spec that automatically creates a [surface](https://docs.amigo.ai/channels/surfaces) on state entry. The engine creates it via the platform API using the template's field definitions and associates it with the current entity.
* **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 be flagged with `navigate_on_completion`. When the flagged tool succeeds, the engine immediately re-evaluates the state's exit conditions rather than waiting for the next user message. This eliminates dead-end silences where the agent would re-ask questions or idle after completing a data-collection step - the agent advances to the next state as soon as the tool's work is done. Useful for states where the tool call is the entire point of the state (e.g., "save the appointment" or "submit the referral").
## Cross-Graph Navigation
Cross-graph navigation allows related problem spaces to be linked hierarchically without forming one massive graph. This preserves clean separation between domains, enables smooth transitions between specialized workflows, and prevents context overload while maintaining logical connections.
## Automated Optimization Through Agent Forge
[Agent Forge](https://docs.amigo.ai/reference/agent-forge) enables coding agents to systematically optimize context graph configurations based on performance data. Rather than manually adjusting state definitions and density calibrations, coding agents can analyze which graph structures deliver the best outcomes and programmatically modify context graphs. This makes optimization data-driven rather than manual.
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.amigo.ai/agent/context-graphs.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.
