Metadata-Version: 2.5
Name: algen-agent-tools
Version: 0.2.0a1
Summary: Curated, governed connectors for Algen Agent Runtime agents
Project-URL: Homepage, https://github.com/AlgenAI/algen-agent-tools
Project-URL: Source, https://github.com/AlgenAI/algen-agent-tools
Project-URL: Documentation, https://github.com/AlgenAI/algen-agent-tools#readme
Project-URL: Issues, https://github.com/AlgenAI/algen-agent-tools/issues
Project-URL: Changelog, https://github.com/AlgenAI/algen-agent-tools/blob/main/CHANGELOG.md
Author: AlgenAI
Maintainer: AlgenAI
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent-tools,agents,ai-governance,connectors,llm,mcp
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: algen-agent-runtime<0.2,>=0.1.0a12
Provides-Extra: all
Requires-Dist: algen-agent-runtime[mcp]<0.2,>=0.1.0a12; extra == 'all'
Requires-Dist: asyncpg<1,>=0.29; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy<3,>=1.11; extra == 'dev'
Requires-Dist: pytest-asyncio<2,>=1.3; extra == 'dev'
Requires-Dist: pytest-cov<8,>=5; extra == 'dev'
Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
Requires-Dist: ruff<1,>=0.6; extra == 'dev'
Provides-Extra: gmail
Provides-Extra: mcp
Requires-Dist: algen-agent-runtime[mcp]<0.2,>=0.1.0a12; extra == 'mcp'
Provides-Extra: postgres
Requires-Dist: asyncpg<1,>=0.29; extra == 'postgres'
Provides-Extra: smtp
Description-Content-Type: text/markdown

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AlgenAI/algen-agent-tools/refs/heads/main/docs/assets/brand/banner-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/AlgenAI/algen-agent-tools/refs/heads/main/docs/assets/brand/banner-light.svg">
  <img alt="Algen Agent Tools — Typed tools for agents. Governed by default." src="https://raw.githubusercontent.com/AlgenAI/algen-agent-tools/refs/heads/main/docs/assets/brand/banner-light.svg">
</picture>

# Algen Agent Tools

