Using Built-In Workspace Integrations

Add first-party files, state, browser, 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, 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 browser with human handoff	`agent-browser`
Drive a browser with natural-language LLM actions	`agent-browser-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://api.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://api.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://api.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://api.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/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',
})

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://api.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://api.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 uses the same browser session and persistence model as agent-browser, but it requires a user-provided LLM provider connection before its actions can run.

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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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://api.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 },
});