Agents Function Tools

agents-function-tools is a portable Python library of policy-friendly system function tools. It contains no business model, Agent routing, domain workflow, database adapter, or code-review logic. Its Python import name is function_tools.

Install

python -m pip install agents-function-tools

Included tools

Every tool returns the same JSON envelope with ok, tool, effect, data, and error fields. Paths are always relative to a configured workspace root.

Safety boundary

• Path traversal and access outside the workspace root are rejected.
• The workspace root cannot be deleted.
• Recursive deletion must be explicit.
• File reads, writes, hashes, and archive expansion have byte limits.
• Every workspace mutation and local command requires the SDK approval gate in addition to the orchestration approval policy. File copy accepts regular, non-symlink source files only.
• ZIP creation rejects symlinks; ZIP extraction rejects path traversal and symlink entries before writing files.
• HTTPS fetching requires an exact host allowlist, rejects redirects, URL credentials, and non-default ports, accepts only text-like content types, and blocks resolved private or loopback addresses. No host is enabled by default. Deployment still needs an egress proxy or firewall: application-layer DNS checks do not replace network isolation.
• Host diagnostics intentionally exclude user identities, network configuration, installed software, and environment variables except for names explicitly configured by the host. Process diagnostics are separate, disabled by default, and return only configured process names, PIDs, states, and start times.
• Command execution accepts an argument array, never a shell string. Programs must be mapped by the host application, execution has a timeout, and output is truncated.
• The local command runner is not an OS security sandbox. Production deployment must run the service or runner inside the company-approved container/sandbox with no production secrets and restricted network access.
• Approval remains the orchestration layer's responsibility. Only attach tools.write or tools.execute after the matching approval policy has been validated.

This is a controlled operating-system capability adapter, not a general shell, process-management, credential, service-control, or unrestricted-network interface. Give each business Agent only the smallest subset of these tools it needs.

Example

from pathlib import Path

from agents import Agent

from function_tools import create_tools

tools = create_tools(Path("./workspace"))

agent = Agent(
    name="Workspace assistant",
    instructions="Use workspace tools when needed.",
    tools=list(tools.files.read),
)

Use the narrowest domain selector: tools.files, tools.network, tools.host, or tools.process. The v0.3-style tools.read, tools.write, and tools.execute selectors remain available for compatibility, but combine more capabilities. Every *.write and *.execute tool requires approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.

Design specs

• v0.4 tool expansion spec

For configured commands, HTTPS hosts, or readable environment variables, use ToolConfig:

import sys
from pathlib import Path

from function_tools import ToolConfig, create_tools

tools = create_tools(
    ToolConfig(
        workspace_root=Path("./workspace"),
        command_programs={"python": sys.executable},
        http_allowed_hosts=frozenset({"api.example.internal"}),
        environment_variables=frozenset({"APP_ENV"}),
    )
)

Network diagnostics and process inspection are disabled until explicitly configured:

from function_tools import ToolConfig, create_tools

tools = create_tools(
    ToolConfig(
        workspace_root="./workspace",
        http_allowed_hosts=frozenset({"api.example.internal"}),
        search_engines={"bing": "https://www.bing.com/search"},
        network_allowed_ports=frozenset({443}),
        process_name_allowlist=frozenset({"python.exe"}),
    )
)

network_tools = tools.network.read
process_tools = tools.process.inspect

License

Apache-2.0. See LICENSE.

Development

Use Python 3.10 or newer:

uv sync --python 3.10
uv run --python 3.10 pytest

Tests do not call the OpenAI API and do not require OPENAI_API_KEY.

Release acceptance

Before every PyPI release, run:

uv run python scripts/release_check.py

The gate checks the lockfile, formatting, linting, tests, wheel and source-distribution contents, package metadata, a clean python -m pip install --no-deps <wheel>, and a separate clean runtime installation with dependencies.

Use the following command to run that gate and publish only when it passes:

uv run python scripts/publish.py