Tools, connections & context

​

The tools config

{
  "tools": {
    "default_config": { "permission": "allow" },
    "configs": {
      "browser": {
        "enabled": true,
        "permission": "ask",
        "config": { "allowed_domains": ["example.com"] }
      },
      "bash": { "enabled": true, "permission": "allow" }
    }
  }
}

• default_config applies to every tool; a configs entry overrides one tool by name.
• permission is one of allow (run silently), ask (pause → requires_action), or deny (the tool is not offered to the model at all).
• Common patterns: enable-only (default_config.enabled: false, then enable individually) and trust-by-default-except (allow all, set one tool to ask).
• Running sessions keep the config they started with; edits apply to new sessions. Tools can also be re-selected per session while it is idle.

​

Built-in tools

​

Web tools

{
  "tools": {
    "configs": {
      "web_search": {
        "enabled": true,
        "permission": "allow",
        "config": { "blocked_domains": ["competitor.example"] }
      },
      "web_fetch": {
        "enabled": true,
        "permission": "allow",
        "config": {
          "allowed_domains": ["docs.example.com", "status.example.com"],
          "max_content_tokens": 4000
        }
      }
    }
  }
}

• allowed_domains — a non-empty list is a closed list: nothing outside it is reachable. Empty or absent means the open web. A domain covers its subdomains, so example.com matches docs.example.com and never notexample.com.
• blocked_domains — always wins over allowed_domains, so one entry carves a hole in a broad allow-list and the answer never depends on list order.
• max_content_tokens — how much of a fetched page may enter the context; the rest is truncated. Defaults to 4000. Context you never load is context you never pay for.
• The two tools are configured separately — searching broadly while fetching only from a short list of trusted hosts is the common shape.
• A search result outside the policy is dropped from the results; a web_fetch outside it is refused before the page is requested. A page that redirects off the policy is refused too — the host that actually answered is the one that has to be admitted, so an open redirect on an allowed host cannot be used to reach past the list. That refusal comes after the fetch, so unlike the others it is billed.
• Both tools are priced per call against the budget and appear on GET /v1/agents/{id}/spend?by=component under search. The price is what the call cost, so it is booked after the call rather than quoted before it — a domain filter bounds where an agent can go, cap_micro_usd bounds how much it spends getting there.

​

Generation tools

{
  "tools": {
    "configs": {
      "generate_video": {
        "enabled": true,
        "permission": "allow",
        "config": { "models": ["bytedance/seedance-2.5", "openai/sora-2-pro"] }
      }
    }
  }
}

• models — which models this agent may generate with, out of the live catalogue at GET /v1/media/models. It narrows; there is no fixed list to choose from and no enum, because the catalogue belongs to the provider and changes without a release of ours. Omit it and the agent may use anything the provider publishes. Name models and the agent is held to them, with the first one you name as its default.
• Choosing a model. With no models pinned, generate_image runs the cheapest model the provider publishes a price for, and generate_video asks the agent to name one — video carries no published price, so there is no cheapest to fall back to and we will not pick a favourite for you. A refusal lists ids the agent can actually use. Asking for a model outside the pin, or one the catalogue does not have, is refused before anything is submitted.
• Before a job starts, the room left under the agent’s max_task_usd (budgets) is held. A generation job’s cost cannot be known until it finishes, so what the reservation does is admit the job rather than price it: an agent with no real headroom left is refused and nothing is spent. The check happens before the render, not after it.
• You are billed for what the finished job actually cost, once per job, and the rest of the reservation is released the moment the job settles. It appears on GET /v1/agents/{id}/spend?by=component under media.
• A job that fails, or that never finishes, tells the session so and stores nothing.
• seconds, aspect_ratio and seed are optional; a model clamps them to what it supports.

​

Permission policies

​

Connection tools

​

MCP connector

{
  "mcp_servers": [
    { "type": "url", "name": "tracker", "url": "https://mcp.example.com/mcp" }
  ]
}

{
  "tools": {
    "default_config": { "permission": "ask" },
    "configs": {
      "tracker.get_issue": { "enabled": true, "permission": "ask" },
      "tracker.delete_project": { "enabled": false }
    }
  }
}

• Constraints: up to 20 servers per agent; every declared server must be referenced by at least one enabled tool, and every referenced tool must resolve to a declared server.
• Default permission is ask for MCP tools, so a newly exposed server tool never auto-runs. To trust one, give it an explicit "permission": "allow" in configs — per tool, by name. There is no server-wide trust switch.
• Auth is injected at session start, never on the agent: reference vault credentials (static_bearer or mcp_oauth) which are matched to servers by URL and injected server-side. The sandbox never receives the token.
• A connection or auth failure doesn’t stop the session — it surfaces as a session.error event naming the server, and the connection is retried on the next wake.

​

Vetta as its own MCP server

{
  "mcp_servers": [
    { "type": "url", "name": "vetta", "url": "https://api.vetta.sh/v1/mcp" }
  ]
}

• The catalog is generated from the route table, one tool per served route, named resource_verb — agents_create, sessions_list_events, computers_exec_command. Namespaced by the server, a tool is vetta.agents_create in configs, exactly like tracker.get_issue above.
• Argument schemas are the request schemas. Path parameters, declared query filters and body fields arrive as one flat object, validated by the same zod schema /v1/openapi.json publishes.
• Every tool carries annotations.readOnlyHint, so a caller can allow reads and ask on writes without maintaining a list.
• A tool call is an ordinary API call. It is dispatched back through the same middleware with the bearer that made it, so authentication, scope, the plan gate, rate limits and the strict request contract all apply once and identically. A tool can never reach further than its own key.
• Nine routes are withheld from the catalog and answer only over HTTP: this endpoint itself, the SSE stream (GET /v1/sessions/{id}/stream), the multipart upload (POST /v1/files), the four /v1/api_keys routes (they mint and return live secrets), POST /v1/vaults/{id}/credentials (the one route that accepts a secret value) and the model proxy (a credentialed, billed model call is a loop, and its streaming half never returns). None of them is a thing a model should be handed.

​

Tools from your apps

curl -fsSL -X PATCH https://api.vetta.sh/v1/apps/app_01H... \
  -H "authorization: Bearer sk_live_..." \
  -H "content-type: application/json" \
  -d '{ "mcp": "/mcp" }'

• Every agent that can access the app gets its tools. Access is the apps tool’s allowed_apps config — absent means every app in the organization, present means exactly the listed ids. On each turn the platform resolves the app’s current URL plus its mcp path and registers the endpoint’s tools as <app-name>.<tool> (storefront.list_orders), so they are gated by the same default_config + configs allow/ask/deny as every other tool. No per-agent mcp_servers entry, and nothing to update when a custom domain moves the URL.
• Auth is the platform’s own token. Setting mcp mints an opaque bearer, pushes it into the app as the write-only secret VETTA_MCP_TOKEN — the app requires it on its endpoint — and injects it as Authorization: Bearer server-side on every call. It never reaches the sandbox, the transcript or any read route. Setting mcp to null deletes the secret and forgets the token; re-sending the same path never rotates it.
• An unreachable endpoint never fails a turn. An app that is not yet active, or whose MCP endpoint is down or malformed, simply contributes no tools that turn; the platform logs one error line and the agent carries on with the rest of its toolset.

​

Coming soon

• send_email / send_sms as agent tools — today email and SMS are sent via the API/CLI (POST .../send), not from inside a turn.
• Custom tools — organization-defined, client-executed tools: you describe the arguments as a JSON Schema, the model emits a tool-use event, your application runs it and returns the result.

​

Context management