bnbagent-studio-core

The agent-runtime library for bnbagent-studio — the code a deployed BNB Chain seller agent imports and runs. It wraps the bnbagent protocol SDK with studio's configuration, workflow, and safety layer so an agent can sign quotes, run ERC-8183 jobs, pay over x402, and read chain state without re-implementing any of it.

Highlights

• Wraps the bnbagent SDK (wallet / ERC-8004 / ERC-8183 / x402) with studio's opinions — studio.toml config, multi-step workflows, signing policy, and an audit log — while leaving the SDK protocol layer untouched.
• Lean runtime deps — bnbagent, web3, eth-account, httpx, tomlkit, python-dotenv. No agent framework, no web server in the base install.
• Framework- and runtime-agnostic — does NOT import ADK, LangChain, or bedrock-agentcore. Those couplings live in the CLI's emitted recipes, not here, so you can drop this into any runtime.
• What a deployed agent imports. This is the library a scaffolded agent declares as its runtime dependency; signing, settlement, and chain reads all flow through it.

⚠️ This project is under active development and may introduce breaking changes between releases. It manages wallet keys and on-chain funds: start on testnet, and use it at your own risk.

⚠️ Deploying provisions AWS resources in your own account, under IAM policies you review and apply yourself. The published policy documents (least-privilege guide, policy JSON) are reference configurations provided AS IS — you remain responsible for scoping, costs, and security. Full terms: DISCLAIMER.md (also shipped in this package as bnbagent_studio_core/DISCLAIMER.md).

Distribution & import names

• Distribution: bnbagent-studio-core
• Import package: bnbagent_studio_core

from bnbagent_studio_core import get_wallet, get_policy
from bnbagent_studio_core.erc8183 import submit_workflow, settle_workflow

Where it sits

You normally don't install this directly. It's the library half of a two-distribution split:

• bnbagent-studio-core (this package, import bnbagent_studio_core) — the runtime library.
• bnbagent-studio (import bag) — the CLI: scaffolding and recipes. It depends on this package.

Its three consumers:

1. A deployed Agent (on AWS Bedrock AgentCore) imports it at runtime to sign quotes, submit/settle ERC-8183 jobs, auto-renew LLM credit, and read chain state. Emitted agent code does from bnbagent_studio_core import ....
2. The bag CLI — shipped as the separate bnbagent-studio distribution — also imports it.
3. Rarely standalone — only when building or vendoring an agent runtime by hand.

Install

# Usual path: install the CLI, which pulls this in automatically
pip install bnbagent-studio

Install it standalone only when building or vendoring an agent runtime by hand:

pip install bnbagent-studio-core

What's inside

Modules live under bnbagent_studio_core/. The convenience surface that agent code imports is re-exported from the package root (get_wallet, get_policy, Policy, load_studio_toml, find_project_root, emit); lower-level surfaces stay reachable via their submodules.

• wallet — keystore-backed signing. get_wallet() returns a bnbagent WalletProvider (an EVMWalletProvider that enforces a SigningPolicy on every sign); ensure_keystore_materialized() writes the injected keystore to disk when the code mount is read-only. Local Keystore V3 today (KMS / remote signing deferred to v2).
• config — studio.toml loading and project discovery: load_studio_toml(), find_project_root(), find_workspace_root(), load_env().
• networks — BSC testnet/mainnet registry and the U stablecoin (United Stables, 18 decimals) token info; get_network(), plus to_raw / from_raw amount converters.
• policy — get_policy() / Policy (budget caps: per-call and daily spend limits read from studio.toml).
• erc8004 — identity: register, resolve, resolve_service, update_endpoint, update_service_endpoint, show (with AgentRecord / ResolvedService result types).
• erc8183 — commerce: a pre-configured client (get_8183_client), multi-step workflows (buy_workflow / submit_workflow / fetch_workflow / settle_workflow, plus get_job_summary), quote verification (verify_signed_job / recover_quote_signer → Verdict), and off-chain negotiation. Typed errors (JobNotFoundError, JobStateError, BudgetCapExceededError, …) are exported alongside.
• x402 — x402 micropayment buyer kernel over the SDK's hardened X402Signer (fetch_with_payment, quote_url, pay_challenge, FetchResult) gated by an X402BuyerPolicy / BudgetTracker.
• pieverse — Pieverse LLM credit layer: PieverseCreditEnsurer (budget-gated auto-renew), BudgetPolicy / PieversePolicy, key management (create_key, inspect_key, allocate, get_account_usage), SIWE login (siwe_login), and x402 top-up (topup_x402).
• tools.chain_readonly — 15 read-only on-chain query functions (wallet_info, balance_native, balance_u, agent_info, job_status, job_list, tx_status, block_info, network_info, …). Also surfaced as the CLI's MCP tools; framework-neutral.
• audit — .studio/audit-log.jsonl emission protocol for on-chain money ops: redaction (validate_no_secrets), schema (Event, SCHEMA_VERSION), and a writer (record, record_chain_op, audited_op, tail).
• storage — deliverable storage selection (local file / IPFS) via storage_provider_from_config().
• llm — framework-neutral LLM-config resolution (_resolve_provider_config() → ProviderConfig) used by emitted provider shells. Studio constructs no model object itself.

Usage

The smallest meaningful snippets — read config and a wallet, verify a signed quote. See the reference doc for the full API.

from bnbagent_studio_core import get_wallet, get_policy, load_studio_toml

cfg = load_studio_toml()           # parsed studio.toml (project root auto-discovered)
wallet = get_wallet()              # keystore-backed WalletProvider (policy enforced)
policy = get_policy()              # budget caps from [policy] in studio.toml

# Verify a counterparty's signed ERC-8183 quote before acting on it.
from bnbagent_studio_core.erc8183 import verify_signed_job

verdict = verify_signed_job(signed_job)
if verdict.ok:
    ...  # safe to submit / settle

# Read-only chain query (no signing, no key needed).
from bnbagent_studio_core.tools.chain_readonly import balance_u

print(balance_u(network="bsc-testnet"))

Dependencies & boundaries

Runtime dependencies (lean by design):

• bnbagent, web3, eth-account, httpx, tomlkit, python-dotenv (and tomli on Python < 3.11).

Boundaries:

• Framework- and runtime-agnostic. This library does NOT import ADK, LangChain, or bedrock-agentcore — those couplings live in the CLI's emitted recipes, not here.
• The SDK protocol layer stays pure. Studio's opinions wrap bnbagent; they never pollute it.

Python ≥ 3.10.

Further reading

• Main repository — overview, guides, and the bag CLI.
• Architecture — the layered design and single-agent A2A/MCP deploy model.
• Reference — CLI / recipe / MCP-tool / library reference.
• User Guide — the install → skills → Claude Code → bag dev path (for CLI end-users).

License

Apache-2.0.