bnbagent-studio

bag — the developer CLI, scaffolding recipes, and bundled IDE skills for vibe-coding a blockchain seller on BNB Chain: an Agent that earns $U by selling services over ERC-8004 (identity) + ERC-8183 (commerce) + x402 (payments), built on the bnbagent SDK. The scaffolded seller serves its protocol — A2A or MCP — directly on AWS Bedrock AgentCore.

You drive most of it in natural language from Claude Code (or Cursor) — the bundled skills teach your AI tool how to scaffold, run, and deploy the agent for you. It is also a complete CLI you can run by hand.

✨ Highlights

• Vibe-code a BNB Chain seller from your IDE — install the skills, then ask Claude Code to "create a BNB seller agent on testnet" and it drives the CLI for you.
• Key-isolated, single-agent deploy — one Agent on AWS Bedrock AgentCore that serves its protocol (A2A or MCP) directly and is the sole key-holder/signer; no separate service.
• Protocol choice — serve A2A or MCP (bag init --protocol), exposing negotiate + notify_funded + 15 read-only chain tools. One runtime, one signer.
• Keys never leave your machine — the encrypted keystore lives at your workspace root, outside any deploy artifact; only your own Agent ever reads it.
• Jump-ship friendly — emitted project code is yours to edit, fork, or migrate; no closed-source SaaS lock-in.
• $0 to start — the default Pieverse LLM provider activates with a zero-deposit API key; testnet funds and your own LLM key are optional.

⚠️ 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 bag/DISCLAIMER.md).

Overview

bnbagent-studio scaffolds and deploys a single seller agent on BNB Chain: one valuable Agent deployed to AWS Bedrock AgentCore that serves its protocol directly and is the sole key-holder/signer (no separate service).

• The protocol is selectable at scaffold (bag init --protocol {A2A,MCP}): A2A (serve_a2a) or MCP (FastMCP on /mcp) — one runtime, one signer.
• Both expose the same fixed-code operations — negotiate (price clamp + EIP-191 sign; no LLM) and notify_funded (verify the funded job → ACK) — plus read-only chain tools. All signing is fixed entrypoint code, never an LLM-callable tool.

This package is the dev-time tool. It imports as bag and depends on bnbagent-studio-core (import bnbagent_studio_core), the agent-runtime library that runs inside the deployed Agent — installing this package auto-pulls core. Both sit on top of the bnbagent SDK protocol layer.

v1 is seller-only. Buyer product flows, KMS/remote signing, and multi-chain support are on the roadmap for a later release.

Installation

uv tool install bnbagent-studio       # machine-wide CLI (recommended)
# or
pip install bnbagent-studio           # into the active environment
# or
uvx --from bnbagent-studio bag init my-agent  # one-shot, no install

Installing bnbagent-studio pulls in bnbagent-studio-core automatically. Verify:

bag --version
bag --help            # lists every command group

Requirements

• Python ≥ 3.10.
• Claude Code or Cursor — required to use the bundled skills (the natural-language workflow). The CLI works without them.
• The native AgentCore CLI — bag init / bag dev / bag deploy agent shell out to it. Install with npm install -g @aws/agentcore (Node ≥ 20). Make sure the npm CLI wins on PATH over any Python bedrock-agentcore-starter-toolkit shim (which -a agentcore, node --version).
• An AWS account is needed only when you deploy — never for local development.

Deploy runtimes

The Layer-A Agent deploys to AWS Bedrock AgentCore, selected at scaffold time with bag init --runtime <name> and recorded in studio.toml [stack].runtime:

Runtime	--runtime	Hosts	Native CLI	Secrets	Deploy handle
AWS Bedrock AgentCore	agentcore (default)	AgentCore runtime (CodeZip)	@aws/agentcore (npm, Node ≥ 20)	AWS Secrets Manager	runtime ARN

(An Azure AI Foundry runtime adapter is implemented but not advertised in this release.)

The selected runtime hosts the whole seller agent; there is no separate keyless Layer B service.

Deploy destinations

Orthogonal to --runtime, the deploy destination is chosen at scaffold with bag init --destination and recorded in studio.toml [deploy].destination (there is no deploy-time destination flag — bag deploy reads it):

