> 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/manipulating-context-variables.md).

# Manipulating context variables

## Overview

Context variables help AI Agents keep execution data, user information, and service results available across the conversation. In agentic workflows, variables are especially important because an Action may collect parameters, call a service, receive a result, and then continue the conversation with the updated context.

In the workflows covered in this section, an Action is not complete until the result is applied to the context through one of these options:

* a **Webhook** response;
* a **REST Connector** output;
* a **Code cell**.

Use this section to decide where to apply the context update and how to write values to `hiddenContext._eva.api.agentic.functionResult` and `hiddenContext._eva.api.agentic.userData`.

For complete Code cell syntax and execution details, see [code cell.](/build-dialogs/dialog-cells/code.md) 

## Before you begin

Before manipulating Context Variables, make sure you have:

* An Action that captures or receives the data needed for the operation;
* The target context variable you want to update;
* One application point after the Action: Webhook, REST Connector, or Code cell;
* For Webhook or REST Connector flows, the service URL and the expected request and response contract.

Use `hiddenContext` for sensitive or internal data. Hidden context is the most secure context and can be edited by Service, REST, Code, Rule, Prompt, and Transactional Answer cells.

## Key concepts

#### Action

An Action defines a task the AI Agent must perform and the data it must collect to execute that task. When an Action captures data, the information is stored in the conversation context and can be accessed through agentic variables.

#### `functionRequest`

`hiddenContext._eva.api.agentic.functionRequest` contains the parameters passed to a REST call. In a typical Action flow, this object represents what the Action collected and what the service needs to execute.

#### `functionResult`

`hiddenContext._eva.api.agentic.functionResult` stores the result of a request to an endpoint in the context. Use it when the AI Agent or Supervisor must understand what happened and decide what to do next.

Use `functionResult` when:

* The Action result affects routing;
* The Supervisor must reason about success or failure;
* Another AI Agent depends on the execution outcome;
* The flow must preserve execution continuity.

#### `userData`

`hiddenContext._eva.api.agentic.userData` passes user or customer information to the AI Agent, such as an ID number, email, phone number, or other relevant information. In the documented examples, `userData` is structured as an object with key-value pairs.

Use `userData` when:

* The AI Agent must know information about the user;
* The information enriches the conversation context;
* No routing or execution decision is required.

### Choosing between `functionResult` and `userData` 

| Use case                                                                                          | Recommended variable | Why                                                                                                      |
| ------------------------------------------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------- |
| The AI Agent must act based on the execution result, or the Supervisor must decide the next step. | `functionResult`     | The value represents an execution outcome that may affect reasoning, routing, recovery, or continuation. |
| The AI Agent only needs contextual information about the user.                                    | `userData`           | The value enriches the conversation but does not represent an execution result.                          |
| The flow stores customer attributes for future use.                                               | `userData`           | Customer attributes are contextual information unless they directly control an execution decision.       |
| The service failed and the AI Agent must recover or explain the next step.                        | `functionResult`     | A failure is part of the execution outcome and must be available for Agent or Supervisor reasoning.      |

{% hint style="info" %}
**Important:** If the AI Agent must act based on the information, use `functionResult`. If the AI Agent only needs to know the information, use `userData`. Also, if you want more information about Context Variables , [check here as well. ](/ai-agents/actions/context-variables.md)
{% endhint %}

### How it works

A common Action flow works as follows:

1. The Agent identifies the user request and triggers an Action;
2. The Action captures the required parameters;
3. Syntphony CAI stores the Action parameters in `hiddenContext._eva.api.agentic.functionRequest`;
4. When the Action or service execution produces a result, Syntphony CAI saves the result in `hiddenContext._eva.api.agentic.functionResult`;
5. A Webhook response, REST Connector output, or Code cell can access and manipulate `functionResult` when the flow needs to transform, enrich, validate, map, or override the saved value;
6. The AI Agent or Supervisor uses the final context to continue the conversation.

