Using Built-In Workspace Integrations

Add first-party files, state, browser, local computer control, dynamic dashboard, HTTP, transformation, sandbox, and agent-memory tools to a workspace.

Using Built-In Workspace Integrations

Built-in workspace integrations give a workspace useful tools before any end user connects an external account. They are the right default for agent workspaces that need files, durable state, browser control, a user-approved local desktop session, dashboard presentation, HTTP calls, data transformation, date utilities, or code execution.

For AI-native SaaS products, add these built-ins to the workspace first, then expose the workspace through a Code Mode MCP server. Agents should call weavz.files, weavz.state, weavz.browser, and other aliases through MCP; direct API/SDK execution is mainly for smoke tests and backend-owned workflows.

Choose the built-ins

Start with the minimum set the workflow needs:

Need	Add
Store generated files or artifacts	`storage`
Keep small JSON state	`kv-store`
Give agents durable memory	`agent-memory`, `agent-scratchpad`, or `sequential-thinking`
Call arbitrary APIs	`http` or `graphql`
Fetch and extract public web pages	`web-reader`
Drive a logged-in hosted browser with human handoff	`agent-browser`
Run tougher hosted browser workflows with human handoff	`agent-browser-stealth`
Drive a local browser on the user's device	`agent-local-browser-control`
Drive a user-approved local macOS desktop session with deterministic controls	`local-computer-control`
Give agents a goal-driven desktop workspace	`local-computer-control-agent`
Present gathered data as charts, metrics, and tables	`weavz-dynamic-dashboard`
Drive a browser with model-backed actions	`agent-browser-ai`
Drive a hosted stealth browser with model-backed actions	`agent-browser-stealth-ai`
Reshape JSON between calls	`data-transformer`
Parse dates, hash values, or create IDs	`datetime`, `hash-encode`
Run code	`code` or `advanced-code`

Add them to a workspace

Use stable aliases because aliases become the names agents and SDK callers target. For example, use files instead of the base integration name storage if you want code-mode agents to call weavz.files.*.

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "storage",
    "alias": "files",
    "displayName": "Workspace Files",
    "settings": {
      "persistence": {
        "scope": "workspace"
      }
    }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "kv-store",
    "alias": "state",
    "displayName": "Workspace State",
    "settings": {
      "persistence": {
        "scope": "workspace"
      }
    }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "agent-browser",
    "alias": "browser",
    "displayName": "Agent Browser",
    "settings": {
      "persistence": {
        "scope": "end_user"
      }
    }
  }'
 
curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "http",
    "alias": "http",
    "displayName": "HTTP"
  }'

typescript

import { WeavzClient } from '@weavz-io/sdk'
 
const client = new WeavzClient({ apiKey: 'wvz_your_api_key' })
const workspaceId = 'YOUR_WORKSPACE_ID'
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'storage',
  alias: 'files',
  displayName: 'Workspace Files',
  settings: {
    persistence: { scope: 'workspace' },
  },
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'kv-store',
  alias: 'state',
  displayName: 'Workspace State',
  settings: {
    persistence: { scope: 'workspace' },
  },
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'agent-browser',
  alias: 'browser',
  displayName: 'Agent Browser',
  settings: {
    persistence: { scope: 'end_user' },
  },
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'http',
  alias: 'http',
  displayName: 'HTTP',
})
 
await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'weavz-dynamic-dashboard',
  alias: 'dashboard',
  displayName: 'Dynamic Dashboard',
})

python

from weavz_sdk import WeavzClient
 
client = WeavzClient(api_key="wvz_your_api_key")
workspace_id = "YOUR_WORKSPACE_ID"
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="storage",
    integration_alias="files",
    display_name="Workspace Files",
    settings={"persistence": {"scope": "workspace"}},
)
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="kv-store",
    integration_alias="state",
    display_name="Workspace State",
    settings={"persistence": {"scope": "workspace"}},
)
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="agent-browser",
    integration_alias="browser",
    display_name="Agent Browser",
    settings={"persistence": {"scope": "end_user"}},
)
 
client.workspaces.add_integration(
    workspace_id,
    integration_name="http",
    integration_alias="http",
    display_name="HTTP",
)

typescript

