Skip to content

docs(studio): finish the Node path across the remaining pages #887

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
0xlucasliao merged 2 commits into from
Aug 25, 2026
Merged

docs(studio): finish the Node path across the remaining pages #887

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
532d462
docs(studio): finish the Node path across the remaining pages
Ang-dot Aug 23, 2026
c9fae62
docs(studio): fix bag init flags in the CLI reference
Ang-dot Aug 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 5 additions & 14 deletions docs/developer-kit/bnbchain-studio/cli-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ The `bag` CLI exposes 19 command groups. Run `bag --help` or `bag <group> --help

| Group | Purpose | Key subcommands |
|-------|---------|-----------------|
| `init` | Scaffold a two-layer workspace | `bag init <name> [--framework adk] [--runtime agentcore] [--llm-provider pieverse-llm] [--network bsc-testnet] [--no-onboard] [--ide claude-code\|cursor\|both]` |
| `init` | Scaffold a seller agent workspace | `bag init <name> [--runtime agentcore\|azure-foundry] [--llm-provider pieverse-llm] [--network bsc-testnet] [--wallet-kind evm-local\|twak\|altana] [--protocols A2A,MCP,X402] [--storage-provider local\|ipfs] [--no-onboard] [--ide claude-code\|cursor\|both]` |
| `scan` | Detect project type + manifest | `bag scan` |
| `recipe` | Print recipe code/files | `list` / `show` / `code` |
| `skills` | Install IDE skills | `list` / `install --target {claude-code,cursor,both}` / `uninstall` |
Expand Down Expand Up @@ -43,7 +43,7 @@ bag llm status --full
### Register on-chain identity

```bash
bag erc8004 register --endpoint https://my-service.example.com/apex/
bag erc8004 register --endpoint https://my-agent.example.com
bag erc8004 show
```

Expand All @@ -66,9 +66,8 @@ bag doctor

```bash
bag deploy prepare
bag deploy prepare --include-service-preflight # opt-in EC2 IAM simulation
bag deploy agent
bag deploy package # Layer B zip → dist/
bag deploy package # build the deploy artifact → dist/
bag deploy verify --endpoint https://my-service.example.com
bag deploy status
```
Expand Down Expand Up @@ -99,17 +98,9 @@ Cross-layer commands (`doctor`, `scan`, `erc8004 register`) operate on whichever

AgentCore runtime names must match `^[A-Za-z][A-Za-z0-9]{0,22}$` (no `-`, `_`, `.`). `bag doctor` validates `agentcore/agentcore.json` names and fails on violations.

## Flat imports in emitted code

Emitted `app/agent/` and `app/service/` use **flat** (top-level) imports because AgentCore runs `main.py` as a top-level module:

```python
from managed_model import X # correct
from .managed_model import X # wrong — bag doctor warns
```

## Further reference

Full capability reference: [GitHub — reference.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/docs/reference.md)
`bag --help` and `bag <group> --help` are the authoritative surface for the installed
version.

[← BNB Agent Studio overview](index.md)
18 changes: 8 additions & 10 deletions docs/developer-kit/bnbchain-studio/configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,11 @@ BNB Agent Studio projects use two config files per layer plus environment variab
| File | Sections |
|------|----------|
| `app/agent/studio.toml` | `[stack]`, `[wallet]`, `[llm.*]`, `[budget]`, `[payments.erc8183]`, `[payments.x402]`, `[network]`, `[storage]`, `[identity]`, `[deploy]` |
| `app/service/studio.toml` | `[network]`, `[agent]`, `[deploy]`, `[storage]`, `[provider]`, `[payments.erc8183]` |

### Cross-layer sync
One runtime means one `studio.toml`. Earlier versions emitted a second config for a
separate keyless service; that tier no longer exists.

Only two values legitimately live in **both** files:
### Shared values

| Field | Agent | Service | Sync mechanism |
|-------|-------|---------|----------------|
Expand Down Expand Up @@ -47,11 +47,11 @@ max_price = "1000000000000000000"
default = "bsc-testnet"
```

### Key service sections
### Deploy and rail sections

```toml
[agent]
runtime_arn = "" # filled after Layer A deploy
runtime_arn = "" # filled after deploy

[payments.erc8183]
poll_interval_seconds = 30
Expand All @@ -61,7 +61,7 @@ auto_settle = true
# address synced from wallet via bag wallet new
```