{% hint style="info" %}
In documented success scenarios, Syntphony CAI inserts the function request into `hiddenContext._eva.api.agentic.functionRequest`. When a client API must be called, a Code cell can format the request and a REST Connector can execute it. The execution result is saved in `hiddenContext._eva.api.agentic.functionResult` by the system. Webhook responses, Rest Connector output processing, and Code cells can then access or manipulate that value before the Agent or Supervisor processes the updated context.
{% endhint %}

## Application methods

| Method         | Where the logic runs                                                       | Use it when                                                                          |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| Webhook        | In the client service.                                                     | The external service owns the business logic and can return the updated context.     |
| REST Connector | In Syntphony CAI, through a configured REST request and Output processing. | You need to call an API from the flow and process the response before saving it.     |
| Code cell      | In Syntphony CAI, through JavaScript logic.                                | You need to format, validate, or create context values without an external API call. |

{% hint style="info" %}
**Developer note:** `functionResult` is system-managed context data. Webhook, Rest Connector output, and Code cell should be documented as manipulation points, not as the only mechanism that stores the value.
{% endhint %}

#### What happens if the context is not applied:

If the Action result is not written back to context:

* AI Agent may not know whether the execution succeeded or failed;
* The Supervisor may not be able to reason over the result;
* Routing decisions may become unstable;
* The flow may continue without the data it needs.

### Manipulating context with a Webhook

A Webhook is a service contract. Syntphony CAI calls an external service, sends the agreed information, and expects the service to return the information required by the flow.

Use a Webhook when the client API should handle the context manipulation. In this scenario, the service receives the current context, updates the required values, and returns the updated context to Syntphony CAI.

Webhook implementation includes naming the cell, inserting the URL, defining options for each API response, setting the answer path, and deciding the next flow steps based on success or failure.

#### How to use a Webhook to update context:

1. Add the Webhook after the Action that requires the context update;
2. Configure the Webhook URL and optional headers;
3. Define the response options that the flow must handle;
4. In the external service, read the received context;
5. Update `hiddenContext._eva.api.agentic.functionResult`, `hiddenContext._eva.api.agentic.userData`, or both;
6. Return the updated context according to the Webhook contract;
7. Connect each Webhook option to the next flow step.

{% hint style="info" %}
In Webhook flows, the context update is implemented in the client API. The documentation provided does not define the exact Webhook response envelope. Use the response structure required by the Webhook contract for the project.
{% endhint %}

#### Example:

The following example is a conceptual response body. Adapt the envelope to the Webhook contract used by the project.

```
{
  "hiddenContext": {
    "_eva": {
      "api": {
        "agentic": {
          "functionResult": {
            "function": "check_balance",
            "result": "success",
            "result_data": {
              "internetBalance": "20Mb",
              "smsBalance": "2 SMS",
              "minutesBalance": "5 Minutes"
            }
          },
          "userData": {
            "phone_number": "21987476822",
            "customer_segment": "premium"
          }
        }
      }
    }
  }
}
```

After Syntphony CAI receives the updated context, the AI Agent can use the function result as execution feedback and the user data as contextual information.

### Manipulating context with a REST Connector

The REST Connector executes the configured REST request, retrieves the result, and stores the response in `hiddenContext.RestConnectorResponse` by default. The Output field can process the response before saving it to another variable.

Use a REST Connector when the flow needs to call an API and then transform the response into `functionResult`, `userData`, or another context variable.

The REST Connector Output field works similarly to a Code cell field and can perform operations to expose or pass processed results downstream. The web request result is available in Hidden Context under `RestConnectorResponse`.

#### How to use a REST Connector to update context:

1. Add the REST Connector after the Action;
2. Configure the URL, headers, request type, content type, authentication, and body as required;
3. Use the Action parameters from `hiddenContext._eva.api.agentic.functionRequest` when building the request;
4. In the Output field, read `hiddenContext.RestConnectorResponse`;
5. Parse or transform the response;
6. Save the processed result into `hiddenContext._eva.api.agentic.functionResult`, `hiddenContext._eva.api.agentic.userData`, or both;
7. Connect the success option to the next flow step;
8. Configure the service error option.

