> For the complete documentation index, see [llms.txt](https://docs.labs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.labs.ai/agent-configuration/passing-context-information.md).

# Passing Context Information

## Overview

**Context** is external data that you pass from your application into EDDI conversations. It's how you inject real-world information—like user profiles, session data, or business state—into your agent's logic without hard-coding it.

### Why Context Matters

Context enables your agents to:

* **Personalize responses**: Use user names, preferences, account details
* **Make business decisions**: Check user roles, subscription status, account balances
* **Maintain session state**: Pass authentication tokens (marked [secret](#secret-context-values)), session IDs
* **Adapt behavior**: Change agent responses based on time of day, location, language
* **Integrate with your systems**: Bring data from your CRM, database, or services

### Context vs Conversation Memory

| Aspect        | Context                     | Conversation Memory            |
| ------------- | --------------------------- | ------------------------------ |
| **Source**    | Your application (external) | EDDI (internal)                |
| **Direction** | Input to EDDI               | Managed by EDDI                |
| **Lifetime**  | Per request                 | Persistent across conversation |
| **Purpose**   | Inject external data        | Store conversation history     |
| **Usage**     | `{context.userName}`        | `{memory.current.input}`       |

### Context Types

EDDI supports four context types:

1. **`string`**: Simple text values

   ```json
   "userRole": {"type": "string", "value": "premium"}
   ```
2. **`object`**: Structured JSON data

   ```json
   "userInfo": {"type": "object", "value": {"name": "John", "age": 30}}
   ```
3. **`expressions`**: Parsed semantic expressions

   ```json
   "intent": {"type": "expressions", "value": "purchase(product)"}
   ```
4. **`array`**: A list of values

   ```json
   "tags": {"type": "array", "value": ["a", "b"]}
   ```

> An `array` context is readable in output templates and HTTP call bodies, but it can never be matched by a `contextmatcher` — see [Behavior Rules → Limitations](https://docs.labs.ai/agent-configuration/behavior-rules.md#limitations). Send the data as an `object` (and match with `objectKeyPath`) if you need to match into it.

### Secret Context Values

Context is stored with the conversation step it arrives with, and it is echoed in the conversation output. For a value that must never be stored or returned — typically the caller's credential for a downstream API — add `"secret": true`:

```json
"userToken": {"type": "string", "value": "<the caller's token>", "secret": true}
```

A secret value is usable for the turn it arrives with, exactly like any other context: in templates (`{context.userToken}`), HTTP call headers and behavior rules. Its lifetime really is per request:

* It is **never echoed** in the conversation output, not even while the turn is still running.
* When the turn ends — completed, stopped, paused or failed — its stored entry is replaced by `<secret context>`, and every copy a template made of it is replaced too: other data of the step, the conversation output, the conversation properties (so a `longTerm` property never reaches the user memory store), a paused tool-call batch and the turn's audit ledger entries.
* A later turn, or tasks that run after a HITL resume, see `<secret context>`. Send the value again with every request that needs it. An HTTP call that would send the placeholder — in a header, query parameter, body or path — is refused with an error naming where it is, instead of reaching the API as a credential that authenticates nobody.

Use it in an HTTP call **header**:

```json
"headers": { "Authorization": "Bearer {context.userToken}" }
```

Keep it out of anything that leaves EDDI while the turn runs: a prompt sends it to the model provider, a streamed reply reaches the user before the turn ends (the returned and stored reply is scrubbed), and a query parameter or body is written to the server log by the HTTP call task. Values shorter than 8 characters are not searched for inside other text; from 4 characters up they are still replaced wherever a property, datum, list element, map value, audit field, or a value inside stored JSON text (a paused tool call's arguments) **is** the value (a PIN copied into a property) — never a map key. Values under 4 characters, and `true`/`false`, are only removed from their own entry. That exact match applies only to an entry whose whole value is a string: the fields of a secret **object** are searched for from 8 characters, like any value, but never matched exactly — its `"tokenType": "Bearer"` or `"port": 8080` would otherwise blank every equal value of the turn. Send a short credential such as a PIN as its own string entry, not as a field of an object.

`"secret": true` is different from the `secretInput` flag: `secretInput` hides the **message the user typed** (see [Secrets Vault → Secret Input](https://docs.labs.ai/security-and-compliance/secrets-vault.md#secret-input-agent-conversations)), `secret` hides a **context value your application sends**.

### Reserved Context Keys

A few context keys are set by EDDI itself when it drives a conversation on its own behalf, and the engine trusts them to decide what a turn may do:

| Key                      | Set by                                                                                 | What the engine uses it for                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `groupId`                | Group conversations                                                                    | Which group's `group`-visible [user memories](https://docs.labs.ai/architecture-and-concepts/user-memory.md#group-memory) the conversation sees and writes                                                                                                                                                                                                                                                                                                                                                 |
| `groupConversationId`    | Group conversations                                                                    | Which live discussion the member's group tools act on                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `groupDepth`             | Group conversations                                                                    | Nesting depth of the discussion                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `groupTranscript`        | Group conversations                                                                    | The discussion transcript shown to a member — scoped by the phase's `contextScope` like the rendered prompt: nothing under `NONE` or the task scopes, the previous and current phase under `LAST_PHASE`, entries stripped of speaker and target under `ANONYMOUS`, own-targeted feedback under `OWN_FEEDBACK`; `FULL` the whole transcript minus process bookkeeping (abstentions, convergence, facilitation) and the ballots and bids of a phase still running; `SYNTHESIS` and `RETRO` phases everything |
| `dynamicAgentConfig`     | Group conversations                                                                    | The group's [dynamic-agent policy](https://docs.labs.ai/conversations-and-orchestration/group-conversations.md) for the turn                                                                                                                                                                                                                                                                                                                                                                               |
| `dynamicCreatedAgentIds` | Group conversations                                                                    | The agents the discussion has created (and may tear down)                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `delegationDepth`        | `converse_with_agent`                                                                  | How many delegation hops led to this conversation                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `selfContinuation`       | [Self-continuation](https://docs.labs.ai/conversations-and-orchestration/long-jobs.md) | Marks a turn the agent started itself with `CONTINUE_CONVERSATION`, with its `number` and `max`                                                                                                                                                                                                                                                                                                                                                                                                            |

A client cannot set them. EDDI drops these keys from the context of every externally supplied request — `POST /agents/{agentId}/start`, `POST /agents/{conversationId}` (plain and streaming), managed conversations, and a trigger's initial context — before the conversation sees it. The request still succeeds; only the reserved entries are removed, so `{context.groupId}` in a template renders empty for a client-started turn. Group members, delegated sub-agent conversations and schedules still receive the values EDDI sets. Matching is case-sensitive and anchored at the start of the name: `screenGroupId` or `GroupId` are ordinary keys, but a key that **starts with** a reserved name — `groupIdSuffix`, `delegationDepthMax`, `dynamicAgentConfigV2` — is dropped as well, so pick context key names that do not begin with a reserved one. (The engine reads its own keys by exact name; dropping the extensions keeps a reader that ever matched by prefix from mistaking a client's key for the engine's.)

Once a conversation has been governed by a group's `dynamicAgentConfig`, later turns in it keep that policy even when they carry no group context — for example a turn the conversation's owner sends into a member conversation directly.

A deployment whose every caller is trusted can let clients set specific reserved keys again — EDDI logs a warning at startup when it does:

```properties
eddi.conversation.client-context.permitted-reserved-keys=groupId
```

Only the keys in the table can be listed; anything else is ignored. Listing a key also permits the keys that start with it (`groupIdLabel` once `groupId` is listed). The default permits none.

### How Context is Used

Once passed to EDDI, context can be:

* **Matched in Behavior Rules**: Conditions check context values
* **Used in Output Templates**: `{context.userName}`
* **Included in HTTP Call Bodies**: Pass to external APIs
* **Stored as Properties**: Save to conversation memory

### Example Flow

```
Your App → POST /agents/conv456
{
  "input": "What's my account balance?",
  "context": {
    "userId": {"type": "string", "value": "user-789"},
    "accountType": {"type": "string", "value": "premium"}
  }
}

→ EDDI Behavior Rule checks context:
   IF context.accountType = "premium" THEN httpcall(get-balance)

→ HTTP Call uses context:
   GET /api/accounts/{context.userId}/balance

→ Output Template uses context:
   "Hello! Your premium account balance is {memory.current.httpCalls.balance.amount}"

→ Response to Your App:
   "Hello! Your premium account balance is $1,250.00"
```

## Sending Context to Conversations

In this section we will explain how **EDDI** handles the context of a conversation and which data can be passed within the scope of a conversation.

In order to talk to **EDDI** with context, send a **`POST`** request to `/agents/`**`{conversationId}`** (same way as interacting in a normal conversation in EDDI), but this time provide context parameters:

### Send message in a conversation with an Agent REST API Endpoint

| Element                          | Tags                                                                                                                                                                                                                                                                                            |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP Method                      | `POST`                                                                                                                                                                                                                                                                                          |
| API endpoint                     | `/agents/{conversationId}`                                                                                                                                                                                                                                                                      |
| {conversationId}                 | (`Path` **parameter**): `String Id` of the **conversation** that you wish to **send** the message to.                                                                                                                                                                                           |
| returnDetailed (Optional)        | (`Query` **parameter**):`Boolean` - Default : `false` Will return all sub results of the entire `conversation steps`, otherwise only public ones such as `input, action, output & quickReplies`.                                                                                                |
| returnCurrentStepOnly (Optional) | (`Query` **parameter**):`Boolean` - Default : `true` Will return only the latest `conversationStep` that has just been processed, otherwise returns all `conversationSteps` since the beginning of this `conversation`.                                                                         |
| Request Body                     | a `JSON` object sent in the request body consists of the usual input text (message to the agent) only this time we are going to provide `context` information through a `key value` data structure ; the Context value must have one of the following : `string, object, expressions or array.` |
|                                  |                                                                                                                                                                                                                                                                                                 |

## Example

Here is an example of a `JSON` object of the input data:

```javascript
{
  "input": "",
  "context": {
    "onboardingOfUser": {
      "type": "string",
      "value": "true"
    },
    "userInfo": {
      "type": "object",
      "value": {
        "username": "Barbara"
      }
    }
  }
}
```

> You can also test context parameters in the **EDDI Manager** chat panel at `http://localhost:7070/manage`.
