Use Metadata Fields Passed from the API

When calling the Platform via the Execute API, include a metadata field in each request to pass custom context. The Platform stores this in the sessionMeta memory store, making it accessible in agent prompts for personalized, context-aware responses.

API Request (metadata field) → sessionMeta memory store → Agent/Supervisor prompts

---

Step 1: Pass Metadata in the API Call

Include a metadata object in the Execute API request body. The following example passes user profile information to the agent:

{
  "sessionIdentity": [
    {
      "type": "sessionReference",
      "value": "s-a302e3c6-xxxx-xxxx-xxxx-a01a5846fae1"
    },
    {
      "type": "userReference",
      "value": "usr_1a2b3c4d5e"
    }
  ],
  "input": [
    {
      "type": "text",
      "content": "Order me a thick-crust, medium-sized pizza with extra cheese"
    }
  ],
  "metadata": {
    "userProfile": {
      "location": "Japan",
      "preferences": {
        "diet": "vegetarian"
      }
    }
  },
  "isAsync": false
}

Learn more about the Execute API →

---

Step 2: How Metadata Appears in Session Memory

The Platform stores the metadata object and session identifiers in sessionMeta using the following schema:

{
  "metadata": { ... },
  "sessionInfo": { ... }
}

For the example above, sessionMeta contains:

{
  "metadata": {
    "userProfile": {
      "location": "Japan",
      "preferences": {
        "diet": "vegetarian"
      }
    }
  },
  "sessionInfo": {
    "sessionReference": "s-a302e3c6-xxxx-xxxx-xxxx-a01a5846fae1",
    "userReference": "usr_1a2b3c4d5e"
  }
}

---

Step 3: Reference Metadata in Prompts

Use the following template syntax to reference metadata fields in agent or orchestrator prompts:

{{memory.sessionMeta.metadata.<field-name>}}

Examples:

Suggest popular pizza ingredients in {{memory.sessionMeta.metadata.userProfile.location}}.

Resolves to: Suggest popular pizza ingredients in Japan.

User diet preference is {{memory.sessionMeta.metadata.userProfile.preferences.diet}}.

Learn more about the SessionMeta Memory Store →

---