Skip to main content

AgentVend SDK (Python)

Package: agentvend-sdk (PyPI). Import: import agentvend_sdk (replaces the former agentvend-agent-sdk / agentvend_agent_sdk names).

Verify HMAC on incoming gateway requests, validate agent keys, run usage pre-flight checks, report usage, progress/completion, and poll async job status on the gateway.

Configuration

Use AgentVendClient with one API origin (scheme + host, optional port). The client uses the default AgentVend API URL layout; for details see the AgentVend documentation.

Setting Default Notes
API origin https://api.agentvend.api (AgentVendClient.DEFAULT_API_URL) Override with api_url=..., or env AGENTVEND_API_URL for staging/tests — no trailing slash required
Agent ID From env AGENTVEND_AGENT_ID, or agent_id=... Optional if Core can infer the agent from the key
Agent secret From env AGENTVEND_AGENT_SECRET, or agent_secret=... Required (Usage HMAC + Core response verification)

Progress / completion still use the full progress_url / callback_url strings from the gateway (including query params).

Constructor arguments override environment variables when both are set.

Environment variables

Variable Purpose
AGENTVEND_API_URL Optional. Overrides the default production API origin when set (staging, local stacks, tests).
AGENTVEND_AGENT_ID Agent UUID if you omit agent_id=... (optional)
AGENTVEND_AGENT_SECRET Agent secret if you omit agent_secret=... (required one way or the other)

In code, names are also available as AgentVendClient.ENV_API_URL, ENV_AGENT_ID, and ENV_AGENT_SECRET. The default base URL is AgentVendClient.DEFAULT_API_URL.

Low-level helpers

validate_agent_key, report_usage, get_request_status, and related functions remain available. They take a single base_url using the SDK’s default URL layout for AgentVend services.

More detail: AgentVend documentation.

Requirements

Python 3.10+

Install

pip install agentvend-sdk

HTTP features (validate, usage, gateway, progress):

pip install agentvend-sdk[http]

Examples

Verify inbound HMAC (agent backend)

Pass a header map (keys matched case-insensitively) and the raw body the gateway signed (same bytes as in the canonical string). Header names follow AgentVendHeaders (X-AgentVend-*). When the gateway sends X-AgentVend-Signing-Version: 2, verification uses the newer user-context suffix (no quota segment in the signed material).

Preferred: verify and read user context in one step (None if the HMAC is invalid):

from agentvend_sdk import verify_inbound_context

ctx = verify_inbound_context(agent_secret, headers, raw_body)
if ctx is not None:
    # ctx.user_id, ctx.plan, ...
    ...

The former name verify_signature_from_headers_and_get_user_context remains available as an alias of verify_inbound_context.

Or verify and read separately:

from agentvend_sdk import verify_signature_from_headers, get_user_context

if verify_signature_from_headers(agent_secret, headers, raw_body):
    ctx = get_user_context(headers)

For full control, build InboundHmacRequest with SignedUserContext and call verify_inbound_hmac(agent_secret, req).

Caller / backend HTTP APIs (single client)

from agentvend_sdk import AgentVendClient, CompletionStatus

# Default API origin is production; pass api_url=... or set AGENTVEND_API_URL only to override.
# agent_secret is required (here or via AGENTVEND_AGENT_SECRET).
client = AgentVendClient(
    agent_id=agent_id,
    agent_secret=agent_secret,
)

validation = client.validate_agent_key("bearer-token")

estimate = client.estimate_usage("bearer-token", 1.0)
if estimate is not None:
    allowed = estimate.would_allow
    status = estimate.http_status

usage_resp = client.report_usage(user_id, agent_id, 1.0)

client.send_progress_update(progress_url, request_id, "some processing info", 50)

client.send_completion(
    callback_url, request_id, CompletionStatus.COMPLETED, units=1.0, result="some result"
)

status = client.get_request_status(request_id, agent_key)
result = client.get_request_result(request_id, agent_key)

Low-level functions (explicit URLs per call)

Use these when you are not using AgentVendClient, or when you pass an explicit base_url per call.

Verify HMAC (low-level)

from agentvend_sdk import (
    AgentVendHeaders,
    verify_signature_from_headers,
    get_user_context,
)

