Metadata-Version: 2.4
Name: bnbagent-studio
Version: 0.0.1
Summary: The `bag` CLI to scaffold and deploy a two-layer bnbagent-sdk seller 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.1
Requires-Dist: boto3>=1.34
Requires-Dist: fastapi>=0.110
Requires-Dist: mcp>=1.0
Requires-Dist: python-dotenv>=1.0
Requires-Dist: rich>=13.0
Requires-Dist: tomlkit>=0.13
Requires-Dist: uvicorn>=0.30
Description-Content-Type: text/markdown

# 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](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/least-privilege-iam.md),
> [policy JSON](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/guides/iam-policies.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 **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`](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 bnbagent-studio 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.

## 🚀 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](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, 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 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

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

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

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