Restrict a tool

This guide gates a ledger lookup in a finance agent so that only the people you choose, including the accounts your workflows run as, can call it. By the end, a signed-in person with the grant can use the tool, everyone else cannot, and each call appears in the Console with who made it and why it was allowed or refused.

When to use thisCopy Anchor Link

Use a restricted tool when a tool 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 model behind the rules is explained in Identity and access.

Before you startCopy Anchor Link

• The hub uses managed access. A hub created with hubzoid init becomes managed when the configured owner first signs in. Otherwise, on a fresh install, run hubzoid access bootstrap --admin you@example.org --authoritative ./finance once. A hub that still uses Open WebUI groups is migrated first, as described in Access administration.
• Sign-in is on in the chat app, so every person arrives with a verified email. See Authentication.
• You can open the Console as an organization administrator, or hold manage_access in the agent. An agent administrator grants only capabilities they hold there themselves, so they also need ledger.

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.org
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
hubzoid run ./finance

Grant access in the ConsoleCopy Anchor Link

1. Open the Console at /portal/ (locally http://localhost:3080/portal/) and choose Agents, then the agent, then the Access tab.
2. For someone already listed, select Edit access on their row. For an existing user without access to this agent, open them under People and select Add an agent. For someone new, select Add user and enter their name, email and a password you type or generate. Where Google sign-in is set up, Google sign-in only creates the account with no password. Nothing is emailed.
3. Open Restricted tools and tick Read ledger. Use this agent is already ticked and stays ticked while any other capability is selected, because every capability includes entry to the agent.
4. Select Review changes. The review lists who, the agent, and the capabilities being added and removed, and marks sensitive ones.
5. Select Save change (with a count when there is more than one), or Create account for a new user. The whole change set is saved in one transaction, and the Console confirms with "Access updated", or "User added" for a new user, whose password is shown once to copy and share with them yourself.

The permission check changes on the next call. The agent list in the chat app follows within about 30 seconds. Every screen in this flow is described in Agents and access.

Grant access from the CLICopy Anchor Link

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

# Grant. use_hub is added automatically.
hubzoid grant priya@example.org ledger ./finance

# Show every permission a subject effectively holds in the agent
hubzoid access check priya@example.org ./finance

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

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

hubzoid access check prints a line such as priya@example.org in finance: ledger, use_hub. CLI changes are recorded with the operating system user as the actor and appear in Activity as a server operator. The CLI writes the permission name exactly as you type it, while the Console offers only capabilities that exist in the agent, so check the spelling against the file name.

Unlike the Console, hubzoid grant also accepts an email that has no account yet. The access applies when someone first signs in with that email, for example through single sign-on.

Grant a workflowCopy Anchor Link

Workflows and markdown tasks run as an ordinary account, and that account's grants decide what they may call. The account is the first of:

1. run_as on the @workflow declaration, or in the markdown task's frontmatter
2. HUBZOID_WORKFLOW_USER, from the hub's settings, then the deployment's
3. on a hub managed in the Console, the owner recorded at setup

Grant that account ledger like any person, with Edit access in the Console or hubzoid grant. It must have signed in once and hold Use this agent. For shared automation, create an ordinary account for it, such as reports@example.org. hubzoid schedule list ./finance and the Runs as column in the Console show who each workflow runs as.

When the workflow calls the agent with hub.call_agent, the agent acts as the run's account on the workflow surface, so the same guard decides and logs the call. A workflow can also check the grant before doing work:

from hubzoid import hub, workflow


@workflow(schedule="0 6 1 * *", timezone="Asia/Kolkata", run_as="reports@example.org")
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.")

Grants to the older workflow:monthly_close or workflow:md:<task> service identities are kept, but runs that act as an account do not use them. The Console shows them as Legacy service identity and cannot add new ones. Grant the permission to the account instead, then revoke the old grant.

If you set HUBZOID_RESTRICTED_SURFACES, keep workflow in the list, or these calls are refused with surface:workflow.

Test allowed and denied callsCopy Anchor Link

Test with real identities. hubzoid test runs with no signed-in person, so it cannot reach a restricted tool. It is useful to confirm the rest of the agent works.

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, reports@example.org, and the surface workflow.

Read the decision in ActivityCopy Anchor Link

Open the agent and choose the Activity tab, then Tool decisions. Each row reads as a sentence, such as "Priya used ledger_read in Finance Assistant via owui", with a green Allowed or red Denied tag. Filter by outcome, person, tool or channel, and select Details for the exact time, tool, channel and reason. The cross-agent view is the Activity page in the sidebar.

The same rows are available on the server:

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

Each line shows the time, the caller, ALLOW or DENY, the tool and the surface with the reason.

TroubleshootingCopy Anchor Link

Next stepsCopy Anchor Link

Read this page as Markdown