[![Quality](https://github.com/AlgenAI/algen-agent-tools/actions/workflows/quality.yml/badge.svg)](https://github.com/AlgenAI/algen-agent-tools/actions/workflows/quality.yml)
[![Security](https://github.com/AlgenAI/algen-agent-tools/actions/workflows/security.yml/badge.svg)](https://github.com/AlgenAI/algen-agent-tools/actions/workflows/security.yml)
[![PyPI](https://img.shields.io/pypi/v/algen-agent-tools.svg)](https://pypi.org/project/algen-agent-tools/)
[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

Curated, governed connectors for agents built on
[Algen Agent Runtime](https://github.com/AlgenAI/algen-agent-runtime).

Each connector is a Runtime `Toolkit` of narrow, typed actions, registered through a declared
plugin. An agent names the plugin in `agent.yaml`, the Runtime checks every tool it enables, and
Algen Agent Studio lists each tool with its side effect, permissions and environment variables
from `algen-agent-runtime describe`, without running project code.

> [!IMPORTANT]
> `0.2.0a1` is a pre-release. Tool contracts may change between alpha releases; every change is
> recorded in [CHANGELOG.md](CHANGELOG.md) with an upgrade note. Review the
> [security policy](SECURITY.md) and each connector's guarantees before deployment.

## Why a separate package

- The Runtime stays small and domain-agnostic; vendor APIs change faster than its core.
- Connectors get their own release cadence, owners and security review.
- Every connector is a plugin, so Studio sees it with no extra work.

| Layer | Package | Contains |
| --- | --- | --- |
| Core | `algen-agent-runtime` | Contracts, `@tool`, presets, `Toolkit`, plugins, `describe`, MCP and HTTP adapters |
| Connectors | `algen-agent-tools` | Generic toolkits, one optional extra each |
| Domain packs | Their own packages | Product-specific tools (hiring, text-to-SQL, HR, ...) |

## Install

Python 3.12 or 3.13. Install the package with the extra for each connector you use:

```bash
pip install "algen-agent-tools[postgres]"        # one connector
pip install "algen-agent-tools[all]"             # every connector
```

The package supports `algen-agent-runtime>=0.1.0a12,<0.2`; see
[compatibility](docs/compatibility.md).

## Use a connector

Name the connector's plugin in `domain_plugins`, trust the package's prefix, enable the tools
and grant their permissions:

```yaml
agents:
  - name: assistant
    version: 1.0.0
    description: Checks that tools are wired up
    system_instructions: Use sample.echo when asked to echo text.
    default_model: {name: m, provider: demo}
    domain_plugins: [algen_agent_tools.sample]
    enabled_tools: [sample.echo]
    tool_permissions: [sample.read]
security:
  trusted_plugin_prefixes: [algen_agent_tools]
```

Then check the project the way Studio will:

```bash
algen-agent-runtime check agent.yaml
algen-agent-runtime describe --config agent.yaml --json
```

Each zero-configuration plugin reads its settings from `env://` references at the moment its
client first opens, never at import. To configure a connector in code (another name, other
environment variables, a fake for tests), build its toolkit in your own plugin:

```python
from algen_agent_runtime.plugins.sdk import PluginManifest, plugin
from algen_agent_tools.sample import sample_toolkit


@plugin(PluginManifest(name="acme.tools", version="1.0.0", publisher="acme"))
class AcmeTools:
    def register(self, context):
        sample_toolkit(name="diagnostics").register(context)
```

## Connectors

| Connector | Plugin | Extra | Tools | Docs |
| --- | --- | --- | --- | --- |
| PostgreSQL | `algen_agent_tools.postgres` | `postgres` | `postgres.list_tables`, `postgres.describe_table` (read), plus your own typed queries | [postgres](docs/connectors/postgres.md) |
| SMTP | `algen_agent_tools.smtp` | `smtp` | `smtp.send_email` (external) | [smtp](docs/connectors/smtp.md) |
| Gmail | `algen_agent_tools.gmail` | `gmail` | `gmail.list_messages` (read), `gmail.send_email` (external) | [gmail](docs/connectors/gmail.md) |
| Sample | `algen_agent_tools.sample` | none | `sample.echo` (read) | [sample](docs/connectors/sample.md) |

### MCP servers

For services with a well-maintained MCP server, `algen_agent_tools.mcp` adds a
[governance overlay](docs/mcp-overlays.md) instead of a native client: a reviewed mapping that
declares each remote tool's side effect, permission, approval rule and pinned input schema. The
tools appear in `describe` and Studio before anything connects, undeclared tools are never
exposed, and a tool whose schema changes is refused until it is reviewed again.

```bash
pip install "algen-agent-tools[mcp]"
python -m algen_agent_tools.mcp snapshot server.yaml --name github --output github.overlay.yaml
```

Moving from the Runtime's built-in email and database connectors? See
[migrating from the Runtime](docs/migrating-from-runtime.md).

Proposed connectors follow the [connector policy](docs/connector-policy.md): at least two
projects need it, it holds no domain logic, it has an owner and it passed a security review.
When a well-maintained MCP server exists, the package ships a governance overlay instead of a
native client.

## Rules every connector follows

- Narrow, typed actions (`list_open_invoices`, `post_message`), never a raw passthrough such as
  free-form SQL or arbitrary HTTP.
- Side effect, permission, idempotency, retries and timeout come from a Runtime preset.
  Anything that writes, sends or deletes is keyed by the idempotency key and tried once.
- Secrets are `env://` references only, resolved when a client opens.
- An in-memory fake for offline tests; live tests run only when `ALGEN_TOOLS_LIVE=1`.
- Every toolkit passes `algen_agent_tools.testing.assert_toolkit_contract`.

## Development

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e '.[dev]'
make check
```

See [CONTRIBUTING.md](CONTRIBUTING.md), [writing a connector](docs/writing-a-connector.md) and
[the release process](docs/releasing.md).

## Security

Report vulnerabilities privately as described in [SECURITY.md](SECURITY.md). Do not open a public
issue.

## License

[Apache License 2.0](LICENSE).
