> For the complete documentation index, see [llms.txt](https://docs-conversational-ai.syntphony.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs-conversational-ai.syntphony.com/ai-agents/actions/context-variables.md).

# Context variables

## Overview

Agentic workflows rely on context to maintain continuity across Actions, API calls, AI Agent reasoning, and user interactions.

Unlike traditional request-response architectures, Agentic systems operate as evolving conversations where information collected in one step may influence decisions many steps later.

Context provides the shared memory layer that makes this possible.

Every Action execution can contribute information to the conversation, allowing the AI Agent to reason not only about the current request, but also about previously collected data, execution outcomes, and business information accumulated throughout the interaction.

The purpose of context is not simply to store data.

Its purpose is to preserve information that helps the AI Agent understand what happened, what is currently known, and what should happen next.

## Understanding the Agentic memory model

Before working with Context Variables, it is important to understand how memory flows through an Agentic system.

A typical execution follows the lifecycle below:

<figure><img src="/files/zRPPwiEOHDePQk8xZojL" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
At each stage, information may be created, enriched, reused, or updated. **Context Variables are the mechanism used to carry this information throughout the conversation**. If you want to learn more about all the supported variables in Syntphony CAI,[ check here as well.](/build-dialogs/dynamic-content-and-contexts.md#supported-variables)
{% endhint %}

## Context types

Not all information stored in the Context serves the same purpose. Some information represents an Action request, other information represents the outcome of an Action execution, and some should remain available throughout the entire conversation.

To support these different responsibilities, Agentic workflows use **three primary context structures (they work together to create a complete execution cycle):**

| Context variable                                 | Purpose                                                                             |
| ------------------------------------------------ | ----------------------------------------------------------------------------------- |
| `hiddenContext._eva.api.agentic.functionRequest` | Describes what should be executed.                                                  |
| `hiddenContext._eva.api.agentic.functionResult`  | Describes what happened after execution.                                            |
| `hiddenContext._eva.api.agentic.userData`        | Stores contextual information that should remain available during the conversation. |

## Context Variables references

<table data-header-hidden><thead><tr><th width="272.20001220703125" valign="top"></th><th width="324.199951171875" valign="top"></th><th width="151.60003662109375" valign="top"></th></tr></thead><tbody><tr><td valign="top"><strong>Agentic Variables</strong></td><td valign="top"><strong>Description</strong></td><td valign="top"><strong>Where</strong></td></tr><tr><td valign="top"><code>hiddenContext._</code><br><code>eva.api.agentic.functionRequest</code></td><td valign="top">Internal structure used to prepare and pass parameters required to execute an Action. It represents the execution intent before the Action is performed.</td><td valign="top">Field <a href="/pages/PQ1TJS6Ii2m3cTjaZWwQ#parameters">Parameters inside Actions</a><br></td></tr><tr><td valign="top"><code>hiddenContext._</code><br><code>eva.api.agentic.functionResult</code></td><td valign="top">Stores the resolution of an Action execution. Rather than acting as a simple API response container, it provides execution context to the AI Agent, describing what happened during the Action and enabling the AI Agent to determine the next conversational step.</td><td valign="top"><a href="/pages/nD2EJS2OjDUL4VGV158h#rest-connector">Service cells</a><br></td></tr><tr><td valign="top"><code>hiddenContext._</code><br><code>eva.api.agentic.userData</code></td><td valign="top">Stores contextual information that should remain available throughout the conversation. This information can include customer attributes, business information, external knowledge, API responses, or any additional context that may support future reasoning.</td><td valign="top"><a href="/pages/nD2EJS2OjDUL4VGV158h#rest-connector">Service cells</a><br></td></tr></tbody></table>

{% hint style="info" %}
These variables create a dynamic memory system that preserves information across AI Agent interactions. By properly structuring **Code cells** to read from and write to these context objects, sophisticated workflows can be built, where each Action builds on previously collected information.
{% endhint %}

## Understanding the contexts

### functionRequest

`functionRequest` represents the Action that the AI Agent intends to execute. Before an Action is executed, the necessary information must be organized and prepared. This structure acts as the execution contract between the AI Agent and the Action.

#### Example:&#x20;

```
hiddenContext._eva.api.agentic.functionRequest = {
  function: "check_balance",
  parameters: {
    phone_number: "21987476822",
    balance_type: "internet"
  }
};
```

At this stage:

* No Action has been executed;
* No result exists yet;
* And the structure only describes what should happen next.

***

### functionResult

`functionResult` stores the resolution of an Action execution. Its primary responsibility is not persistence, but to provide execution context back to the AI Agent.

Once an Action finishes, the AI Agent must understand:

* Whether the Action succeeded;
* Whether the Action failed;
* Which business outcome was produced;
* Which information became available;
* And what should happen next.

{% hint style="info" %}
`functionResult` acts as the execution contract returned after the Action completes.
{% endhint %}

#### Example (customer identification):

An Action attempts to identify a customer:

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "identify_customer",
  status: "success",
  customerFound: true
};
```

The value of this structure is not the boolean itself. It is the context it provides to the AI Agent. The Agent can now reason:

* Customer identified → Continue customer-specific flow; **OR**
* Customer **not** identified  → Request additional information.

#### Example (business outcome):

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  status: "success",
  result_data: {
    internetBalance: "20GB",
    smsBalance: "2 SMS",
    minutesBalance: "5 Minutes"
  }
};
```

The AI Agent now understands:

* Which Action was executed;
* Whether the execution succeeded;
* And which information became available after execution.

***

### userData

`userData` represents persistent contextual memory. Unlike `functionResult`, which describes the outcome of a specific execution, `userData` stores information that may be useful throughout the conversation.

Information stored in `userData` remains available to future Actions, Code cells, Service cells, and AI Agent reasoning processes.

#### Common examples

```
hiddenContext._eva.api.agentic.userData = {
  customerId: "12345",
  customerType: "Premium",
  activePlan: "Fiber 500"
};
```

Typical examples can include:

* Customer attributes;
* Account information;
* Contract information;
* Subscription information;
* Eligibility information;
* Preferences.

#### userData is not limited to customer information

A common misconception is that `userData` should only contain customer attributes. This is not a system requirement. Any information that should remain available throughout the conversation may be stored in `userData`.

#### Example: Product catalog

Suppose an Action retrieves a list of available products:

```
{
  products: [
    {
      id: "100",
      name: "Fiber 500"
    },
    {
      id: "200",
      name: "Fiber 1000"
    }
  ]
}
```

The returned products are not customer information. However, they may still be useful for future reasoning. In this scenario, the information can be persisted as contextual knowledge.

```
hiddenContext._eva.api.agentic.userData.products = [
  {
    id: "100",
    name: "Fiber 500"
  },
  {
    id: "200",
    name: "Fiber 1000"
  }
];
```

This allows the AI Agent to reference the product catalog later without performing another Action execution.

The same principle can be applied to:

* Service catalogs;
* Available plans;
* Installation information;
* Eligibility rules;
* Business metadata;
* External knowledge relevant to the conversation.

## Simplifying context access

#### Using aliases

The complete context path can become difficult to read when reused across multiple Actions. For instance:

```
hiddenContext._eva.api.agentic.functionRequest.parameters.number
```

For readability and maintainability, developers **may expose simplified aliases.** For instance:

```
hiddenContext.number
```

{% hint style="info" %}
Instead of repeatedly accessing a deeply nested structure, **the same information can be accessed directly.**
{% endhint %}

#### Another practical example

Action collects:

```
number = "21987476822"
```

Stored as:

```
hiddenContext.number = "21987476822";
```

Using an alias, this becomes:

```
hiddenContext.number
```

### Why use aliases?

Aliases help:

* Reduce complexity;
* Improve readability;
* Simplify debugging;
* Improve reuse across Actions;
* Reduce deeply nested references.

## Success scenario

### What happens during a successful Action execution

A successful execution generates **two independent but complementary outcomes:**

* Execution outcome: The Action returns a resolution through `functionResult`;
* Persistent context: Relevant information may be persisted through `userData` or custom context variables for future use.

### Execution lifecycle

#### Step 1: User request

> *I want to check my internet balance.*

#### Step 2: AI Agent selects an Action

The AI Agent determines that the `check_balance` Action should be executed.

#### Step 3: Parameters are collected

All values collected by the Action may remain available for future executions:

```
hiddenContext.number = "21987476822";
```

#### Step 4: functionRequest is created

```
hiddenContext._eva.api.agentic.functionRequest = {
  function: "check_balance",
  parameters: {
    phone_number: hiddenContext.number,
    balance_type: "internet"
  }
};
```

#### Step 5: REST execution

The request is executed.

#### Step 6: functionResult is created

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  status: "success",
  result_data: {
    internetBalance: "20GB"
  }
};
```

#### Step 7: Context enrichment

Additional information may be persisted.

```
hiddenContext._eva.api.agentic.userData.lastBalanceCheck = {
  internetBalance: "20GB"
};
```

#### Step 8: Agent reasoning

Following the cycle, the AI Agent now has access to:

* Action parameters;
* functionResult;
* userData;
* Previously stored context.

The AI Agent uses this information to decide the next conversational step.

## Combining functionResult and userData

The same execution can leverage both structures. For instance:&#x20;

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  status: "success",
  customerType:
    hiddenContext._eva.api.agentic.userData.customerType,
  result_data: {
    internetBalance: "20GB"
  }
};
```