agent_secret = "your-agent-secret"
headers = {
    "x-agentvend-signature": sig,
    "x-agentvend-timestamp": ts,
}
valid = verify_signature_from_headers(agent_secret, headers, raw_body)
if valid:
    ctx = get_user_context(headers)

Typed inbound request

from agentvend_sdk import verify_inbound_hmac, InboundHmacRequest, SignedUserContext

req = InboundHmacRequest(
    signature=sig,
    timestamp=ts,
    payload="",
    signed_user_context=SignedUserContext(
        user_id="u1",
        plan="p1",
        roles=["r1"],
        quota_remaining=10.0,
        subscription_active=False,
    ),
)
assert verify_inbound_hmac(agent_secret, req)

Validate agent key and usage estimate (low-level)

from agentvend_sdk import validate_agent_key, estimate_usage

# Pass your Core service base URL (same layout as the unified client’s Core target).
result = validate_agent_key(core_base_url, "bearer-token", "agent-secret", agent_id="agent-uuid")
est = estimate_usage(core_base_url, "bearer-token", "agent-secret", 1.0, agent_id="agent-uuid")

Report usage, progress, completion (low-level)

from agentvend_sdk import (
    CompletionStatus,
    report_usage,
    report_usage_at,
    report_progress,
    report_completion_with_result,
)

report_usage(usage_service_base_url, user_id, agent_id, 1.0, agent_secret)
report_usage_at(
    usage_service_base_url, user_id, agent_id, 1.0, agent_secret, timestamp=1700000000.0,
)
report_progress(progress_url, request_id, "stage", 50, agent_secret)
report_completion_with_result(
    callback_url, request_id, CompletionStatus.COMPLETED, agent_secret, "ok", units=1.0
)

Gateway job status / result (low-level)

from agentvend_sdk import get_request_status, get_request_result

st = get_request_status(gateway_base_url, request_id, agent_key)
res = get_request_result(gateway_base_url, request_id, agent_key)

Tests (from source)

cd sdk-python
pip install -e ".[dev,http]"
pytest

Release (PyPI)

  1. Version — Bump version in pyproject.toml under [project] (PEP 440 / SemVer). Each upload must use a new version; PyPI will reject duplicates.

  2. Verify — Run tests (see above). Optionally run from a clean tree.

  3. Build distributions — Install tooling if needed (pip install build twine), then from sdk-python:

    python -m build
    

    This creates dist/*.whl and dist/*.tar.gz.

  4. Check — twine check dist/*

  5. Upload — Use PyPI (or Test PyPI for a dry run):

    twine upload dist/*
    

    Configure credentials via ~/.pypirc, environment variables, or a trusted publisher / API token as described in PyPI’s publishing docs.

  6. Tag — Tag the Git commit that matches the released version.

Project metadata (name agentvend-sdk, license, URLs) lives in pyproject.toml.

For HMAC signing and HTTP API layout, see the AgentVend documentation.

Metadata

Release files for agentvend-sdk 0.0.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentvend-sdk 0.0.3
File Size Uploaded Provenance Actions
agentvend_sdk-0.0.3.tar.gz 23.3 kB Without provenance Details for agentvend_sdk-0.0.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentvend-sdk 0.0.3
File Interpreter ABI Platform Actions
agentvend_sdk-0.0.3-py3-none-any.whl Python 3 none any Details for agentvend_sdk-0.0.3-py3-none-any.whl

Total release size: 42.5 kB

Release files / agentvend_sdk-0.0.3.tar.gz

Download URL agentvend_sdk-0.0.3.tar.gz
Size 23.3 kB
Tags Source
SHA-256 checksum
How to use checksums
8cb8b75da1197da81ca61179a857f2cb462c36ec15c35c9fb923a87a5350b0e7
BLAKE2b-256 checksum
How to use checksums
4604ee2a83ffc565701b3bf83fe4b2bf048346e889250d69ecbffa185686a847
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Release files / agentvend_sdk-0.0.3-py3-none-any.whl

Download URL agentvend_sdk-0.0.3-py3-none-any.whl
Size 19.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
58dd300e3bc25559a67a8a19349d1c27b204174058369a858925b8451ae86f3c
BLAKE2b-256 checksum
How to use checksums
c4c3f64ff0394eb661684a3f88321ceed325bbc819ffd537c2c4f445fdc1694f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.13.11

Security for agentvend-sdk 0.0.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page