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.

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, process lists, network configuration, installed software, and environment variables except for names explicitly configured by the host.
• 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 expose workspace_write or workspace_execution tools to an Agent after the matching approval 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

import sys
from pathlib import Path

from function_tools.openai_tools import ToolConfig, create_function_tools

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

# Safe tools can be attached to an Agent immediately.
safe_tools = list(bundle.safe_read)

# Select side-effect tools only after the policy and approval checks pass.
write_tools = list(bundle.workspace_write)
execution_tools = list(bundle.workspace_execution)

The SDK derives each FunctionTool's input schema from the Python signature and docstring. For production, keep the groups separate when attaching them to an Agent; do not use bundle.all by default.

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.