Guardrails and allowed actions

Guardrails are access limits your server attaches to a session. They decide which memories a task may see and, for Explore Product, which browser actions it may declare. Set them on POST /v1/sessions with your secret key. The React SDK only receives a clientToken and cannot expand the rails.

How they work

• Guardrails are minted on the session and bound to the client token.
• guardRails.memoryTypes is required for Explore Memories, Memory Chat, and Memory Search sessions.
• Explore Product sessions use allowedActions as the usual control; guardRails is only needed when the task will declare semantic searches.
• Each memory type entry uses exactly one scope: memoryIds, match, or includeAll. Combining them on the same entry is rejected by the API.

For the full request fields, see Create explore memories session and Create explore product session.

Metadata overrides

Each memory type entry can include a metadata array that overrides the stored meta-key schema for that session only:

• visible: whether the agent can see that key.
• description: the description the agent gets for that key, overriding the stored one.

Each entry needs a key plus at least one of visible or description.

Explore Memories

guardRails.memoryTypes is required. The common pattern scopes by metadata with match (for example to a single tenant) and overrides key visibility and descriptions:

createAgentTask: {
    taskType: 'EXPLORE_MEMORIES',
    guardRails: {
        memoryTypes: [
            {
                memoryTypeId: 'mty_...',
                match: { organization_id: 'org_...' },
                metadata: [
                    {
                        key: 'renewal_date',
                        visible: true,
                        description: 'ISO-8601 date the contract auto-renews',
                    },
                    {
                        key: 'internal_notes',
                        visible: false,
                    },
                ],
            },
        ],
    },
}

When the user has already picked specific memories, scope by explicit IDs instead. Use memoryTypeId + memoryIds only. Never combine memoryIds with match on the same entry:

createAgentTask: {
    taskType: 'EXPLORE_MEMORIES',
    guardRails: {
        memoryTypes: [
            {
                memoryTypeId: 'mty_...',
                memoryIds: ['mem_...', 'mem_...'],
                metadata: [
                    {
                        key: 'renewal_date',
                        visible: true,
                        description: 'ISO-8601 date the contract auto-renews',
                    },
                ],
            },
        ],
    },
}

Explore Product

Explore Product sessions have two server-side controls:

1. allowedActions: an allowlist of action and component names the browser may declare. Absent means unrestricted. If the client declares a name that is not on the list, task creation fails.
2. guardRails.memoryTypes: optional, but required if the client will declare semantic searches. Those searches may only target memory types on the rails. When rails are present, include metadata overrides the same way.

createAgentTask: {
    taskType: 'EXPLORE_PRODUCT',
    allowedActions: ['setTheme', 'applyFilter'],
    guardRails: {
        memoryTypes: [
            {
                memoryTypeId: 'mty_...',
                match: { tenant_id: 'ten_...' },
                metadata: [
                    {
                        key: 'sku',
                        visible: true,
                        description: 'Store SKU used to look up the product',
                    },
                    {
                        key: 'cost_price',
                        visible: false,
                    },
                ],
            },
        ],
    },
}

Many product copilots operate the application without any memory access. Those sessions need only allowedActions and no guardRails at all.

Other task types

Memory Chat and Memory Search sessions use the same guardRails.memoryTypes shape. See Memory chat completion for a full server route example.