This allows the AI Agent to reason using:

* Execution outcomes;
* Persistent context;
* Previously collected information.

## Error handling

Errors are also Action outcomes. For this reason, errors should be represented through the same execution context structure used for successful executions.

The AI Agent reasons over both outcomes in a consistent way.

#### Example: Business error

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  status: "error",
  detail: "Unavailable Destination"
};
```

#### Example: Validation error

```
hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  status: "error",
  detail: "Invalid or missing function request"
};
```

### Agent reasoning after an error

The purpose of the error is not only to report a failure, but to provide context for the next decision. For instance:

{% stepper %}
{% step %}

### Action executed&#xD;&#x20;

{% endstep %}

{% step %}

### Error returned&#x20;

{% endstep %}

{% step %}

### functionResult updated

{% endstep %}

{% step %}

### &#xD;AI Agent reasons over outcome&#x20;

{% endstep %}

{% step %}

### Recovery strategy selected

{% endstep %}
{% endstepper %}

Depending on the outcome, the AI Agent may:

* Request additional information;
* Retry an Action;
* Suggest an alternative path;
* Escalate to another Agent;
* Inform the user about the issue.

## Final guidelines&#x20;

When designing and building Agentic workflows, consider:

{% tabs %}
{% tab title="functionRequest" %}
Use it when:

* Describing what should be executed;
* Passing parameters to an Action;
* Preparing REST requests.
  {% endtab %}

{% tab title=" functionResult" %}
When to use it?

* When describing what happened;
* When communicating Action outcomes;
* And when informing AI Agent reasoning.
  {% endtab %}

{% tab title="userData " %}
Use it when:&#x20;

* Information must persist;
* Future Actions may need it;
* The AI Agent may reuse it later.
  {% endtab %}

{% tab title=" Aliases" %}
When to use it?<br>

* When values are reused frequently;
* When readability is important;
* When multiple Actions depend on the same information.
  {% endtab %}
  {% endtabs %}

#### Avoid context pollution

Do not persist information that **has no future value.** Store only information that contributes to future:

* Decisions;
* Actions;
* Reasoning.

{% hint style="info" %}
A well-designed context should maximize usefulness while minimizing unnecessary memory.
{% 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs-conversational-ai.syntphony.com/ai-agents/actions/context-variables.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.