Using Built-In Workspace Integrations

Add first-party files, state, 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, HTTP calls, data transformation, date utilities, or code execution.

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`
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": "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: '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="http",
    integration_alias="http",
    display_name="HTTP",
)

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 Advanced Code 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": 45,
        "sandboxPersistence": "persistent",
        "storageMountScope": "workspace"
      }
    }
  }'

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"
    }
  }'

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

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 declarations with weavz_read_api, then call them from weavz_execute.

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 },
})