Metadata-Version: 2.4
Name: bnbagent-studio
Version: 0.0.3
Summary: The `bag` CLI to scaffold and deploy a bnbagent-sdk seller agent on BNB Chain.
Project-URL: Homepage, https://github.com/bnb-chain/bnbagent-studio
Project-URL: Repository, https://github.com/bnb-chain/bnbagent-studio
Author: BNB Chain Studio
License-Expression: Apache-2.0
Keywords: agent,blockchain,bnb,cli,erc-8004,erc-8183,x402
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: bnbagent-studio-core==0.0.3
Requires-Dist: boto3>=1.34
Requires-Dist: fastapi>=0.110
Requires-Dist: mcp>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: tomlkit>=0.13
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: a2a-sdk<1.0,>=0.3; extra == 'dev'
Requires-Dist: google-adk>=0.1; extra == 'dev'
Requires-Dist: litellm>=1.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/agentcore-deploy-iam.md),
> [policy JSON](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/agentcore-deploy-iam.md))
> are **reference configurations provided AS IS** — you remain responsible for
> scoping, costs, and security. Full terms:
> [DISCLAIMER.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/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`](https://pypi.org/project/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`](https://pypi.org/project/bnbagent/) SDK protocol layer.

v1 is **seller-only**. Buyer product flows, KMS/remote signing, and multi-chain
support are on the [roadmap](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/roadmap.md)
for a later release.

## Installation

```bash
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:

```bash
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](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md).

### 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

```bash
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.

```bash
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:

```bash
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

```bash
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.

```bash
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](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md).

## 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](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/design/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`](https://pypi.org/project/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](https://github.com/bnb-chain/bnbagent-studio)
- [User Guide](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/user-guide.md) — full install → skills → Claude Code → `bag dev` walkthrough
- [CLI / recipe / MCP reference](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/reference.md)
- [Architecture](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/design/architecture.md)
- [Roadmap](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/roadmap.md) — what's shipped and what's deferred

## License

Apache-2.0.
