Allowed Tools

Tool whitelisting prevents agent confusion by filtering visible tools to only those explicitly allowed, solving collision problems in multi-environment deployments.

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="Use only whitelisted tools",
    tools=["search", "send_message"],
)
agent.start("Search the docs and send a summary")

The user restricts visible tools; the agent only sees whitelisted names from the environment or config.

Quick Start

Set Environment Variable

Enable tool whitelisting by setting ALLOWED_TOOLS to a comma-separated list of tool names:

export ALLOWED_TOOLS="search,send_message"

from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="Use only the whitelisted tools",
    tools=["search", "send_message", "extract_pdf"],  # extract_pdf gets filtered out
)

agent.start("Find recent news and message me a summary")

The user requests news and a message; only tools on the allow-list are exposed to the model.

Programmatic Usage

Use the AllowedToolsFilter class directly for more control:

from praisonaiagents.allowed_tools_filter import AllowedToolsFilter

tool_filter = AllowedToolsFilter()
available_tools = {"search", "send_message", "extract_pdf"}
visible_tools = tool_filter.filter_tools(available_tools)
tool_filter.log_diagnostics()

print(f"Filtered tools: {visible_tools}")

How It Works

The filter operates at tool registration time, intercepting the complete tool registry and returning only whitelisted tools.

Environment State	Behavior
`ALLOWED_TOOLS` unset	All tools visible (with collision warning)
`ALLOWED_TOOLS=""`	Error - empty string not allowed
`ALLOWED_TOOLS=search,send_message`	Only these tools visible
Unknown tool + `CI=true`	Strict failure at startup
Unknown tool + dev mode	Warning logged, unknown tools stripped

Configuration Options

Option	Type	Default	Description
`ALLOWED_TOOLS` (env)	`str` (csv)	unset	Comma-separated tool names to whitelist
`HERMES_ONLY_TOOLS` (env)	`str` (csv)	unset	Deprecated backward-compatibility alias
`CI` (env)	`str`	unset	When truthy (`true`/`1`/`yes`), unknown tools cause startup failure
`env_var_name` (constructor)	`str`	`"ALLOWED_TOOLS"`	Override the primary environment variable name

AllowedToolsFilter Methods

Method	Returns	Description
`filter_tools(available_tools)`	`Set[str]`	Apply whitelist filter to tool set
`is_enabled()`	`bool`	Check if filtering is active
`get_whitelist()`	`Optional[Set[str]]`	Get current whitelist set
`log_diagnostics()`	`None`	Print startup diagnostics report
`get_diagnostics()`	`Dict[str, Any]`	Get diagnostics as dictionary

Common Patterns

Multi-Environment Composition

Combine YouTube, Twilio, and Gmail tool modules while ensuring agents see only canonical tools:

from praisonaiagents import Agent

# Multiple environments might register overlapping tool names
# ALLOWED_TOOLS ensures deterministic tool selection
agent = Agent(
    name="Communication Assistant", 
    instructions="Handle multimedia communication tasks",
    tools=["youtube_search", "twilio_send", "gmail_send", "search", "send_message"]
)
# Only tools in ALLOWED_TOOLS whitelist will be visible

CI/CD Strict Mode

Catch typos early by enabling strict mode in pipelines:

# In CI environment
export CI=true
export ALLOWED_TOOLS="search,send_message,nonexistent_tool"
# This will fail fast with ValueError instead of silently ignoring typos

Backward Compatibility Migration

Existing projects using HERMES_ONLY_TOOLS continue working:

# Legacy (still works)
export HERMES_ONLY_TOOLS="search,send_message"

# Preferred (takes precedence if both are set)
export ALLOWED_TOOLS="search,send_message"

Best Practices

Use exact registered tool names

Tool names are case-sensitive and must match exactly as registered in the tool registry. Use list_tools() to verify available names before whitelisting.

from praisonaiagents.tools import list_tools
print("Available tools:", list_tools())

Enable strict mode in CI pipelines

Set CI=true in automated environments to catch typos in ALLOWED_TOOLS that would otherwise be silently ignored in development.

# In CI/CD pipelines
export CI=true
export ALLOWED_TOOLS="search,send_message"

Prefer ALLOWED_TOOLS over legacy naming

New projects should use ALLOWED_TOOLS instead of the deprecated HERMES_ONLY_TOOLS. The new name is clearer and future-proof.

# ✅ Preferred
export ALLOWED_TOOLS="search,send_message"

# ❌ Deprecated (backward compatibility only)  
export HERMES_ONLY_TOOLS="search,send_message"

Combine with BotConfig for layered security

Environment-variable whitelisting is global and name-based, while BotConfig.allowed_tools provides per-bot runtime filtering. Use both for comprehensive tool security.

from praisonaiagents import Agent, BotConfig

# Global filter (env var): search,send_message,extract_pdf
# Bot-level filter (runtime): search,send_message only
bot_config = BotConfig(allowed_tools=["search", "send_message"])
agent = Agent(name="Bot", bot_config=bot_config)

When to Use ALLOWED_TOOLS

Real-World Scenario

User runs an agent in an environment with YouTube, Gmail, and Twilio integrations. Each provides a send_message tool:

Without ALLOWED_TOOLS: Agent might pick wrong send_message implementation
With ALLOWED_TOOLS: Agent gets deterministic tool set: search,gmail_send,twilio_sms
User types: “/summarize latest emails and send alerts”
Agent behavior: Uses search for email summary, gmail_send for notifications (not the conflicting tools)

Tool Configuration

Environment variables and tool setup

Security Best Practices

Agent and tool security guidelines

Model-Family Harness

Failover

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

How It Works

Configuration Options

AllowedToolsFilter Methods

Common Patterns

Multi-Environment Composition

CI/CD Strict Mode

Backward Compatibility Migration

Best Practices

When to Use ALLOWED_TOOLS

Real-World Scenario

Tool Configuration

Security Best Practices

​Quick Start

​How It Works

​Configuration Options

​AllowedToolsFilter Methods

​Common Patterns

​Multi-Environment Composition

​CI/CD Strict Mode

​Backward Compatibility Migration

​Best Practices

​When to Use ALLOWED_TOOLS

​Real-World Scenario

​Related

Tool Configuration

Security Best Practices

Quick Start

How It Works

Configuration Options

AllowedToolsFilter Methods

Common Patterns

Multi-Environment Composition

CI/CD Strict Mode

Backward Compatibility Migration

Best Practices

When to Use ALLOWED_TOOLS

Real-World Scenario

Related