const workspaceId = 'YOUR_WORKSPACE_ID'
const headers = {
  'Authorization': 'Bearer wvz_your_api_key',
  'Content-Type': 'application/json',
}
 
for (const integration of [
  {
    integrationName: 'storage',
    alias: 'files',
    displayName: 'Workspace Files',
    settings: { persistence: { scope: 'workspace' } },
  },
  {
    integrationName: 'kv-store',
    alias: 'state',
    displayName: 'Workspace State',
    settings: { persistence: { scope: 'workspace' } },
  },
  {
    integrationName: 'agent-browser',
    alias: 'browser',
    displayName: 'Agent Browser',
    settings: { persistence: { scope: 'end_user' } },
  },
  {
    integrationName: 'http',
    alias: 'http',
    displayName: 'HTTP',
  },
]) {
  await fetch(`https://platform.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
    method: 'POST',
    headers,
    body: JSON.stringify(integration),
  })
}

python

import httpx
 
workspace_id = "YOUR_WORKSPACE_ID"
headers = {"Authorization": "Bearer wvz_your_api_key"}
 
for integration in [
    {
        "integrationName": "storage",
        "alias": "files",
        "displayName": "Workspace Files",
        "settings": {"persistence": {"scope": "workspace"}},
    },
    {
        "integrationName": "kv-store",
        "alias": "state",
        "displayName": "Workspace State",
        "settings": {"persistence": {"scope": "workspace"}},
    },
    {
        "integrationName": "agent-browser",
        "alias": "browser",
        "displayName": "Agent Browser",
        "settings": {"persistence": {"scope": "end_user"}},
    },
    {
        "integrationName": "http",
        "alias": "http",
        "displayName": "HTTP",
    },
]:
    httpx.post(
        f"https://platform.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
        headers=headers,
        json=integration,
    )

Add agent-browser-ai with an alias such as browser_ai when you want natural-language browser actions (act, extract, and observe). Agent Browser AI also exposes the deterministic browser controls, including ensure_connected, snapshot, navigate, screenshots, and human handoff. Only the model-backed actions require the configured model provider connection. The shared provider/model picker supports OpenAI, Anthropic, Google AI, and xAI.

Add agent-browser-stealth-ai with an alias such as stealth_browser_ai when the workflow needs the tougher hosted browser and the same model-backed act, extract, and observe actions. It uses the same provider/model dropdown connection pattern as agent-browser-ai, the same persistence settings as agent-browser-stealth, and the same human handoff flow.

Add agent-browser-stealth with an alias such as stealth_browser when a workflow can run in a hosted browser but needs a tougher browser environment for pages that challenge standard automation. It has the same deterministic actions, screenshots, persistence settings, and human handoff flow as agent-browser. Use local browser control when the site needs the user's own device, network, password manager, or device trust.

Add agent-local-browser-control with an alias such as local_browser when a workflow needs the browser to run on the user's own machine and network. New workspace integrations use the Weavz Local Browser Extension by default; the user signs in through the extension and approves sites before agents control them. Set settings.localBrowser.runtime to managed_profile when the workflow needs the older CLI fallback. Agents call ensure_connected and proceed only when it returns ready: true.

Add local-computer-control with an alias such as computer when a workflow needs a user-approved local desktop session on macOS. The normal path is for the local user to open Weavz Local Computer Control, sign in to the workspace, grant Screen Recording and Accessibility, choose the allowed apps or full-computer display mode, and turn on Allow Weavz to control this computer. Agents cannot widen that local scope from start_session. Its start_session action can also return a one-time companion command for setup or recovery:

bash

npx -y @weavz-io/local-computer-control connect --url "<localRunnerUrl from start_session>"

After the signed-in app is ready, agents call ensure_connected and proceed only when it returns ready: true. The local user keeps visible pause/off controls and can remove the device by signing out. If they reclaim control, resume returns requiresLocalConfirmation: true until the local app confirms agent control again. The preferred action loop is observe first, then semantic element refs such as press_ref, focus_ref, set_text_ref, select_ref, or scroll_ref, followed by wait_for and another observation. Agents should use list_targets and activate_target to focus approved apps instead of driving Spotlight or Finder. Use bounded mouse and keyboard primitives such as move_mouse, click, drag, type, press_key, and scroll only when no safe ref exists, or inside a short run_steps batch with small delays or waitUntil conditions.

Expose them through MCP

For most agent workflows, the next step is to create an MCP server for the same workspace. Code Mode keeps the MCP surface compact while still letting the agent discover and call every configured workspace integration by alias.

bash

curl -X POST https://platform.weavz.io/api/v1/mcp/servers \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Agent Workspace",
    "workspaceId": "YOUR_WORKSPACE_ID",
    "mode": "CODE",
    "authMode": "oauth",
    "endUserAccess": "restricted"
  }'

typescript

const { server, mcpEndpoint } = await client.mcpServers.create({
  name: 'Agent Workspace',
  workspaceId,
  mode: 'CODE',
  authMode: 'oauth',
  endUserAccess: 'restricted',
})

python

result = client.mcp_servers.create(
    name="Agent Workspace",
    workspace_id=workspace_id,
    mode="CODE",
    auth_mode="oauth",
    end_user_access="restricted",
)

typescript

const res = await fetch('https://platform.weavz.io/api/v1/mcp/servers', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Agent Workspace',
    workspaceId: 'YOUR_WORKSPACE_ID',
    mode: 'CODE',
    authMode: 'oauth',
    endUserAccess: 'restricted',
  }),
})
 
const { server, mcpEndpoint } = await res.json()

python

import httpx
 
res = httpx.post(
    "https://platform.weavz.io/api/v1/mcp/servers",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "name": "Agent Workspace",
        "workspaceId": "YOUR_WORKSPACE_ID",
        "mode": "CODE",
        "authMode": "oauth",
        "endUserAccess": "restricted",
    },
)
 
data = res.json()
server = data["server"]
mcp_endpoint = data["mcpEndpoint"]

With the examples above, agents can use aliases such as weavz.files, weavz.state, weavz.http, or weavz.browser depending on which built-ins you added. Use MCP Tool Mode when your client should receive one MCP tool per action instead of Code Mode's compact meta-tools.

Configure scoped persistence

Stateful built-ins default to end_user persistence. Change the scope when a workflow needs shared state or a custom namespace.

json

{
  "settings": {
    "persistence": {
      "scope": "external",
      "externalId": "tenant_123"
    }
  }
}

Use end_user for personal agent memory, workspace for shared project files, and external when your application owns the namespace.

Add Sandbox when needed

code is enough for pure JavaScript data transforms. Use advanced-code when you need Python, shell, network access, or persistent sandbox state.

bash

curl -X POST https://platform.weavz.io/api/v1/workspaces/YOUR_WORKSPACE_ID/integrations \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "integrationName": "advanced-code",
    "alias": "sandbox",
    "displayName": "Sandbox",
    "settings": {
      "advancedCode": {
        "timeoutSeconds": 300,
        "sandboxPersistence": "persistent",
        "storageMountScope": "workspace"
      }
    }
  }'

typescript

await client.workspaces.addIntegration(workspaceId, {
  integrationName: 'advanced-code',
  alias: 'sandbox',
  displayName: 'Sandbox',
  settings: {
    advancedCode: {
      timeoutSeconds: 300,
      sandboxPersistence: 'persistent',
      storageMountScope: 'workspace',
    },
  },
})

python

client.workspaces.add_integration(
    workspace_id,
    integration_name="advanced-code",
    integration_alias="sandbox",
    display_name="Sandbox",
    settings={
        "advancedCode": {
            "timeoutSeconds": 300,
            "sandboxPersistence": "persistent",
            "storageMountScope": "workspace",
        }
    },
)

typescript

await fetch(`https://platform.weavz.io/api/v1/workspaces/${workspaceId}/integrations`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    integrationName: 'advanced-code',
    alias: 'sandbox',
    displayName: 'Sandbox',
    settings: {
      advancedCode: {
        timeoutSeconds: 300,
        sandboxPersistence: 'persistent',
        storageMountScope: 'workspace',
      },
    },
  }),
})

