Workspaces, helpers, and browser automation

​

Use one workspace path model

• Read text with POST /workspace/read.
• Browse with /workspace/list, /workspace/find, and /workspace/search.
• Write or edit text with /workspace/write and /workspace/edit.
• Preview or download a file with GET /workspace/preview or /workspace/download.
• Upload with multipart POST /workspace/upload.
• Delete one file or empty directory with DELETE /workspace/delete?path=....

​

Understand the helper contract

• registered name
• argument schema
• whether Browser access is required
• owning skill slug
• declared managed-credential IDs

​

Author a reusable helper

• Use @browser_function(...) when the operation requires the Agent’s Browser session.
• Use @computer_function(...) when the operation can run without opening or consulting the Browser.
• Declare required credential IDs in source and resolve them at execution time.
• Keep the helper contract narrow, independently invocable, and based on durable inputs rather than hidden prior state.

​

Example: call an API without opening the Browser

import json
from urllib import error, parse, request

from vida_helper_runtime import computer_function, managed_secret


API_ROOT = "https://api.example.com/v1"


@computer_function(
    domain="api.example.com",
    description="Look up one customer by its external ID.",
    args={
        "type": "object",
        "required": ["customer_id"],
        "properties": {
            "customer_id": {
                "type": "string",
                "description": "Exact customer ID from the source system.",
            },
        },
    },
    result={
        "type": "object",
        "required": ["status", "summary"],
        "properties": {
            "status": {"type": "string", "enum": ["done", "blocked", "need_user"]},
            "summary": {"type": "string"},
            "reason": {"type": "string"},
            "httpStatus": {"type": "integer"},
            "result": {
                "type": "object",
                "properties": {
                    "customerId": {"type": "string"},
                    "name": {"type": "string"},
                },
            },
        },
    },
    required_secrets=["example_api_token"],
)
def lookup_customer(customer_id):
    customer_id = str(customer_id or "").strip()
    if not customer_id:
        return {
            "status": "blocked",
            "summary": "A customer ID is required.",
            "reason": "invalid_customer_id",
        }

    token = managed_secret("example_api_token")
    url = f"{API_ROOT}/customers/{parse.quote(customer_id, safe='')}"
    api_request = request.Request(
        url,
        headers={"Authorization": f"Bearer {token}", "Accept": "application/json"},
    )

    try:
        with request.urlopen(api_request, timeout=15) as response:
            payload = json.loads(response.read().decode("utf-8"))
    except error.HTTPError as exc:
        if exc.code in (401, 403):
            return {
                "status": "need_user",
                "summary": "The API connection must be updated.",
                "reason": "authentication_required",
                "httpStatus": exc.code,
            }
        return {
            "status": "blocked",
            "summary": "The customer API rejected the lookup.",
            "reason": "api_error",
            "httpStatus": exc.code,
        }
    except (error.URLError, TimeoutError, json.JSONDecodeError):
        return {
            "status": "blocked",
            "summary": "The customer API could not return a usable response.",
            "reason": "api_unavailable",
        }

    return {
        "status": "done",
        "summary": "Customer found.",
        "result": {
            "customerId": str(payload.get("id", customer_id)),
            "name": str(payload.get("name", "")),
        },
    }

1. Write the owning SKILL.md and helper source with POST /workspace/write.
2. Save example_api_token with POST /secrets using {secretId, value}.
3. Call POST /helpers/refresh. Require ok: true, no validation errors, and the expected helper contract in functions.
4. Confirm the same contract through GET /helpers.
5. Run a safe lookup through POST /helpers/execute with {name: "lookup_customer", arguments: {customer_id: "..."}}.
6. Check the helper’s structured status and business result. For a write operation, also read the destination system before retrying after a timeout or uncertain response.
7. Discover the Agent’s available functions, stage the exact computer action and argument mapping, run a conversational test, then publish only after it succeeds.

​

Record and generate a Browser workflow

1. Create POST /browser/automation-sessions and retain its cdpUrl, headers, slot, and expiration.
2. Read {cdpUrl}/json/version with the returned header and connect browser tooling to its webSocketDebuggerUrl. For local automation, Browser Harness is the recommended client: provide that ticket-bearing WebSocket URL as BU_CDP_WS. Do not provide the protected discovery URL as BU_CDP_URL when the client cannot attach the required discovery header.
3. Confirm no recording or generation is active.
4. Start recording with the automation session’s exact slot.
5. Perform the representative workflow through the CDP connection.
6. Stop recording and retain domainKey, recordingId, and evidenceRoot. Require finalized: true and analysisStatus: completed before generation.
7. Start generation, optionally supplying a neutral skillName.
8. Retain the returned generationId and immutable recordingIds evidence snapshot. New recordings require a new generation; they are not appended to work already in progress.
9. Poll phase, updatedAt, and lastActivityAt until terminal and use the returned conversation reference to inspect work and tool calls.
10. Re-list helpers and test every required operation.

​

Expose a helper to a conversational Agent

​

Accept a reusable helper

1. Registry: /helpers exposes its exact inputs, result metadata, owner, Browser requirement, and required credential IDs.
2. Execution: a safe representative /helpers/execute call works and its normalized runtime fields match the registered result metadata. Verify the destination effect when one is expected.
3. Conversation: Agent function discovery exposes Computer, and a staged conversational test can select and use the helper in the intended environment.