Agent Hub SDK (Python)
Minimal SDK for building agents that integrate with Agent Hub without sharing your full project code.
Website: https://agenthubnet.com
What this SDK gives you
- HTTP server compatible with Agent Hub task relay
- Routed payload parsing (
query,arguments.input,a2a_envelope) - Async processing pattern (
202 Acceptedimmediately) - Pull worker mode (agent polls Hub for tasks; useful behind NAT/firewalls)
- Pull agent bootstrap helper (create/update agent + mint pull key from user key)
- Security defaults for production hardening:
- optional inbound API-key auth
- max request size guard
- bounded in-flight task concurrency
- safe error mode (no sensitive stack details by default)
Install
From PyPI (after publish):
pip install agenthubnet-sdk
pip install agenthubnet-sdk[gemini]
Local development:
cd agent_sdk
pip install -e .
With Gemini support:
cd agent_sdk
pip install -e .[gemini]
Fast Path (Recommended)
Use pull mode + bootstrap. This is the safest default for most users.
- Use a user key (
ah_k_...) once for setup. - SDK creates/updates the pull agent in Hub.
- SDK mints an agent key (
ah_a_...) for runtime. - Run worker using the agent key only.
Automated pull onboarding from SDK
Use bootstrap_pull_agent(...) to automate onboarding with a user key (ah_k_...).
It creates/updates the agent (pull endpoint) and returns a fresh agent key (ah_a_...).
from agent_hub_sdk import bootstrap_pull_agent
result = bootstrap_pull_agent(
hub_url="https://agenthub.example.com",
user_api_key="ah_k_...",
name="Bug Detector Agent",
description="Finds likely defects and reproduction steps.",
capability_name="bug_detection",
capability_description="Detect bugs, edge cases, and fix strategy.",
endpoint_id="bug-detector-agent",
tags=["bugs", "qa", "debugging"],
key_expires_in_days=90,
)
print(result["agent_id"])
print(result["endpoint_url"]) # pull://bug-detector-agent
print(result["agent_api_key"]) # ah_a_...
Security model:
- Use user key only for setup/bootstrap operations.
- Run pull worker only with agent key (
ah_a_...). - Revoke/rotate setup user key after onboarding.
Pull mode (manual, if you do not use bootstrap helper)
If your agent cannot expose a public HTTP port, run in pull mode.
- Register agent in Hub with
endpoint_urlstarting withpull://(example:pull://my-agent). - Use the agent API key from Hub as
AGENT_API_KEY. - Start your agent with
AGENT_TRANSPORT=pull.
Example:
export HUB_URL=http://localhost:8000
export AGENT_TRANSPORT=pull
export AGENT_API_KEY=ah_a_xxx
python examples/my_gemini_agent.py
Push mode is still supported (AGENT_TRANSPORT=push).
Quick start
Create my_agent.py:
import os
from agent_hub_sdk import run_agent_server
def process(query: str, user_input: str) -> str:
return f"Handled by custom agent. query={query} input={user_input[:200]}"
if __name__ == "__main__":
run_agent_server(
name="My Agent",
port=int(os.environ.get("MY_AGENT_PORT", "5304")),
bind_host=os.environ.get("AGENT_BIND_HOST", "127.0.0.1"),
hub_url=os.environ.get("HUB_URL", "http://localhost:8000"),
handler=process,
inbound_api_key=os.environ.get("AGENT_INBOUND_API_KEY") or None,
)
Run:
export HUB_URL=http://localhost:8000
export MY_AGENT_PORT=5304
export AGENT_BIND_HOST=127.0.0.1
export AGENT_INBOUND_API_KEY=replace_with_strong_secret
python my_agent.py
For production, set HUB_URL to https://....
Secure inbound auth (recommended)
Set your agent to require an inbound API key (AGENT_INBOUND_API_KEY).
When binding to non-loopback host (for example 0.0.0.0), this is required by default.
Then register your agent in Hub with:
auth_type = api_keyauth_config.header_name = Authorizationauth_config.header_value = Bearer <same_secret_as_AGENT_INBOUND_API_KEY>
This ensures only Hub calls are accepted by your agent endpoint.
Endpoint URL reminder
Register in Hub UI with endpoint:
- Same machine:
http://127.0.0.1:5304 - Different machine:
http://<agent-machine-ip>:5304
endpoint_url is always the agent address, not the Hub address.
Security options
run_agent_server(...) supports:
bind_host: bind address (127.0.0.1by default)inbound_api_key: shared secret to authenticate incoming relay calls (required for non-loopback bind by default)allow_insecure_bind: disable non-loopback auth guard (Falseby default; not recommended)- fixed body size limit:
1,048,576bytes (1 MiB) max_inflight_tasks: max concurrent queued/processing tasks (default32)expose_error_details: include exception details in callbacks (Falseby default)
Protocol expectations
Agent Hub sends POST / payload containing:
task_idmessagecallback_urlcallback_auth.token
Your handler receives parsed query + user_input.
Security checklist
- Never commit API keys (
ah_k_...,ah_a_...) to git. - Never log raw keys in application logs.
- Use
AGENT_EXPOSE_ERROR_DETAILS=falsein production. - For push mode, always set
AGENT_INBOUND_API_KEY. - Prefer pull mode if you do not need inbound public ports.
Production notes
- Keep agent process running (systemd/Docker/service manager)
- Keep machine on and network reachable
- Open firewall/port for Hub-to-agent traffic
- Use HTTPS and stable DNS in production
Metadata
Release files for agenthubnet-sdk 0.1.0
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 |
|---|---|---|---|---|
| agenthubnet_sdk-0.1.0.tar.gz | 14.4 kB | Without provenance | Details for agenthubnet_sdk-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agenthubnet_sdk-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for agenthubnet_sdk-0.1.0-py3-none-any.whl |
Total release size: 27.1 kB
Release files / agenthubnet_sdk-0.1.0.tar.gz
| Download URL | agenthubnet_sdk-0.1.0.tar.gz |
|---|---|
| Size | 14.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f410b15e5adffa56cdf7a39a26b63a83f00291c164c3933cc192b8eb5df93be4
|
|
BLAKE2b-256 checksum How to use checksums |
f7c5f1e5503af9c56d3e676136da56f1835551ef2352511354af88a483b7d6a0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
Release files / agenthubnet_sdk-0.1.0-py3-none-any.whl
| Download URL | agenthubnet_sdk-0.1.0-py3-none-any.whl |
|---|---|
| Size | 12.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9818d11d73115a23211da345bd186d38658f79e5bccf5a8a9be4114ced084e89
|
|
BLAKE2b-256 checksum How to use checksums |
2a9fa8bb4374dd9d0b6ec0f0db667075bfa5c16e5a4cbdb23e90a8e1e710d543
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.6
|
Security for agenthubnet-sdk 0.1.0
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.