> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindset.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Data channels overview
> Four data channels and one programmatic trigger for connecting a host page to a Mindset AI agent. Each has a different direction, destination, and purpose.
## Micro-composability: making the agent native to your application
The Mindset AI platform gives you three ways to engage at the macro level: use the full SDK, run the headless graph with your own UI, or build entirely on the Platform API. Once you choose the SDK path, a second question follows: how does your application actually talk to the agent? The answer is five independent integration points we call micro-composability.
* **`Agent Session Parameters`** establish identity and authorization at session creation.
* **`Situational Awareness`** feeds the agent live page context so it knows what the user is looking at.
* **`Page Tools`** let the agent call JavaScript functions on the host page, turning conversation into action.
* **`Pass-through Parameters`** inject data directly into tool calls without the LLM wasting tokens copying it.
* **`sendMessage`** lets the host page trigger the agent programmatically, without the user typing a word. Each of these is a single JavaScript call; each works independently and each becomes more powerful when combined with the others.
None of it requires backend work, Mindset AI-side configuration, or changes to the agent's graph. A developer wiring the agent into their HR platform sets Situational Awareness so the agent knows which employee profile the user is viewing, registers a Page Tool so the agent can update that profile, attaches Pass-through Parameters so the tool receives the full profile JSON without the LLM copying it, and calls `sendMessage` to kick off the interaction when the user clicks a button. A handful of lines of JavaScript, and the agent is a native participant in the application's workflow rather than a chat sidebar disconnected from it.
That is the difference between an embedded agent and an integrated one.
***
> **TL;DR:** there are four data channels and one programmatic trigger for connecting a host page to a Mindset AI agent. Each has a different direction, destination, and purpose. Together they let you make the agent native to your application without backend work or platform-side configuration.
### Per-channel guides
Identity, routing, and MCP server authorization.
Give the agent live context about the page.
Inject data directly into tool calls, bypassing the LLM.
Let the agent call browser-local handler functions.
Trigger the agent programmatically from the host page.
***
## The four channels
| | Agent Session Parameters | Situational Awareness | Pass-through Parameters | Page Tools |
| ----------------------- | --------------------------------------------------------- | ---------------------------------------------------------- | --------------------------------------------------------------- | ----------------------------------------------------------- |
| **Direction** | Host page to platform | Host page to agent | Host page to tools | Agent to host page |
| **When set** | Once, at session creation | At init and/or dynamically via element method | At init and/or dynamically via element method | Dynamically via element method (after the element is ready) |
| **Destination** | MCP server HTTP headers | Agent's system prompt | Tool call parameters (injected before execution) | Handler functions in the browser |
| **Agent sees it?** | No, by design | Yes, that's the point | No, that's the point | Yes (the agent decides when to call a tool) |
| **MCP servers see it?** | Yes, as headers on every request | No | Yes, as injected parameter values on the tool call | No (page tools execute locally, not on MCP servers) |
| **Purpose** | Identity and routing | Give the agent contextual awareness to reason with | Bypass the agent for large payloads it would only copy verbatim | Let the agent take actions on the host page |
| **Lifecycle** | Session-scoped (persists for the duration of the session) | Transient per message (read fresh from store on each send) | Transient per message | Available until replaced or cleared |
***
## 1. Agent Session Parameters
### What they are
Data provided once when the client creates an agent session via the [AgentSessions API](https://docs.mindset.ai/deploy/api/agentsessions-api), before any conversation happens. These parameters configure the session and establish identity.
### What gets sent
| API Field | Purpose |
| ----------------------- | ------------------------------------------------------------- |
| `agentUid` | Which agent to use |
| `externalUserId` | Who the user is in your system |
| `tags` (max 10) | Arbitrary strings for filtering, segmentation, access control |
| `contextUids` (max 30) | Which knowledge bases / RAG sources the agent can access |
| `mcpserverUids` (max 5) | Which MCP servers the agent can call |
### Where it goes
The identity and classification fields are forwarded to every MCP server as HTTP headers:
| Header | Source | Purpose |
| ---------------- | ----------------- | ------------------------------------------------------------------------------------------------------ |
| `x-user-id` | `externalUserId` | Identifies the end user so the MCP server can scope data access and apply permissions |
| `x-app-uid` | Platform-provided | Identifies the application |
| `x-session-tags` | `tags` | JSON array of the session tags, for filtering, segmentation, or access control logic in the MCP server |
| `x-human-uid` | Platform-provided | Internal Mindset AI identifier, optional, for logging only |
The structural fields (`contextUids`, `mcpserverUids`) configure what the agent has access to for the session. They are not forwarded anywhere; they define scope.
### What it is not
Agent session parameters are never made available to the agent's reasoning and the agent has no mechanism to see them. This is by design: the agent does not need to know the user's external ID or session tags to hold a conversation. These are infrastructure-level concerns for authentication, authorization, and routing.
### Security boundary
The `x-user-id` header identifies the **current user**, the person making the request. MCP servers must use this header (not a tool parameter) to identify who is acting. Tool parameters should only contain user identifiers when the tool is an admin operation acting on a **target** user, and even then the MCP server must verify that the `x-user-id` has admin permissions before proceeding.
For the full specification, see [Agent Session Parameters](./agent-session-parameters.mdx).
***
## 2. Situational Awareness
### What it is
Dynamic, contextual information that the host page provides to give the agent awareness of the user's current situation. Unlike agent session parameters (which are about identity), Situational Awareness reflects what the user is actually doing right now.
### How to set it
**At init time** via the HTML attribute:
```html theme={null}
```
**Dynamically** via the element method (updates take effect on the next message, no reload needed):
```javascript theme={null}
const agent = document.querySelector('mindset-agent');
agent.setSituationalAwareness({
page: 'Employee Performance Dashboard',
active_tab: 'Quarterly Reviews',
user_role: 'Finance Manager',
});
```
Both methods are complementary. Set initial context via the HTML attribute, then update it via the element method as the user navigates. If the element method is never called, the init-time values persist for the entire session.
### Where it goes
The key-value pairs are injected into the agent's system prompt as a structured block. The agent reads them, reasons about them, and uses them to inform its responses. The platform passes them through verbatim with no per-key interpretation.
### Design properties
* Transient per message. Read fresh from the store on each message send. Not persisted in conversation history. No stale context accumulation.
* Size-aware. 10,000 character default limit. For dedicated agents where the SA context is the primary input (for example, processing a transcript or document), opt into the 20,000 character ceiling via `extendedSituationalAwareness: true` in `mindset.init()`. The LLM reads the entire SA payload on every message, so larger payloads increase token cost.
* Generic pass-through. The platform does not interpret keys. The meaning is a contract between the host page and the agent.
For the full specification, see [Situational Awareness](./situational-awareness.mdx).
***
## 3. Pass-through Parameters
### The problem they solve
Sometimes the host page already has data that a tool needs as input. For example, an HR platform might display a detailed employee profile on screen. If the user asks the agent to update that employee's record, the tool needs the employee's internal identifier or a large structured payload. The host page already has this data because it is rendering the page.
Without Pass-through Parameters, the data would need to flow through the agent: present in the conversation context, then copied token by token into the tool call. This is expensive (output tokens), slow (generating thousands of copied tokens), error-prone (LLMs are not good at verbatim copying of structured data), and pointless (the agent is not reasoning about the data, just copying it).
### How to set them
**At init time** via the HTML attribute:
```html theme={null}
```
**Dynamically** via the element method:
```javascript theme={null}
const agent = document.querySelector('mindset-agent');
agent.setPassthroughParams({
'update_employee.employee_id': 'EMP-4821',
'submit_report.report_body': reportContent,
});
```
Keys use the format `tool_name.parameter_name` for targeted injection, or just `parameter_name` for wildcard injection into any tool that declares that parameter.
### How it works
The platform does two things:
1. **Strips the parameter from the tool definition.** Before presenting tools to the agent, any parameter that has a pass-through value is removed from the tool's schema. The agent sees a simplified version of the tool where this parameter does not exist.
2. **Re-injects the parameter before execution.** When the agent calls the tool, the platform adds the pass-through value back into the tool call before dispatching it. The tool receives the complete call as if the agent had generated all parameters.
### Design properties
* Transient per message. Same lifecycle as Situational Awareness.
* Agent never sees it. The values are not added to the system prompt, conversation history, or any part of the agent's context.
* Deterministic. The value that reaches the tool is exactly what the host page sent, byte for byte.
* Higher size ceiling. The data never enters the agent's context window, so the constraint is transport and tool-side, not token budget.
* Works on both MCP tools and page tools. Same mechanic for both. The SDK strips the parameter from the schema the agent sees, then injects the value when the tool is invoked.
### Complementary to Situational Awareness
Both channels can work together on the same message:
* Situational Awareness sends `page: "Employee Profile"` and `employeeName: "Sarah Chen"` so the agent knows what the user is looking at and can respond conversationally.
* Pass-through Parameters sends the full employee profile JSON that the update tool needs, so the agent doesn't have to copy it.
The agent reasons with the summary. The tool receives the data. Each channel does what it's good at.
For the full specification, see [Pass-through Parameters](./passthrough-parameters.mdx).
***
## 4. Page Tools
### What they are
Page Tools let the agent take actions on the host page. While Situational Awareness flows context *inward* (host page tells the agent about the world), Page Tools flow actions *outward* (agent tells the host page to do something).
The host page registers JavaScript handler functions as tools. The agent can call them when appropriate. The handler runs in the browser with full access to the application's DOM, state, and APIs. The agent decides *when* to act; the host page's handler decides *how*.
### How to register them
```javascript theme={null}
const agent = document.querySelector('mindset-agent');
agent.setPageTools([{
name: 'add_to_cart',
description: 'Add the product the user is currently viewing to the shopping cart.',
runningDescription: 'Adding to cart...',
completedDescription: 'Added to cart',
parameters: {
type: 'object',
properties: {
quantity: { type: 'number', description: 'Number to add (default 1)' },
},
},
handler: async (args) => {
await myApp.cart.addItem(currentProductId, args.quantity ?? 1);
const cart = await myApp.cart.getState();
return { success: true, cartTotal: cart.formattedTotal };
},
}]);
```
Call `setPageTools()` after the element fires `mindset:agent-idle` for the first time (see [§ When the element is ready to call](./methods.mdx#when-the-element-is-ready-to-call)). Re-call it whenever the available tools change as the user navigates. `setPageTools()` replaces the entire tool list, so just call it again with the new set.
### How it works
When the agent decides to use a Page Tool, your handler function is called directly in the browser. There is no network round-trip and no server involved. Your function runs, returns a result, and the agent uses that result to formulate its response to the user.
### Design properties
* You control the capabilities. The agent can only call tools you have registered. No registration, no capability. Different pages can offer different tools. Admin users can get tools that regular users don't.
* Local execution. Handlers run in the browser, in the user's authenticated session. They have access to your DOM, your client-side state, your APIs. If your frontend can do it, a Page Tool can do it.
* Dynamically updatable. Call `setPageTools()` as the application state changes. The agent's available actions evolve with the page.
* Complementary to MCP servers. MCP servers connect the agent to backend services behind your infrastructure. Page Tools connect the agent to the application in front of your user.
For the full specification, see [Page Tools](./page-tools.mdx).
***
## Programmatic trigger: `sendMessage`
The four channels above handle data flow. One additional method completes the picture for host-page integration: `agent.sendMessage(text, options?)` sends a message to the agent programmatically, as if the user had typed it.
This is not a fifth data channel. It is a way for the host page to trigger the agent to act on context that has already been set via the channels above. For example: Situational Awareness provides a consultation transcript, Page Tools register form fields, and `sendMessage` tells the agent to start populating the form, all without the user typing a word.
```javascript theme={null}
const agent = document.querySelector('mindset-agent');
// Visible: appears in the chat UI like a user-typed message
agent.sendMessage('Analyse the transcript and populate the form.');
// Silent: agent responds, but the trigger is hidden from the chat UI
agent.sendMessage('Check for pending tasks.', { silent: true });
```
`sendMessage` goes through the same graph pipeline as any user message: guard classification, directive filtering, tool scoping. No special bypass. The `silent` option uses the same `PSEUDO_HUMAN` input type as icebreakers, hiding the message from the chat UI while still triggering a full agent response.
The host page can observe the agent's state via DOM events on the element (`agent.addEventListener('mindset:agent-busy', fn)` / `'mindset:agent-idle'`), or call `agent.isAgentBusy()` for a synchronous check. `sendMessage` throws if the agent is currently busy, enforcing one message at a time (the same constraint the chat UI applies).
For the full specification, see [`agent.sendMessage`](./methods.mdx#agent-sendmessage-text-options).
***
## How the four channels relate
The four channels form a complete picture of how data flows between the host page and the agent:
```
Host Page
│
├── Session Creation ──→ Agent Session Parameters
│ │
│ ├── x-user-id, x-session-tags ──→ MCP Server Headers
│ └── contextUids, mcpserverUids ──→ Agent Capability Scope
│
├── Per Message ──→ Situational Awareness
│ └──→ Agent's System Prompt
│
├── Per Message ──→ Pass-through Parameters
│ │
│ ├── Strip from tool schema ──→ Agent sees simplified tool
│ └── Re-inject before dispatch ──→ Tool receives complete call
│
└── Per Message ──→ Page Tools
└──→ Agent calls handler ──→ Handler runs in browser ──→ Result back to agent
```
Each channel has a clear destination and none of them leak into another's domain:
* The agent never sees Agent Session Parameters or Pass-through Parameter values.
* MCP servers never receive Situational Awareness or Page Tool calls.
* Agent Session Parameters never enter the agent's context.
* Pass-through Parameters never appear in conversation history.
* Page Tools execute locally, never on the server.
The boundaries are clean because the purposes are distinct: identity, context, data delivery, and action are different concerns that belong in different places.
***
## Related
Identity headers and the AgentSessions API.
Per-message context for the LLM.
Direct data injection into tool calls.
Browser-local tool handlers the agent can call.
Full element method surface, including sendMessage.
Page-level configuration via mindset.init().