Skip to main content
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 →