agentshield-gateway-sdk

Python client for the AgentShield Tool Security Gateway. Call evaluate() from inside your agent's tool-calling loop before it actually runs a tool, and act on the decision AgentShield returns.

Install

Once published to PyPI, anyone can install it with no local files at all:

pip install agentshield-gateway-sdk

Until then (or for local development), install from a local checkout of the AgentShield repo:

pip install /path/to/agentshield/sdk
# or, for local development (picks up edits without reinstalling):
pip install -e /path/to/agentshield/sdk

Or from git, without cloning first:

pip install "git+https://github.com/<org>/<repo>.git#subdirectory=sdk"

All three install the same distribution, agentshield-gateway-sdk, which provides the importable module sdk (matching the code snippet shown in the dashboard's "Get gateway credentials" step) - the import is identical no matter which install method you used.

Get a credential first

The client needs a gateway credential for the specific agent it's acting on behalf of. Get one from the dashboard: Add Agent → Connect its tools → Get gateway credentials (step 6 of onboarding), or via the API: POST /v1/agents/{id}/credentials. The token is shown only once - store it securely (e.g. an environment variable), not in source control.

Usage

import os
from sdk.client import AgentShieldClient
# or: from sdk import AgentShieldClient

shield = AgentShieldClient(
    base_url="https://your-agentshield-host",
    credential=os.environ["AGENTSHIELD_CREDENTIAL"],
)

result = shield.evaluate(
    tool="email.send",
    action="send",
    target="customer@example.com",
    data_classification="confidential",
)

if result.allowed:
    ...  # actually send the email
else:
    print(f"{result.decision}: {result.reason}")
    # handle BLOCK / REQUIRE_APPROVAL / QUARANTINE - do not proceed

evaluate() returns an EvaluationResult with decision, risk_score, risk_breakdown, policy, reason, and the allowed convenience property (True only when decision == "ALLOW").