bnbagent-studio 0.0.2

The `bag` CLI to scaffold and deploy a two-layer bnbagent-sdk seller on BNB Chain.

bnbagent-studio

bag — the developer CLI, read-only MCP server, scaffolding recipes, and bundled IDE skills for vibe-coding a two-layer 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.

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.
• Two-layer, key-isolated deploy — a private, invoke-only Agent (the sole key-holder/signer, on AWS Bedrock AgentCore) and a public, keyless Service (no key, no LLM, never signs).
• Read-only MCP — 15 chain-query tools for your IDE, with no signing and no on-chain state change by design.
• 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 two-layer seller on BNB Chain:

• Layer A — the Agent (deployed invoke-only to AWS Bedrock AgentCore): the value (LLM, memory, tools) and the sole key-holder/signer. It is invoked on an action envelope — quote / fulfill / settle. All signing is fixed entrypoint code, never an LLM-callable tool.
• Layer B — the ERC-8183 Service (deployed to EC2): a public, long-running, keyless container — a funded-job poller plus a /apex/negotiate ingress. It holds no key, runs no LLM, and never signs; it delegates every signing op to the Agent.

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 bnbagent-studio 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.

🚀 Getting started

This is the canonical, beginner-friendly path: install → install skills → drive from your IDE → run both layers 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, 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 two independent sub-projects: app/agent/ (Layer A — the Agent and sole signer) and app/service/ (Layer B — the keyless Service). 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/app/agent/.env.local.

4. Run both layers locally

bag dev        # from the workspace root (or app/agent/)

bag dev mirrors the two-artifact deploy and launches both layers by default:

• Agent on :8080 — Layer A, the sole signer, runs the LLM (POST /invocations).
• keyless Service on :8003 — Layer B, public /apex/negotiate + funded-job poller.

They're wired over STUDIO_AGENT_LOCAL_URL and share STORAGE_LOCAL_PATH for deliverable handoff. Useful flags: --agent-only / --service-only, --port / --service-port.

Health check the Service: curl localhost:8003/apex/health → {"status":"ok","keyless":true}. Then exercise the full negotiate path:

curl -X POST http://localhost:8003/apex/negotiate \
  -H 'Content-Type: application/json' \
  -d '{"task_description": "5-day forecast for Singapore",
       "terms": {"deliverables": "JSON forecast", "quality_standards": "hourly granularity"}}'
# → the Service relays the Agent's signed offer
#   (the Agent prices, clamps to [min_price, max_price], then EIP-191 signs)

5. Deploy

When you're ready, ask Claude Code to deploy, or run it yourself. Deploy is two-artifact: the Agent goes to AWS Bedrock AgentCore (invoke-only), the keyless Service goes to an EC2 systemd host.

agentcore configure          # once — writes agentcore/agentcore.json
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 --endpoint <service-url>   # 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. The keyless Service never holds the key. For the EC2 Service deploy steps, ask Claude Code to load the bnbagent-studio-deploying-service-to-ec2 skill.

For the complete walkthrough — IDE/skill scopes, per-project MCP wiring, the manual two-terminal 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 two-layer agent project (app/agent/ + app/service/) + 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 BOTH layers locally (Agent :8080 + keyless Service :8003)
doctor	Diagnose project + environment readiness across both sub-projects
wallet	Local keystore: new / show / list / sign / balance / policy
erc8004	Identity: register / show / resolve / update-endpoint
erc8183	Commerce: publish / 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	Two-layer deploy flow (prepare / agent / package / verify / status / destroy / logs / fix-gitignore / fix-a2a-disable)
mcp	Run the read-only MCP server (bag mcp serve / bag mcp tools)
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 two-service mirror

bag dev runs from the workspace root (or app/agent/) and launches both layers by default:

• Agent on :8080 — Layer A, the sole signer, runs the LLM (POST /invocations).
• keyless Service on :8003 — Layer B, public /apex/negotiate + funded-job poller.

Flags: --agent-only / --service-only, --port / --service-port, --reload.

🔌 MCP server

bag mcp serve runs a read-only MCP server over stdio — this is what an IDE launches. It exposes 15 read-only chain tools:

• Wallet & balances — wallet_info, wallet_list, wallet_address, balance_native, balance_u
• Network & tx — network_info, tx_status, block_info, contract_call_view
• ERC-8004 identity — agent_info, agent_by_address
• ERC-8183 commerce — job_status, job_list, job_count
• LLM usage — pieverse_usage

Read-only by design: no signing, no on-chain state change. List the tools with bag mcp tools. Wire one MCP entry per project so your AI tool reads the right keystore + studio.toml — see the User Guide. Only stdio transport is supported in v1.

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.