Metadata-Version: 2.4
Name: agents-function-tools
Version: 0.3.0
Summary: Portable, policy-friendly system function tools for AI applications.
License-Expression: Apache-2.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai-agents<1,>=0.1
Requires-Dist: pydantic<3,>=2
Dynamic: license-file

# 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

```bash
python -m pip install agents-function-tools
```

## Included tools

| Category | Tools | Tool group |
|---|---|---|
| Workspace read | List, read UTF-8, inspect metadata, glob-style find, hash files, disk usage | `read` |
| Workspace write | Write text, create directories, copy a regular file, move a path, delete a path | `write` |
| ZIP | List archive entries; create and extract bounded ZIP archives | `read` / `write` |
| Network | Fetch bounded HTTPS text from configured hosts | `read` |
| Host | Non-sensitive system info, UTC time, explicitly allowlisted environment variables | `read` |
| Commands | Describe configured aliases; run one allowlisted executable with `shell=False` | `read` / `execute` |

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 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

```python
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.read),
)
```

`tools.read` is read-only. `tools.write` and `tools.execute` require approval on every call. The SDK derives each FunctionTool's input schema from the Python signature and docstring.

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

```python
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"}),
    )
)
```

## License

Apache-2.0. See [LICENSE](LICENSE).

## Development

Use Python 3.10 or newer:

```powershell
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:

```powershell
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:

```powershell
uv run python scripts/publish.py
```