• --destination self (default) — deploys to your own cloud via the --runtime adapter above (AgentCore). Unchanged behavior.
• --destination platform — a 48h testnet-trial sandbox on the BNB Chain managed platform (bnbagent-api), hosted in the operator's account. It forces runtime=agentcore and [network].default = bsc-testnet; bag deploy agent packages an artifact (a zip for the default evm-local wallet, a container for twak) and ships it there. Opt-in only — a trial wallet key is transmitted to the operator, so run bag wallet new for a throwaway. Manage the account/session with bag platform … (GitHub device flow, ~/.bag/session.json). See the platform-deploy guide.

🚀 Getting started

This is the canonical, beginner-friendly path: install → install skills → drive from your IDE → run the agent locally → deploy. You mostly talk to Claude Code in plain language; the studio runs the CLI for you. The full, deepest version of this walkthrough is in the User Guide.

What to prepare

• Python ≥ 3.10 and Claude Code (or Cursor).
• The native AgentCore CLI (npm install -g @aws/agentcore, Node ≥ 20).
• A wallet password you choose. bag creates a local encrypted keystore; the password lives only in your shell env as WALLET_PASSWORD and is never written to disk.
• Optional: testnet funds (tBNB + $U from a faucet) and your own LLM API key. Neither is required to start — the default Pieverse LLM provider activates with a $0 deposit.

1. Install the CLI

uv tool install bnbagent-studio       # or: pip install bnbagent-studio
bag --version                          # confirm it's on PATH

2. Install the skills into your IDE

Claude Code doesn't know the studio exists until you install the skills.

bag skills install
# On a TTY: auto-detects Claude Code / Cursor, lets you pick scope (user/project),
# and installs 10 skills (the azure-foundry skill is hidden this release), e.g.:
#   claude-code [user]: installed=10 target=~/.claude/skills

Non-interactive (CI) form:

bag skills install --target both --scope user      # Claude Code + Cursor, machine-wide
bag skills install --target cursor --scope project # Cursor only, this workspace

Then reload your IDE window so it picks up the skills. (Remove them later with bag skills uninstall.)

3. Drive it in natural language from Claude Code

Open Claude Code where you want the project to live, and just say what you want. Concrete prompts that work:

"Create a new BNB seller agent named weather-seller on testnet that sells weather forecasts."

"Start my agent and verify it works."

"Is my wallet funded? What's my $U balance?"

"Register my agent on chain so others can find it."

The skills tell Claude Code how to chain the CLI for you — it runs bag init, sets up the per-layer virtualenvs, runs bag wallet new (prompting you for WALLET_PASSWORD), runs bag doctor, and edits your project files. It stops to ask you for the wallet password, for confirmation before any real on-chain transaction, and for a faucet step if your wallet has 0 tBNB.

bag init emits a thin workspace root plus one agent sub-project, app/agent/ (the Agent and sole signer). The encrypted keystore is written to the workspace root .studio/wallets/, deliberately outside the deploy code location.

Prefer to do it by hand? bag init weather-seller runs the same onboarding on an interactive terminal — it prompts once for the wallet password, creates the keystore, zero-deposit activates Pieverse, and prints testnet faucet URLs. For a non-Pieverse provider, set the key afterward, e.g. echo "OPENROUTER_API_KEY=sk-or-..." >> weather-seller/.studio/.env.local.

4. Run the agent locally

bag dev        # from the workspace root (or app/agent/); the same runtime production uses

bag dev serves the single agent locally (sole signer, runs the LLM) and prints the local URL: A2A → the agent card at http://localhost:9000/.well-known/agent-card.json; MCP → FastMCP at http://localhost:8000/mcp.

Exercise negotiate: for A2A, send an A2A message/send with a {"skill": "negotiate", "task_description": "5-day forecast for Singapore", "terms": {"deliverables": "JSON forecast"}} data part; for MCP, call the negotiate tool. The agent prices, clamps to [min_price, max_price], then EIP-191 signs and returns the offer.

5. Deploy

When you're ready, ask Claude Code to deploy, or run it yourself. Deploy is single-artifact: the Agent goes to AWS Bedrock AgentCore and serves its protocol (A2A or MCP) directly.

agentcore configure          # once — writes agentcore/agentcore.json
bag deploy provision-cognito # emit the Cognito CDK app (you run `cdk deploy`) for inbound OAuth2
bag deploy agent             # pushes secrets to AWS Secrets Manager, then delegates
                             # to `agentcore deploy`; captures the runtime ARN