python

import httpx
 
httpx.post(
    f"https://platform.weavz.io/api/v1/workspaces/{workspace_id}/integrations",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "integrationName": "advanced-code",
        "alias": "sandbox",
        "displayName": "Sandbox",
        "settings": {
            "advancedCode": {
                "timeoutSeconds": 300,
                "sandboxPersistence": "persistent",
                "storageMountScope": "workspace",
            }
        },
    },
)

Sandbox settings are workspace-integration settings. timeoutSeconds defaults to 300, sandboxPersistence defaults to ephemeral, and storageMountScope defaults to none. Use storageExternalId only when storageMountScope is external. See Sandbox settings.

Execute a built-in action

You can execute a built-in directly through the standard action endpoint. No connectionId or connectionExternalId is needed for no-auth built-ins.

bash

curl -X POST https://platform.weavz.io/api/v1/actions/execute \
  -H "Authorization: Bearer wvz_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "YOUR_WORKSPACE_ID",
    "integrationName": "storage",
    "integrationAlias": "files",
    "actionName": "write_file",
    "input": {
      "path": "runs/latest.json",
      "content": "{\"status\":\"complete\"}",
      "contentType": "application/json"
    }
  }'

typescript

await client.actions.execute('storage', 'write_file', {
  workspaceId,
  integrationAlias: 'files',
  input: {
    path: 'runs/latest.json',
    content: JSON.stringify({ status: 'complete' }),
    contentType: 'application/json',
  },
})

