AgentBuck Python SDK

agentbuck is the public Python SDK for AgentBuck runtime validation.

Install

pip install agentbuck

Import

import agentbuck

api_key = "<api key provided by caller>"
client = agentbuck.AgentBuckClient(api_key=api_key)
result = client.validate_bulk(
    agent_id="agent-123",
    idApp=456,
    data=[{"email": "user@example.com"}],
)

Successful validation returns a dictionary with engine status, message, and decisions:

{
    "status": "success",
    "message": "",
    "decisions": ["PROCEED", "BLOCK"],
}

Authorization failures are returned by the engine in the same response shape:

{
    "status": "failed",
    "message": "idApp not accessible",
    "decisions": [],
}

The SDK endpoint can be provided directly, loaded from a custom env file, or read from AGENTBUCK_GRPC_TARGET in the process environment. If no endpoint or custom env file is provided, the SDK also loads a standard .env file from the current working directory when present.

Examples:

AGENTBUCK_GRPC_TARGET=tcp://127.0.0.1:50051

client = agentbuck.AgentBuckClient(
    api_key=api_key,
    endpoint="tcp://127.0.0.1:50051",
)

client = agentbuck.AgentBuckClient(
    api_key=api_key,
    env_file="/path/to/custom.env",
)

Endpoint lookup order:

1. Explicit endpoint=...
2. Explicit env_file=...
3. AGENTBUCK_GRPC_TARGET from the process environment or .env in the current working directory

Endpoint values must use tcp://host:port format.

Authentication

Pass an API key when creating the client:

api_key = "<api key provided by caller>"
client = agentbuck.AgentBuckClient(api_key=api_key)

The API key must be provided by the caller through api_key=....

Public API

• agentbuck.AgentBuckClient
• agentbuck.HealthResult
• agentbuck.ValidateBulkResult

License

The SDK is licensed under Apache-2.0. Copyright 2026 AgentBuck.

Build and verify a release

From a clean checkout, install the release tools and build both distribution formats:

python -m pip install build twine
python -m build
python -m twine check --strict dist/*
python scripts/verify_release.py dist

verify_release.py checks that the wheel and source distribution have matching versions, Apache-2.0 metadata, the license files, the type marker, and the generated gRPC modules. It also checks that the source distribution contains validation.proto and the generator script. The generated Python modules are checked in; installing the SDK does not run the generator or need grpcio-tools.

GitHub Actions runs these checks and installs both archives in clean environments on Python 3.10, 3.11, 3.12, and 3.13.

Verify against a running engine

On Windows, install the built wheel into a fresh environment, then run the interactive check:

py -3.12 -m venv .venv-pypi-check
.\.venv-pypi-check\Scripts\python.exe -m pip install .\dist\agentbuck-0.1.0-py3-none-any.whl
.\.venv-pypi-check\Scripts\python.exe .\scripts\verify_live.py --csv "C:\path\to\data.csv" --endpoint "tcp://host:port" --agent-id "agent-123" --idapp 370

The script prompts for api_key without echoing it. If omitted, --csv and --endpoint are prompted for too. The defaults are agent-123 and 370 for --agent-id and --idapp. It reads CSV records using the same header handling as the SDK, times validate_bulk, and shows each row whose decision is BLOCK. It checks the decision count before pairing decisions with rows. A successful live check ends with Live SDK validation succeeded. The server must be running and the API key must be allowed to validate the chosen idapp and agent_id.

Publish to PyPI

One-time setup:

1. Publish this repository at the public FirstEigen-Labs/agentbuck_sdk path and update this checkout's origin URL to that repository.
2. In that repository's Settings → Environments, create pypi. Require a reviewer before deployment and allow release tags matching v*.
3. In PyPI's publishing settings, register a pending GitHub trusted publisher with project agentbuck, owner FirstEigen-Labs, repository agentbuck_sdk, workflow release.yml, and environment pypi. A pending publisher does not reserve the project name.

For the first release, keep pyproject.toml and agentbuck.__version__ at 0.1.0. After CI passes, push the v0.1.0 tag:

git tag v0.1.0
git push origin v0.1.0

The release workflow checks the tag against the distribution version, rebuilds and verifies the archives, and waits for approval in the pypi environment before uploading through trusted publishing. For later releases, update both version values before tagging.