bag deploy status            # what still needs deploying
bag deploy verify            # probe + reconcile your ERC-8004 record

By default (--secrets-mode secretsmanager) the encrypted keystore is injected into the Agent via AWS Secrets Manager (WALLET_KEYSTORE_JSON) and is never bundled into the code package.

For the complete walkthrough — IDE/skill scopes, scaffold, run, and the deploy details — see the User Guide.

Direct CLI use

bag is also a full CLI you can run by hand. bag --help shows the complete surface, and bag <group> --help lists a group's subcommands. The command groups:

Group	What it does
init	Scaffold a single-agent project (app/agent/) + onboarding
skills	Install / remove the IDE skills (install / uninstall / list; --target / --scope)
install / uninstall	Deprecated aliases of bag skills install / bag skills uninstall
dev	Run the agent locally (default port matches the deploy contract: A2A :9000 / MCP :8000/mcp); same protocol entrypoint production uses (platform is unified with self-deploy)
doctor	Diagnose project + environment readiness
wallet	Local keystore: new / show / list / sign / balance / policy
erc8004	Identity: register / show / resolve / update-endpoint
erc8183	Commerce: list / buy / status / submit / fetch / settle
x402	x402 payment client helpers (quote / buy)
llm	LLM provider helpers (test / activate / status / topup / usage / list-models / rotate / allocate / auto-renew)
deploy	Deploy flow (prepare / agent / provision-cognito / verify / status / destroy / logs / fix-gitignore); destination-dispatched on [deploy].destination
platform	Managed-platform account/session ops (login / logout / whoami / agents / credit (alias trial) / token / invoke-client) — for the --destination platform 48h testnet trial
bundle	Pack an agent project + local wheels into an offline-installable tarball
scan	Detect project framework + manifest (read-only)
recipe	Emit / re-emit a single recipe layer
config	Read / write studio.toml (show / get / set / list-keys)
env	Edit .env.local idempotently (set / get)
agents	Local agent project registry (~/.bnbagent-studio/projects.toml)
budget	Opt-in auto-topup policy for the Pieverse LLM
audit	View the on-chain action audit log

bag dev — the local agent runtime

bag dev runs from the workspace root (or app/agent/) and serves the single agent by running the selected protocol entrypoint in-process by default (python main.py for A2A, python mcp_main.py for MCP; a platform project is unified with self-deploy and serves the same protocol entrypoint). A2A → the agent card at :9000; MCP → FastMCP at :8000/mcp. Use --container when you specifically want native agentcore dev image parity.

Flags: --port (default is protocol-aware: A2A 9000 / MCP 8000), --host, --reload, --project-root, --container.

🔌 MCP — a deploy protocol (peer to A2A)

There is no local MCP server command. MCP is one of the two external protocols a scaffolded seller can serve, chosen at bag init --protocol MCP (one runtime, one signer — see decisions.md). The deployed MCP runtime (mcp_main.py, FastMCP on /mcp) exposes:

• Commerce — negotiate (wallet-signed quote) and notify_funded (verify → produce the deliverable → on-chain submit, synchronously within the call; signing is fixed signing.py code, never an LLM-callable tool)
• 15 read-only chain tools — wallet/balances, network/tx, ERC-8004, ERC-8183, and pieverse_usage

bag dev on an MCP project serves it at http://localhost:<port>/mcp — connect any MCP client (e.g. npx @modelcontextprotocol/inspector). notify_funded delivers synchronously inside the tool call (AgentCore allows ~15 min; ctx.report_progress heartbeat); the runtime is stateful.

Relationship to bnbagent-studio-core

This distribution ships, under the bag import package: bag/cli, bag/mcp, bag/recipes, bag/utils, bag/skills_installer.py, and the bundled skills/.

It depends on the runtime library bnbagent-studio-core (import bnbagent_studio_core), which pip install bnbagent-studio pulls in automatically.

A deployed Agent does not install this CLI — it depends only on bnbagent-studio-core. bnbagent-studio is the dev-time tool you use to scaffold, develop, and deploy; core is the library that runs in production.

📚 Further reading

• Main repository
• User Guide — full install → skills → Claude Code → bag dev walkthrough
• CLI / recipe / MCP reference
• Architecture
• Roadmap — what's shipped and what's deferred

License

Apache-2.0.