Metadata-Version: 2.4
Name: agents-function-tools
Version: 0.2.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`.

## Included tools

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

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

```python
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](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`.