{% hint style="info" %}
**Tip:** If the flow has multiple REST Connector calls, save each response in a different variable to avoid overwriting `hiddenContext.RestConnectorResponse`.
{% endhint %}

#### Example:

```
const response = JSON.parse(hiddenContext.RestConnectorResponse);

hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  result: "success",
  result_data: {
    internetBalance: response.internetBalance,
    smsBalance: response.smsBalance,
    minutesBalance: response.minutesBalance
  }
};

hiddenContext._eva.api.agentic.userData = {
  phone_number: response.phoneNumber,
  customer_segment: response.customerSegment
};
```

#### Handling REST connector errors

External services may fail. When this happens, Syntphony CAI automatically generates a service error option, which can be handled like any other service option.

Use the error path to give the AI Agent enough information to continue. When the Agent or Supervisor must reason over the failure, add a Code cell in the error option and write an error result to `functionResult`.

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

### Manipulating context with a Code cell

A Code cell can read, create, and modify variables in all contexts, and it can parse existing values or save data into new fields.

Use a Code cell when the context update does not require an external API call, or when you need to format, validate, or assemble values before the AI Agent continues.

Keep this section focused on the context update. For complete Code cell behavior, syntax, supported variables, and execution limitations, see [code cell.](/build-dialogs/dialog-cells/code.md) 

#### How to use a Code cell to update context:

1. Add the Code cell after the Action or after the service option that needs to update context;
2. Read the values already available in context;
3. Create or update `hiddenContext._eva.api.agentic.functionResult`, `hiddenContext._eva.api.agentic.userData`, or both;
4. Connect the Code cell to the next flow step.

#### Example:

```
hiddenContext._eva.api.agentic.userData = {
  phone_number: "21987476822",
  customer_segment: "premium"
};

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

## Takeaways

The following example shows the same Action outcome applied with **Webhook, REST Connector, and Code cell.**

### Scenario

A user asks:

> I want to check my internet balance.

The AI Agent triggers the `check_balance` Action. The Action collects the required parameters and the flow must return the balance to the Agent.

#### Option 1:  Webhook

AI Agent cycle: 

{% stepper %}
{% step %}

### Action: check\_balance

{% endstep %}

{% step %}

###  Webhook: client API checks the balance

{% endstep %}

{% step %}

### Webhook response returns updated hiddenContext

{% endstep %}

{% step %}

### AI Agent receives functionResult and continues

{% endstep %}
{% endstepper %}

The client API updates the context and returns the updated values to Syntphony CAI:

```
{
  "functionResult": {
    "function": "check_balance",
    "result": "success",
    "result_data": {
      "internetBalance": "20Mb",
      "smsBalance": "2 SMS",
      "minutesBalance": "5 Minutes"
    }
  }
}
```

#### Option 2: REST Connector

AI Agent cycle: 

{% stepper %}
{% step %}

### Action: check\_balance

{% endstep %}

{% step %}

### REST Connector: executes the API request

{% endstep %}

{% step %}

### Output: writes functionResult and userData

{% endstep %}

{% step %}

###  AI Agent receives the processed result

{% endstep %}
{% endstepper %}

```
const response = JSON.parse(hiddenContext.RestConnectorResponse);

hiddenContext._eva.api.agentic.functionResult = {
  function: "check_balance",
  result: "success",
  result_data: response
};
```

#### Option 3: Code cell

AI Agent cycle: 

{% stepper %}
{% step %}

### Action: check\_balance

{% endstep %}

{% step %}

### Code cell: creates or updates the context directly

{% endstep %}

{% step %}

### AI Agent receives functionResult and userData

{% endstep %}
{% endstepper %}

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

hiddenContext._eva.api.agentic.userData = {
  phone_number: "21987476822"
};
```


---

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