Algen Agent Tools

Curated, governed connectors for agents built on 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.

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.

Install

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

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

The package supports algen-agent-runtime>=0.1.0a11,<0.2; see compatibility.

Use a connector

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

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:

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:

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

MCP servers

For services with a well-maintained MCP server, algen_agent_tools.mcp adds a governance overlay 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.

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.

Proposed connectors follow the connector policy: 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

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, writing a connector and the release process.

Security

Report vulnerabilities privately as described in SECURITY.md. Do not open a public issue.

License

Apache License 2.0.