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
Recommended: single AgentVendClient
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)
-
Version — Bump
versioninpyproject.tomlunder[project](PEP 440 / SemVer). Each upload must use a new version; PyPI will reject duplicates. -
Verify — Run tests (see above). Optionally run from a clean tree.
-
Build distributions — Install tooling if needed (
pip install build twine), then fromsdk-python:python -m build
This creates
dist/*.whlanddist/*.tar.gz. -
Check —
twine check dist/* -
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. -
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.