Configuration

This page documents the public configuration types used by @interopio/io-assist-react.

---

Installation Model

Before configuration, keep the package setup model clear:

• install @interopio/io-assist-react
• ensure react and react-dom are present — they are the only peer dependencies
• import @interopio/io-assist-react/styles

Everything else — the io.Connect platform packages (@interopio/browser, @interopio/desktop), the core intelligence library (@interopio/ai-web), and @interopio/working-context — is declared as a package dependency and installed automatically. You still import a platform factory (for example @interopio/browser) to pass into connectConfig.

---

IoAssistStaticConfig

IoAssistStaticConfig is passed as the staticConfig prop.

type IoAssistStaticConfig = {
    connectConfig: {
        browser?: { factory: IOConnectBrowserFactoryFunction; config?: IOConnectBrowser.Config };
        desktop?: { factory: (config?: IOConnectDesktop.Config) => Promise<IOConnectDesktop.API>; config?: IOConnectDesktop.Config };
    };
    aiWebConfig: {
        agentServer: IoAiWeb.AgentServerConfig;
        mcp?: IoAiWeb.MCPConfig;
    };
    defaultAgentName?: string;
    workingContext?: IoAiWeb.WorkingContextConfig;
    defaultPrompts?: IoAssistPromptCategory[];
};

Properties

Property	Type	Required	Description
connectConfig	object	Yes	io.Connect platform setup. Must include a browser and/or desktop entry, each with a factory and optional config
aiWebConfig	object	Yes	Underlying AI Web configuration. See AI Web Configuration
defaultAgentName	string	No	Agent name to select on startup
workingContext	IoAiWeb.WorkingContextConfig	No	Working Context factory and configuration
defaultPrompts	IoAssistPromptCategory[]	No	Prompt library entries shown in the assistant UI

Required Minimum

At minimum, static config needs:

• connectConfig with a platform factory
• aiWebConfig.agentServer.baseUrl

---

AI Web Configuration

aiWebConfig is the io.Assist React wrapper around the underlying AI Web configuration. It is an inline object on IoAssistStaticConfig (there is no separately exported AIWebConfig type).

aiWebConfig: {
  agentServer: IoAiWeb.AgentServerConfig;
  mcp?: IoAiWeb.MCPConfig;
};

Notes

• baseUrl is the only required field on agentServer. It also accepts retry and backoff options, fetch credentials mode, and other IoAiWeb.AgentServerConfig fields.
• MCP, remote servers, MCP Apps, and capability handlers all flow through mcp.
• Although agentServer accepts a headers field, request headers are sourced from the dynamic config (dynamicConfig.agentServer.headers) and override anything set here. Put per-user headers there so they can be supplied after login.

Example

aiWebConfig: {
  agentServer: {
    baseUrl: 'http://localhost:4111',
    retries: 3,
    backoffMs: 1000,
    maxBackoffMs: 10000,
  },
  mcp: {
    clientsConfig: {
      capabilities: {},
    },
  },
}

---

IoAssistDynamicConfig

IoAssistDynamicConfig is passed as the dynamicConfig prop.

type IoAssistUserConfig = {
    id: string;
    name?: string;
};

type IoAssistDynamicConfig = {
    user: IoAssistUserConfig;
    agentServer?: {
        headers?: Record<string, string>;
    };
};

Properties

Property	Type	Required	Description
user.id	string	Yes	Unique user identifier used to scope thread history
user.name	string	No	Display name shown in the assistant UI
agentServer.headers	Record<string, string>	No	Per-user request headers such as auth tokens. This is the only source of request headers

Why the Split Matters

This config is designed for values that are only known at runtime:

• the current authenticated user
• per-user authorization headers
• values that may change without rebuilding the static configuration

The recommended pattern is to memoize dynamicConfig from auth state and render IoAssist only once a user is present. See Component API.

---

Prompt Shapes

Prompt library entries are authored as inline literals on defaultPrompts. They are not exported as named types, but their structure is:

type IoAssistPrompt = {
    name: string;
    prompt: string;
    iconResource?: IconResource;
};

type IoAssistPromptCategory = {
    category?: string;
    prompts: IoAssistPrompt[];
};

IconResource

type IconResource = {
    type: 'svg' | 'url' | 'data-url';
    data: string;
};

Type	Notes
'svg'	Inline SVG string. Sanitized: fill, width, height stripped; hardcoded colors become currentColor
'url'	Absolute URL or absolute path from the document root
'data-url'	Base64-encoded SVG, PNG, or JPEG

Prompts without an icon show a default icon.

Example

defaultPrompts: [
    {
        category: 'General',
        prompts: [
            {
                name: 'Summarize',
                prompt: 'Please summarize the following content:',
            },
            {
                name: 'Explain',
                prompt: 'Please explain this in simple terms:',
                iconResource: {
                    type: 'svg',
                    data: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="..."/></svg>',
                },
            },
        ],
    },
];

---

Working Context Configuration

When enabled, workingContext uses the same factory-and-config pattern as the standalone Working Context package.

import { IoIntelWorkingContextFactory } from '@interopio/working-context';

workingContext: {
  factory: IoIntelWorkingContextFactory,
  config: {
    schema: {
      clientId: {
        type: 'string',
        source: {
          context: {
            location: { workspace: { target: 'my' } },
            path: 'clientId',
          },
        },
      },
    },
  },
}

For the schema model itself, see Working Context Schema Configuration.

---

Stylesheet Requirement

The component styles are exposed through the package ./styles export:

@import '@interopio/io-assist-react/styles';

Add the import wherever your app loads global CSS (for example src/styles.css or your root entry). Without the stylesheet import, the component will not render as intended.