python

import json
 
client.actions.execute(
    "storage",
    "write_file",
    workspace_id=workspace_id,
    integration_alias="files",
    input={
        "path": "runs/latest.json",
        "content": json.dumps({"status": "complete"}),
        "contentType": "application/json",
    },
)

typescript

await fetch('https://platform.weavz.io/api/v1/actions/execute', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer wvz_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    workspaceId: 'YOUR_WORKSPACE_ID',
    integrationName: 'storage',
    integrationAlias: 'files',
    actionName: 'write_file',
    input: {
      path: 'runs/latest.json',
      content: JSON.stringify({ status: 'complete' }),
      contentType: 'application/json',
    },
  }),
})

python

import httpx
import json
 
httpx.post(
    "https://platform.weavz.io/api/v1/actions/execute",
    headers={"Authorization": "Bearer wvz_your_api_key"},
    json={
        "workspaceId": "YOUR_WORKSPACE_ID",
        "integrationName": "storage",
        "integrationAlias": "files",
        "actionName": "write_file",
        "input": {
            "path": "runs/latest.json",
            "content": json.dumps({"status": "complete"}),
            "contentType": "application/json",
        },
    },
)

For repeated or aliased integrations, prefer workspaceIntegrationId when you have it. Use integrationAlias when you want stable human-readable targeting.

When a workflow needs structured model output, use ai-toolkit with the ask_json action. It returns a parsed json value and raw model text metadata, so agents do not need to infer provider response shapes or manually parse markdown-wrapped JSON.

Use them from MCP Code Mode

When a workspace has a CODE-mode MCP server, workspace integrations are automatically exposed under their aliases. An agent can discover them with weavz_search, inspect one or more declarations with weavz_read_api, then call them from weavz_execute.

For Agent Browser workflows, prefer batching several browser operations in one Code Mode run instead of calling weavz_execute once for each click, read, or screenshot:

javascript

const session = await weavz.browser.start_session({ headless: true });
await weavz.browser.navigate({ sessionId: session.sessionId, url: "https://app.example.com" });
const snapshot = await weavz.browser.snapshot({ sessionId: session.sessionId });
const screenshot = await weavz.browser.screenshot({ sessionId: session.sessionId, quality: 55 });
 
return {
  sessionId: session.sessionId,
  snapshot: String(snapshot.snapshot).slice(0, 3000),
  screenshot: { width: screenshot.width, height: screenshot.height },
};

For non-browser built-ins, the same batching pattern works for files, state, HTTP, and transform steps:

javascript

const run = await weavz.http.send_request({
  method: "GET",
  url: "https://api.example.com/status",
});
 
await weavz.files.write_file({
  path: "runs/status.json",
  content: JSON.stringify(run.body),
  contentType: "application/json",
});
 
await weavz.state.put({
  key: "last_status_check",
  value: { checkedAt: new Date().toISOString(), status: run.status },
});