Restrict a tool

This guide puts a ledger lookup in a finance agent behind a permission, so only the people you choose can call it. By the end, a person with the grant can use the tool, everyone else cannot, and every call shows in Settings with who made it and why it was allowed or refused.

Video lesson 9 · 3:04Access and telemetry: run AI agents for a whole teamGrant one restricted tool and trace its use in Activity.

When to use thisCopy Anchor Link

Restrict a tool when it reads or changes something that not every user of the agent should reach, such as payroll data, refunds or a production system. Tools that anyone who can open the agent may use belong in tools_local/ instead. The rules behind this are in identity and access.

What you needCopy Anchor Link

• Sign-in turned on (HUBZOID_AUTH=true), so every person arrives with a verified email. In local mode every request on this machine is the local owner, so you cannot test as different people. See authentication.
• An organization administrator account, or Manage access on the agent. The first administrator comes from hubzoid admin create you@example.com ./finance --owner. An agent administrator grants only capabilities they hold there themselves, so they also need the new permission.

What you will buildCopy Anchor Link

Gate the toolCopy Anchor Link

"""Ledger lookups. Every tool in this file requires the `ledger` permission."""
from __future__ import annotations

import os

import httpx
from agents import function_tool


@function_tool
def ledger_read(account: str, period: str) -> str:
    """Return ledger entries for one account and accounting period.

    Args:
        account: Ledger account code, for example "4000".
        period: Accounting period as YYYY-MM, for example "2026-08".

    Returns:
        The entries as JSON text.
    """
    # Read credentials inside the call. They are loaded from restricted/.env.
    base_url = os.environ["LEDGER_API_URL"]
    token = os.environ["LEDGER_API_TOKEN"]
    response = httpx.get(
        f"{base_url}/entries",
        params={"account": account, "period": period},
        headers={"Authorization": f"Bearer {token}"},
        timeout=20,
    )
    response.raise_for_status()
    return response.text

LEDGER_API_URL=https://ledger.internal.example.com
LEDGER_API_TOKEN=paste-the-token-here

ledger:
  label: Read ledger
  description: View accounting entries and balances.
payroll:
  label: Run payroll
  description: Process employee payroll and view salaries.
  sensitive: true

hubzoid doctor ./finance

Grant access in SettingsCopy Anchor Link

1. Open Settings and choose Agents, then the agent, then the Access tab.
2. Choose who gets the tool:
   • Someone already listed: select Edit access on their row.
   • Someone with an account but no access to this agent: open them under People and select Add an agent.
   • Someone new: select Add user and enter their name and email.
3. Open Restricted tools and tick Read ledger. Use this agent is already ticked and stays ticked, because every capability includes entry to the agent.
4. Select Review changes. The review lists the person, the agent and the capabilities being added and removed, and marks sensitive ones.
5. Select Save change, or Create account for a new user. Settings confirms with "Access updated", or "User added" for a new user.

The new permission applies on the person's next call. Every screen in this flow is described in agents and access.

What else the Access editor holdsCopy Anchor Link

Besides Restricted tools, the editor groups the agent's other capabilities. Each group is described in agents and access.

Grant access from the CLICopy Anchor Link

The same access store is available on the server. Commands take the Hub folder as their last argument and use its name as the agent, or another agent with --hub.

hubzoid grant priya@example.com ledger ./finance

granted priya@example.com · ledger in finance

use_hub is added automatically. The CLI writes the permission name exactly as you type it, while Settings offers only capabilities that exist, so check the spelling against the file name.

# Every permission a person effectively holds in the agent
hubzoid access check priya@example.com ./finance

# Every grant in one agent
hubzoid access list ./finance --hub finance

# Remove one permission, or use_hub to remove everything in the agent
hubzoid revoke priya@example.com ledger ./finance
hubzoid revoke priya@example.com use_hub ./finance

Grant a workflowCopy Anchor Link

Workflows and markdown tasks run as an ordinary account: their run_as, else HUBZOID_WORKFLOW_USER, else the owner recorded at setup. That account's grants decide what they may call, so grant it ledger like any person. The full rules are in workflows and schedules.

from hubzoid import hub, workflow


@workflow(schedule="0 6 1 * *", timezone="Asia/Kolkata", run_as="reports@example.com")
def monthly_close():
    if not hub.user.can("ledger"):
        raise RuntimeError(f"{hub.user.email} needs the ledger permission")
    return hub.call_agent("Summarize last month's ledger entries for account 4000.")

Test allowed and denied callsCopy Anchor Link

Test with real people. hubzoid test runs with no signed-in person, so it cannot reach a restricted tool. An eval with run_as checks the same rule from the command line.

1. Sign in as the person you granted and ask:

   Show the ledger entries for account 4000 in 2026-08.

   The agent calls ledger_read, and a row with the decision allow and the reason grant is written.

2. Sign in as someone who holds only Use this agent. The tool is hidden from them on every runtime, so the agent answers without it and no row is written. A call that reaches the tool another way is refused with an access denied message, and a no-grant row is written.

3. Sign in as someone with no grant in the agent. Their chat requests to it are refused.

To test the workflow, start it by hand with hubzoid schedule run ./finance monthly_close. Its tool calls are recorded with the account it runs as and the channel workflow.

Read the decisions in the audit logCopy Anchor Link

Open Settings → Activity → Audit log and switch to Tool decisions, or select View activity on the agent's page. Each row says who used which tool, with an Allowed or Denied tag.

The same rows are available on the server with hubzoid audit.

hubzoid audit ./finance --user priya@example.com
hubzoid audit ./finance --denied --limit 100

If something goes wrongCopy Anchor Link

How files map to permissionsCopy Anchor Link

One permission per file. The file name in lowercase, without .py, is the permission.

Where secrets liveCopy Anchor Link

Secrets for restricted tools live in restricted/.env, which the agent's own file tools cannot open.

Where restricted tools can be reachedCopy Anchor Link

A restricted tool runs only on channels where each request carries one verified person. The default list covers the web app, the API, MCP, workflows and apps that embed the chat. Slack, WhatsApp and Telegram are not in it. If you set HUBZOID_RESTRICTED_SURFACES, keep the channels you rely on in the list.

Next stepsCopy Anchor Link