diff --git a/build/agents/extend-your-agent/user-chat-settings.mdx b/build/agents/extend-your-agent/user-chat-settings.mdx
new file mode 100644
index 00000000..ce658e91
--- /dev/null
+++ b/build/agents/extend-your-agent/user-chat-settings.mdx
@@ -0,0 +1,219 @@
+---
+title: "UserChatSettings"
+sidebarTitle: "UserChatSettings"
+description: "Control which mounts and agent skills are active in a chat session using the Node.js SDK."
+---
+
+`UserChatSettings` is a TypeScript type in the Relevance AI Node.js SDK that lets you configure the chat interface when starting or managing an agent conversation programmatically. It controls which **mounts** (built-in capabilities like file upload or code execution) and **agent skills** (other agents callable from within the conversation) are enabled or disabled.
+
+## Concepts
+
+**Mounts** are named capabilities that can be attached to a chat session. Each mount maps to a feature the agent can use during a conversation — for example, accessing files, running code, or calling external services. Disabling a mount prevents the agent from using that capability in a given session.
+
+**Agent skills** are agents that have been configured as callable skills from within another agent's conversation. Each skill is identified by its agent ID. You can control whether a given skill is available to the agent in a specific session.
+
+## API structure
+
+`UserChatSettings` takes an object where keys are mount names or agent IDs. Each value is an object with a single boolean field.
+
+```typescript
+type UserChatSettings = {
+ // Mount configuration: mountName -> { is_enabled: boolean }
+ [mountName: string]: { is_enabled: boolean };
+} | {
+ // Agent skill configuration: agentId -> { is_skill: boolean }
+ [agentId: string]: { is_skill: boolean };
+}
+```
+
+### Mount format
+
+```typescript
+{
+ [mountName: string]: {
+ is_enabled: boolean; // true = mount is active, false = mount is disabled
+ }
+}
+```
+
+### Agent skill format
+
+```typescript
+{
+ [agentId: string]: {
+ is_skill: boolean; // true = agent is available as a skill, false = agent is not available
+ }
+}
+```
+
+## Usage examples
+
+### Enable and disable mounts
+
+```typescript
+import { RelevanceAI } from "@relevanceai/chain";
+
+const client = new RelevanceAI({
+ apiKey: process.env.RELEVANCE_API_KEY,
+ projectId: process.env.RELEVANCE_PROJECT_ID,
+ region: process.env.RELEVANCE_REGION,
+});
+
+// Enable a specific mount, disable another
+const chatSettings = {
+ file_upload: { is_enabled: true },
+ code_execution: { is_enabled: false },
+};
+
+await client.agents.trigger({
+ agentId: "your-agent-id",
+ message: { role: "user", content: "Hello" },
+ userChatSettings: chatSettings,
+});
+```
+
+### Control agent skills
+
+```typescript
+import { RelevanceAI } from "@relevanceai/chain";
+
+const client = new RelevanceAI({
+ apiKey: process.env.RELEVANCE_API_KEY,
+ projectId: process.env.RELEVANCE_PROJECT_ID,
+ region: process.env.RELEVANCE_REGION,
+});
+
+// Make a specific agent available as a skill, disable another
+const chatSettings = {
+ "agent-id-for-research": { is_skill: true },
+ "agent-id-for-outreach": { is_skill: false },
+};
+
+await client.agents.trigger({
+ agentId: "your-agent-id",
+ message: { role: "user", content: "Start the research workflow" },
+ userChatSettings: chatSettings,
+});
+```
+
+### Combine mounts and agent skills
+
+```typescript
+const chatSettings = {
+ // Mounts
+ file_upload: { is_enabled: true },
+ web_search: { is_enabled: true },
+ code_execution: { is_enabled: false },
+
+ // Agent skills
+ "a1b2c3d4-research-agent": { is_skill: true },
+ "e5f6g7h8-outreach-agent": { is_skill: false },
+};
+```
+
+## Deprecated format
+
+
+The following format is deprecated. It still works but will be removed in a future release. Migrate to the new format above.
+
+
+The old format used two separate list fields:
+
+```typescript
+// Deprecated — do not use in new code
+{
+ disabled_mounts: string[]; // list of mount names to disable
+ disabled_skills: string[]; // list of agent IDs to disable
+}
+```
+
+**Why the new format is preferred:** The object format makes each entry's intent explicit — you can see at a glance whether a mount is enabled or disabled without inferring from inclusion in a list. It also removes the ambiguity around what the default state is when a mount or skill is not listed.
+
+### Migrating from the old format
+
+
+
+ Old code using `disabled_mounts`:
+
+ ```typescript
+ // Old format (deprecated)
+ const chatSettings = {
+ disabled_mounts: ["code_execution", "file_upload"],
+ };
+ ```
+
+ Equivalent new format:
+
+ ```typescript
+ // New format
+ const chatSettings = {
+ code_execution: { is_enabled: false },
+ file_upload: { is_enabled: false },
+ };
+ ```
+
+ Mounts not listed in the new format retain their default state. If you previously relied on the absence from `disabled_mounts` to mean "enabled", explicitly set `is_enabled: true` for those entries to be unambiguous.
+
+
+
+ Old code using `disabled_skills`:
+
+ ```typescript
+ // Old format (deprecated)
+ const chatSettings = {
+ disabled_skills: ["a1b2c3d4-research-agent"],
+ };
+ ```
+
+ Equivalent new format:
+
+ ```typescript
+ // New format
+ const chatSettings = {
+ "a1b2c3d4-research-agent": { is_skill: false },
+ };
+ ```
+
+
+
+ Old code with both fields:
+
+ ```typescript
+ // Old format (deprecated)
+ const chatSettings = {
+ disabled_mounts: ["code_execution"],
+ disabled_skills: ["a1b2c3d4-research-agent", "e5f6g7h8-outreach-agent"],
+ };
+ ```
+
+ Equivalent new format:
+
+ ```typescript
+ // New format
+ const chatSettings = {
+ code_execution: { is_enabled: false },
+ "a1b2c3d4-research-agent": { is_skill: false },
+ "e5f6g7h8-outreach-agent": { is_skill: false },
+ };
+ ```
+
+
+
+## Related pages
+
+
+
+ Trigger agents programmatically using the SDK or HTTP API
+
+
+ Create and continue conversations with agents via the API
+
+
diff --git a/docs.json b/docs.json
index d19ecda9..b340b4b4 100644
--- a/docs.json
+++ b/docs.json
@@ -171,6 +171,14 @@
},
"build/agents/share-your-agent",
"build/agents/delete-agent",
+ {
+ "group": "SDK & API reference",
+ "pages": [
+ "build/agents/extend-your-agent/conversation",
+ "build/agents/extend-your-agent/list-conversations",
+ "build/agents/extend-your-agent/user-chat-settings"
+ ]
+ },
{
"group": "Use-cases & Examples",
"pages": [