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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

Tip: If the flow has multiple REST Connector calls, save each response in a different variable to avoid overwriting hiddenContext.RestConnectorResponse.

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.

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:

1

Action: check_balance

2

Webhook: client API checks the balance

3

Webhook response returns updated hiddenContext

4

AI Agent receives functionResult and continues

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:

1

Action: check_balance

2

REST Connector: executes the API request

3

Output: writes functionResult and userData

4

AI Agent receives the processed result

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:

1

Action: check_balance

2

Code cell: creates or updates the context directly

3

AI Agent receives functionResult and userData

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"
};