feat(autogen-ext): add OPA tool-call authorization

[Prithvi1994]

Summary

Adds autogen_ext.tools.opa, a new module in autogen-ext that wraps any BaseTool with Open Policy Agent (OPA) authorization, intercepting tool calls before execution.

Motivation

Enterprise multi-agent deployments need declarative, auditable access control over which tools agents can invoke — and which agents can hand off to which other agents. Currently AutoGen has no built-in policy enforcement layer at the tool-execution boundary.

With OWASP LLM Top 10 (2025) listing Excessive Agency and Insecure Tool Use as critical vulnerabilities, a policy-as-code solution that integrates with the OPA ecosystem enterprises already use for Kubernetes is a natural fit.

Design

• OPAAuthorizedTool(inner_tool, opa_url, policy_path, context) — wraps any BaseTool
• Overrides run_json() — the single dispatch point for all tool calls, including agent-to-agent handoff tools (transfer_to_<AgentName>)
• Queries OPA REST API asynchronously via httpx before delegating to inner tool
• fail_open=True/False controls behaviour when OPA is unreachable (default: deny)
• opa_authorize_tools(tools, ...) factory for wrapping tool lists — drop-in replacement

Usage

from autogen_ext.tools.opa import opa_authorize_tools

agent = AssistantAgent(
    name="PlannerAgent",
    model_client=model_client,
    tools=opa_authorize_tools(
        [search_tool, delete_tool, transfer_to_coder],
        opa_url="http://localhost:8181",
        context={"user": "alice", "role": "analyst"},
    ),
)

OPA request body sent for every call:

{
  "input": {
    "tool": "delete_file",
    "args": {"path": "/data/report.csv"},
    "context": {"user": "alice", "role": "analyst"}
  }
}

Sample Rego policy (bundled in policies/autogen_tools.rego):

• Default deny
• Read-only tools allowed for any authenticated user
• Destructive tools (delete, execute, write) restricted to admin role
• Argument-level constraints (e.g. delete_file only permitted under /tmp/)
• Handoff tools (transfer_to_X) restricted to a whitelist of approved agents

Files Changed

• python/packages/autogen-ext/src/autogen_ext/tools/opa/__init__.py
• python/packages/autogen-ext/src/autogen_ext/tools/opa/_opa_tool.py
• python/packages/autogen-ext/src/autogen_ext/tools/opa/_exceptions.py
• python/packages/autogen-ext/src/autogen_ext/tools/opa/policies/autogen_tools.rego
• python/packages/autogen-ext/src/autogen_ext/tools/opa/README.md
• python/packages/autogen-ext/tests/tools/opa/test_opa_tool.py

No Breaking Changes

Zero modifications to autogen-core or autogen-agentchat. Pure extension — any AssistantAgent accepting tools= works transparently with OPAAuthorizedTool.

Test Plan

Full pytest suite using mocked httpx (no real OPA server needed):

• Tool allowed when OPA returns true
• Tool denied when OPA returns false → OPAAuthorizationError
• fail_open=True allows when OPA is unreachable
• fail_open=False raises OPAConnectionError when OPA is unreachable
• opa_authorize_tools() wraps multiple tools correctly
• Handoff tool (transfer_to_X) intercepted identically to regular tools
• OPA payload structure verified
• call_id forwarded correctly to inner tool

[Prithvi1994]

@microsoft-github-policy-service agree