diff --git a/docs/developer-kit/bnbchain-studio/cli-reference.md b/docs/developer-kit/bnbchain-studio/cli-reference.md index 624729170e..c81d77d554 100644 --- a/docs/developer-kit/bnbchain-studio/cli-reference.md +++ b/docs/developer-kit/bnbchain-studio/cli-reference.md @@ -10,7 +10,7 @@ The `bag` CLI exposes 19 command groups. Run `bag --help` or `bag --help | Group | Purpose | Key subcommands | |-------|---------|-----------------| -| `init` | Scaffold a two-layer workspace | `bag init [--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 [--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` | @@ -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 ``` @@ -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 ``` @@ -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 --help` are the authoritative surface for the installed +version. [← BNB Agent Studio overview](index.md) diff --git a/docs/developer-kit/bnbchain-studio/configuration.md b/docs/developer-kit/bnbchain-studio/configuration.md index 84443f6ffb..f43ab6c641 100644 --- a/docs/developer-kit/bnbchain-studio/configuration.md +++ b/docs/developer-kit/bnbchain-studio/configuration.md @@ -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 | |-------|-------|---------|----------------| @@ -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 @@ -61,7 +61,7 @@ auto_settle = true # address synced from wallet via bag wallet new ``` -Use `bag config show`, `bag config get `, and `bag config set ` for CRUD. From workspace root, pass `--project-root app/agent` or `--project-root app/service`. +Use `bag config show`, `bag config get `, and `bag config set ` for CRUD. From workspace root, pass `--project-root app/agent`. ## Environment variables @@ -79,11 +79,9 @@ Use `bag config show`, `bag config get `, and `bag config set | `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 | |------|-------------------| diff --git a/docs/developer-kit/bnbchain-studio/demo.md b/docs/developer-kit/bnbchain-studio/demo.md index 7a37417a99..bc71c26e6d 100644 --- a/docs/developer-kit/bnbchain-studio/demo.md +++ b/docs/developer-kit/bnbchain-studio/demo.md @@ -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 @@ -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 diff --git a/docs/developer-kit/bnbchain-studio/deployment.md b/docs/developer-kit/bnbchain-studio/deployment.md index fdbee45f41..3f5aeea012 100644 --- a/docs/developer-kit/bnbchain-studio/deployment.md +++ b/docs/developer-kit/bnbchain-studio/deployment.md @@ -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/-service-.zip -# upload + systemd on EC2 (see deploying-service-to-ec2 skill) -bag deploy verify --endpoint # 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 ` 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 ``` -## 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) diff --git a/docs/developer-kit/bnbchain-studio/troubleshooting.md b/docs/developer-kit/bnbchain-studio/troubleshooting.md index 9441100173..58ab1fab61 100644 --- a/docs/developer-kit/bnbchain-studio/troubleshooting.md +++ b/docs/developer-kit/bnbchain-studio/troubleshooting.md @@ -14,11 +14,11 @@ bag doctor ### `bag doctor` reports network drift -`[network].default` must agree between `app/agent/studio.toml` and `app/service/studio.toml`. +`[network].default` in `app/agent/studio.toml` must match the network your wallet and +deploy target expect. ```bash bag config set network.default bsc-testnet --project-root app/agent -# mirrors to service automatically ``` ### Provider address mismatch @@ -30,37 +30,30 @@ bag wallet show bag doctor # re-check sync ``` -### Package-relative imports +### Generated code will not build -AgentCore runs `main.py` as a top-level module. Use flat imports: - -```python -from signing import quote # correct -from .signing import quote # wrong -``` - -`bag doctor` warns on remaining package-relative imports. +The generated project is a pnpm workspace. Make sure Corepack and pnpm 10 are active, +then reinstall from the workspace root before re-running `bag dev`. ### AgentCore runtime name invalid Runtime names must match `^[A-Za-z][A-Za-z0-9]{0,22}$`. No hyphens, underscores, or dots. Re-run `agentcore configure` with a valid name if `bag doctor` fails. -### `agentcore` not found or wrong binary +### Wrong Node version ```bash -which -a agentcore -node --version # must be ≥ 20 -npm install -g @aws/agentcore +node --version # must be >= 22 ``` -Ensure the npm CLI wins on PATH over any Python shim. +The AWS CLI is **not** required to deploy — it is used only by the fail-open, read-only +AgentCore quota check in `bag deploy prepare`. -### Service not picking up funded jobs +### Funded jobs are not being picked up -1. Confirm both layers are running: `bag dev` or deployed equivalents -2. Check `app/service/studio.toml` `[agent].runtime_arn` is set after Layer A deploy -3. Verify `[payments.erc8183].poll_interval_seconds` and `auto_settle` -4. Probe health: `curl /apex/health` +1. Confirm the runtime is up: `bag dev`, or `bag deploy status --provider ` +2. Verify `[payments.erc8183]` in `app/agent/studio.toml` +3. Probe the runtime: `curl /readiness` +4. Remember `settle` is manual — `bag erc8183 settle ` ### `PolicyViolation` / `X402PolicyError` at runtime