Use `bag config show`, `bag config get <key>`, and `bag config set <key> <value>` for CRUD. From workspace root, pass `--project-root app/agent` or `--project-root app/service`.
Use `bag config show`, `bag config get <key>`, and `bag config set <key> <value>` for CRUD. From workspace root, pass `--project-root app/agent`.

## Environment variables

Expand All @@ -79,11 +79,9 @@ Use `bag config show`, `bag config get <key>`, and `bag config set <key> <value>
| `STORAGE_IPFS_GATEWAY` | Deploy | IPFS gateway for deliverables |
| `STUDIO_AGENT_LOCAL_URL` | Service-only dev | Agent URL when running `bag dev --service-only` |

### Service (`app/service/.env.local`)
### Deploy-time secrets

The Service is keyless — **no wallet secrets**. It may read runtime connection vars injected at deploy time. `bag deploy package` **never** includes any `.env*` in the Service zip.

### Deploy-time secrets (Layer A)
`bag deploy package` **never** includes any `.env*` file in a deploy artifact.

| Mode | Keystore delivery |
|------|-------------------|
Expand Down
19 changes: 16 additions & 3 deletions docs/developer-kit/bnbchain-studio/demo.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,22 @@ title: BNB Agent Studio Demo

# Demo — weather-forecast seller (end to end)

This walkthrough follows the full BNB Agent Studio path for a single example: a **weather-forecast seller** on BSC testnet. You install the CLI, scaffold the agent with your AI IDE, set up a wallet, fund it, activate an LLM, run locally, negotiate a sale, register on-chain, and deploy.
!!! danger "This walkthrough is out of date — use the Quickstart instead"
This page still documents the earlier **Python, two-layer** Studio (Layer A Agent +
Layer B keyless Service, `main.py` / `service.py`, `npm i -g @aws/agentcore`). The
shipped product is a **TypeScript, single-runtime** tool: see
**[Quickstart](quickstart.md)** and [Architecture](architecture.md) for the current
flow.

It has not been rewritten because a faithful end-to-end walkthrough has to be
*executed* to be trustworthy — every command output, wallet prompt, and deploy
result verified against a real run — rather than adapted on paper. Rewriting it from
inference would produce a confident-looking guide that does not work, which is worse
than an openly flagged stale one.

Commands and behavior match the [bnbagent-studio](https://github.com/bnb-chain/bnbagent-studio) repository — see the [weather seller example](https://github.com/bnb-chain/bnbagent-studio#-example-a-weather-forecast-seller-end-to-end) in the README for the canonical reference.
Kept for now only as a record of the earlier flow's shape.

This walkthrough follows the full BNB Agent Studio path for a single example: a **weather-forecast seller** on BSC testnet. You install the CLI, scaffold the agent with your AI IDE, set up a wallet, fund it, activate an LLM, run locally, negotiate a sale, register on-chain, and deploy.

## Prerequisites

Expand Down Expand Up @@ -431,7 +444,7 @@ $ cd ~/Desktop/weather-seller/app/agent && set -a && . ./.env.local && set +a &&
| description | Weather forecasts on demand — paid via ERC-8183 |
| protocol | ERC8183 |
| endpoint | http://localhost:8003/apex/ (update after deploy) |
| registry | See [Networks & contracts](../../bnbagent-sdk/networks.md) for deployment refs |
| registry | See [Networks & contracts](../bnbagent-sdk/networks.md) for deployment refs |

Remaining items

Expand Down
164 changes: 81 additions & 83 deletions docs/developer-kit/bnbchain-studio/deployment.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,124 +4,122 @@ title: BNB Agent Studio Deployment

# Deployment

A v1 seller deploys as **two artifacts** — Layer A (Agent) to AWS Bedrock AgentCore, Layer B (Service) to EC2/Fargate. Use the bundled IDE skills (`bnbagent-studio-use-aws-agentcore`, `bnbagent-studio-deploying-service-to-ec2`) for guided deploys, or run the commands below directly.
A Studio project deploys as **one runtime** — the same process that holds the key and
serves your selected faces. There is no second keyless artifact to ship.

On-chain deployments: [apex-contracts#deployments](https://github.com/bnb-chain/apex-contracts#deployments).
Every deploy **explicitly selects a target**. A recorded deployment is only ever offered
as an explicit update; it is never used as a silent default.

## Prerequisites
All cloud lifecycle mutations are delegated to the pinned
[`@bnbagent/deploy-cli`](https://www.npmjs.com/package/@bnbagent/deploy-cli). Studio does
not shell out to `azd` or the Azure CLI, and the scaffold contains no `azure.yaml` or
`infra/`.

| Requirement | Notes |
|-------------|-------|
| AgentCore CLI | `npm i -g @aws/agentcore` (Node ≥ 20) |
| AWS account | You provision resources in your own account under IAM policies you review |
| `agentcore configure` | One-time setup — writes `agentcore/agentcore.json` |
| IAM policies | Reference configs: [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) |
!!! warning "You are provisioning real resources"
AWS and Azure deploys create resources in **your own** account, under permissions you
review. Published IAM reference policies are provided as-is — scoping, costs, and
security remain yours. Start on BSC testnet.

> Deploying provisions AWS resources in your account. Review [DISCLAIMER.md](https://github.com/bnb-chain/bnbagent-studio/blob/main/DISCLAIMER.md) before first deploy.
## The three targets

## Deploy flow
| Target | What it is | Key constraint |
| --- | --- | --- |
| `bnb` | Managed **48-hour testnet** trial | Runs in the **operator's** cloud, so signing material leaves your control. Use a throwaway wallet (`bag wallet new`) and never reuse it on mainnet. Disabled after expiry. |
| `aws` | AWS Bedrock AgentCore in your account | Keystore injected via **AWS Secrets Manager** as `WALLET_KEYSTORE_JSON` — never in the code zip. |
| `azure` | Azure AI Foundry hosted agents | **Container-only**, and **A2A scaffolds only** — `bag init` and provider selection reject an MCP entrypoint for Foundry. Secrets injected through a Foundry **CustomKeys** connection. |

```bash
bag deploy prepare # readiness sweep (BLOCKED/CRITICAL/WARNING)
bag deploy agent # Layer A → AgentCore
bag deploy package # Layer B zip → dist/<name>-service-<sha>.zip
# upload + systemd on EC2 (see deploying-service-to-ec2 skill)
bag deploy verify --endpoint <public-url> # probe layers + register ERC-8004 endpoint
bag deploy status # dashboard: liveness, inventory, cost estimate
```
## Prerequisites

| Requirement | Needed for |
| --- | --- |
| Node.js ≥ 22 | everything |
| Bun 1.3+ | any deploy |
| Corepack + pnpm 10 | the generated workspace |
| Docker | container paths only — for example a `twak` deployment, and Azure (container-only) |
| AWS CLI | **optional**; used only by the fail-open, read-only AgentCore quota check in `bag deploy prepare` |

## Layer A — Agent (AgentCore)
## Deploy flow

```bash
bag deploy agent
bag deploy prepare # readiness gates: storage, provider, tooling
bag deploy --provider bnb # or: aws | azure
bag deploy verify --provider bnb # reconcile ERC-8004 identity with the live endpoint
bag deploy status --provider bnb # liveness and inventory
```

- Thin-wraps `agentcore deploy` (run `agentcore configure` first)
- Default `--secrets-mode secretsmanager` pushes keystore to AWS Secrets Manager as `WALLET_KEYSTORE_JSON` — **never** in the CodeZip
- Testnet-only `--secrets-mode envvars` inlines secrets in `agentcore.json` — refused on mainnet
- First deploy gates on explicit IAM risk acceptance (interactive or `--accept-risk`)
- Records `runtime_arn` in `app/service/studio.toml` `[agent]` section

**Multi-environment:** pass agentcore's `--target` through: `bag deploy agent -- --target prod`. Studio records one target per workspace — deploying multiple targets overwrites recorded state.
`bag deploy prepare` gates on storage, provider, and deploy-tooling readiness. **Local
deliverable storage fails readiness by design** — switch to IPFS before deploying, since
a local path is unreachable from a deployed runtime.

**Redeploy:** every `bag deploy agent` re-runs `agentcore deploy` (CDK). First run is slow (~4–6 min); subsequent runs use cache.

### Keystore posture

The encrypted keystore lives at workspace root `.studio/wallets/`, **outside** `app/agent/` (the AgentCore codeLocation). No packaging path — including a raw `agentcore deploy` — can bundle it. At deploy, it is injected via Secrets Manager.

## Layer B — Service (EC2)
For AWS, an inbound-auth step may be required before the first deploy:

```bash
bag deploy package
bag deploy provision-cognito
```

Produces a zip rooted at `app/service/` (so `service.py` is at zip top level) plus a `.sha256` sidecar. Excludes:

- `.venv/`, `__pycache__/`, `.git/`, `.studio/`, `dist/`
- **All `.env*`** — the keyless host must not receive Agent secrets
## Operating a deployment

Hand the zip to the EC2 deploy skill. The Service reads the Agent runtime ARN from `app/service/studio.toml` `[agent].runtime_arn` and calls `InvokeAgentRuntime` for every signing operation.

**Fast redeploy:** Layer B supports code-only updates — `scp` + `systemctl restart` without full reprovision.
```bash
bag deploy status --provider aws # liveness + resource inventory
bag deploy logs --provider aws # tail runtime logs
bag deploy info --provider azure # resolved deployment details
bag deploy destroy --provider aws # teardown
```

## Readiness checks
`bag deploy --help` lists the full surface. `bag deploy agent` remains available as the
agent-scoped form.

`bag deploy prepare` runs checks including:
## Keystore posture

- `studio.toml` parseable on both layers
- AgentCore runtime name valid
- Flat imports (no package-relative imports in emitted code)
- Network and provider address sync between layers
- Legacy keystore inside `app/agent/` (warn only)
The encrypted keystore lives at the workspace root in `.studio/wallets/`, **outside**
`app/agent/` — the deploy `codeLocation`. No packaging path can bundle it into an
artifact. It reaches a deployed runtime only through the selected provider's delegated
secret channel:

Opt-in cross-layer check:
| Target | Channel |
| --- | --- |
| `aws` | AWS Secrets Manager (`WALLET_KEYSTORE_JSON`) |
| `azure` | Foundry CustomKeys connection |
| `bnb` | the operator's managed secret store — material leaves your control |

```bash
bag deploy prepare --include-service-preflight
```
An **Altana** deployment is different in kind: it sends only a budget- and time-bounded
runtime session rather than a keystore. Keep the budget and expiry tight, and renew or
revoke explicitly.

Simulates Layer B EC2 provisioning IAM actions via `iam:SimulatePrincipalPolicy` — surfaces permission issues before Agent deploy completes.
## ERC-8004 registration

## Post-deploy verification
Buyers discover your agent on-chain. `bag deploy verify --provider <target>` reconciles
the deployed endpoint with its ERC-8004 identity. The registry commands are also
available directly:

```bash
bag deploy verify --endpoint https://my-service.example.com
bag erc8004 show
```

- Probes Layer A liveness via AgentCore
- Probes Layer B `/apex/health`
- Registers the Service public URL as the ERC-8004 endpoint
## Local mirror

## Operations
`bag dev` runs the same single runtime locally:

```bash
bag deploy status # liveness + resource inventory + cost estimate
bag deploy status --no-probe # skip HTTP probes
bag deploy logs --layer agent # CloudWatch tail
bag deploy logs --layer service # SSH + journalctl
bag deploy destroy # dry-run teardown plan; --execute for Layer A only
```
| Local | Deployed |
| --- | --- |
| A2A on `:9000` | the runtime's A2A face |
| MCP on `:8000/mcp` | the runtime's MCP face (not available on Azure) |
| `/x402` on the same process | the runtime's x402 face |
| local storage path | IPFS |

`bag deploy destroy` prints Layer B teardown as `aws` CLI commands but **never** executes them — you run those manually.
## Earning after deploy

## ERC-8004 registration
Buyers fund ERC-8183 jobs or pay an x402 request. The runtime verifies payment on-chain
*before* doing paid work, submits the deliverable, and records an audit trail
(`bag audit ls`).

After deploy, buyers discover your agent via ERC-8004. `bag deploy verify` registers the endpoint, or run manually:
Settlement stays with the buyer, who chooses approve, reject, or dispute. Operator-side
settle is manual:

```bash
bag erc8004 register --endpoint https://my-service.example.com/apex/
bag erc8004 show
bag erc8183 settle <jobId>
```

## Local mirror

`bag dev` is the local mirror of the two-artifact deploy:

| Local | Deployed |
|-------|----------|
| Agent `:8080` | AgentCore runtime |
| Service `:8003` | EC2 `/apex/*` |
| `STORAGE_LOCAL_PATH` | S3 / IPFS |
---

[← BNB Agent Studio overview](index.md)
[← BNB Agent Studio overview](index.md) · [Architecture](architecture.md) · [Security](security.md)
Loading
Loading