Skip to content

migration.md

Latest commit

 

History

History
350 lines (255 loc) · 17.5 KB

migration.md

File metadata and controls

350 lines (255 loc) · 17.5 KB

Migration Guide: openclaw-acp → acp-cli

This guide covers migrating from the old openclaw-acp CLI to the new acp-cli (powered by acp-node-v2). The new CLI introduces on-chain job management with USDC escrow, SSE-based event streaming, and keychain-secured authentication.

Authentication

The new CLI replaces API key-based auth with browser-based OAuth and stores tokens securely in your OS keychain.

Old (openclaw-acp) New (acp-cli)
acp setup — interactive setup wizard (login + agent + token) acp configure — browser OAuth, tokens stored in OS keychain
acp login — re-authenticate expired session Automatic token refresh via keychain (no manual re-auth)
acp whoami — show current agent info acp agent whoami — show details of the currently active agent

What changed

  • No more config.json API keys. Authentication tokens are stored in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager).
  • No more acp setup wizard. Run acp configure to authenticate, then use acp agent commands separately.
  • Sessions are automatic. The CLI handles token refresh transparently.

Agent Management

Old (openclaw-acp) New (acp-cli)
acp agent create <name> acp agent create (interactive) or acp agent create --name <n> --description <d>
acp agent switch <name> acp agent use (interactive) or acp agent use --agent-id <id>
acp agent list acp agent list --page <n> --page-size <n>
N/A acp agent add-signer or acp agent add-signer --agent-id <id> (new)

What changed

  • Agent creation supports flags. Use --name, --description, and --image to skip interactive prompts. Omit flags to be prompted interactively.
  • switch is now use. Pass --agent-id for non-interactive use, or omit to pick from an interactive list.
  • Pagination support. agent list now supports --page and --page-size flags.
  • New: add-signer. Generates a P256 key pair, displays the public key for verification, and opens a browser URL for you to approve the signer on the UI. The CLI polls until approval is confirmed (5-minute timeout). Private keys are only stored in your OS keychain after successful approval. Pass --agent-id to skip the interactive picker.

Client Flow

The client flow has changed significantly. Jobs are now on-chain with explicit funding, evaluation, and settlement steps.

Old flow

acp browse "query" → acp job create <wallet> <offering> → acp job status <id>

New flow

acp browse "query" → acp client create-job --offering → acp client fund → ... → acp client complete/reject
Old (openclaw-acp) New (acp-cli)
acp browse <query> acp browse [query] --chain-ids <ids> --sort-by <fields> --top-k <n> --online <status>
acp job create <wallet> <offering> acp client create-job --provider <addr> --offering <json> --requirements <json>
(manual job creation) acp client create-job --provider <addr> --description <text>
(payment was implicit) acp client fund --job-id <id> --amount <usdc>
N/A acp client complete --job-id <id> --reason <text>
N/A acp client reject --job-id <id> --reason <text>
acp job status <id> acp job history --job-id <id> --chain-id <id>
acp job active / acp job completed acp job list (v2 only) / acp job list --legacy / acp job list --all

What changed

  • Explicit escrow funding. After creating a job, you must fund it with client fund. USDC is held in escrow until the job is completed or rejected.
  • Evaluator role. Jobs now have a client, provider, and evaluator. The evaluator (defaults to client) approves or rejects deliverables.
  • complete / reject replace automatic settlement. You explicitly approve or reject the deliverable, which triggers escrow release or refund.
  • Multi-chain support. Use --chain-id to specify which chain (default: 8453 Base mainnet).
  • client create-job options:
    • --provider <address> — provider wallet address (required)
    • --description <text> — job description (required)
    • --evaluator <address> — evaluator address (defaults to your wallet)
    • --chain-id <id> — chain ID (default: 8453)
    • --expired-in <seconds> — expiry time (default: 3600)
    • --hook <address> — custom settlement hook
    • --fund-transfer — use fund transfer hook

Provider Flow

The provider flow has changed from a local daemon model to an event-driven model.

Old flow

acp sell init <name> → edit handlers.ts → acp sell create <name> → acp serve start

New flow

acp events listen → acp provider set-budget → acp provider submit
Old (openclaw-acp) New (acp-cli)
acp sell init <name> acp offering create (interactive) or with flags: --name, --description, --price-type, --price-value, --sla-minutes, --requirements, --deliverable, etc.
acp sell create <name> acp offering create
acp sell delete <name> acp offering delete or acp offering delete --offering-id <id> --force
acp sell list acp offering list
acp sell inspect <name> acp offering list (shows full details including requirements/deliverable schemas)
acp sell resource init <name> acp resource create (interactive or with flags: --name, --description, --url, --params)
acp sell resource create <name> acp resource create
acp sell resource delete <name> acp resource delete
N/A acp resource list (new — list all resources for active agent)
N/A acp resource update (new — update an existing resource)
acp serve start/stop/status/logs Replaced by acp events listen + acp events drain
N/A acp provider set-budget --job-id <id> --amount <usdc>
N/A acp provider set-budget-with-fund-request --job-id <id> --amount <usdc> --transfer-amount <usdc> --destination <addr>
N/A acp provider submit --job-id <id> --deliverable <text>

What changed

  • Resource management is now under acp resource. The old sell resource init, sell resource create, and sell resource delete commands are replaced by acp resource create, acp resource update, acp resource delete, and acp resource list. Each resource has a name, description, URL, and a params JSON schema (validated via AJV). No more local resources.json scaffolding — resources are managed directly via the CLI.
  • Offering management is now under acp offering. The old sell init, sell create, sell delete, and sell list commands are replaced by acp offering create, acp offering update, acp offering delete, and acp offering list. All offering commands support non-interactive flag alternatives (e.g., --name, --offering-id, --force) for agent automation. Requirements and deliverable can be a plain string description or a JSON schema object — when a JSON schema is provided, it is validated via AJV at creation time, and client requirement data is validated against it during job creation.
  • No more handlers.ts or provider daemon. The old acp serve start ran a background daemon that auto-executed handlers.ts logic (validateRequirements → requestPayment → executeJob). In the new system, requirement schema validation is handled by the SDK at job creation time (client-side), and the provider agent reviews the requirement message before proposing a budget. For LLM-based agents this is a natural fit — the agent reads the requirements, decides if it can fulfill the job, proposes a budget, does the work, and submits. No code scaffolding needed. For developers with complex programmatic handlers (API calls, on-chain transactions), that logic needs to move into whatever agent or script consumes events from acp events listen.
  • Requirement data from clients. When a client creates a job from one of your offerings, their requirement data arrives as the first message in the job with contentType: "requirement". You'll see it in the event stream from acp events listen, or retrieve it with acp job history --job-id <id> --chain-id <chain>. Parse the message's content field (JSON string) to access the client's requirements. If your offering defined a JSON schema for requirements, the data was already validated against it by the SDK at job creation time.
  • Budget reflects offering price. Providers propose a budget with provider set-budget. The amount should match the priceValue from your offering (acp offering list to check) — this is the price the client saw when they chose your offering. The client then funds the job if they agree.
  • Fund requests. Sellers can request immediate fund transfers as part of budget negotiation using provider set-budget-with-fund-request.
  • Deliverable submission. Use provider submit to submit work. The --deliverable flag accepts text, URLs, or hashes.

Events & Messaging (New)

The new CLI introduces real-time event streaming and job room messaging — designed for agent orchestration.

Event Streaming

# Stream all job events as JSONL (long-running)
acp events listen

# Listen for legacy events only
acp events listen --legacy

# Listen for both v2 and legacy events
acp events listen --all

# By default, only v2 events are streamed

# Stream events for a specific job
acp events listen --job-id <id>

# Write events to a file
acp events listen --output events.jsonl

# Drain events from a file (atomic batch read)
acp events drain --file events.jsonl --limit 10

Each event includes: jobId, chainId, status, roles, availableTools, and full event details.

Messaging

# Send a message in a job room
acp message send --job-id <id> --chain-id <id> --content "Hello"

# With content type
acp message send --job-id <id> --chain-id <id> --content "..." --content-type proposal

Content types: text, proposal, deliverable, structured.

Wallet

Old (openclaw-acp) New (acp-cli)
acp wallet address acp wallet address
N/A acp wallet sign-message --message <text> --chain-id <id> (new)
N/A acp wallet sign-typed-data --data <json> --chain-id <id> (new)
acp wallet balance acp wallet balance --chain-id <id>
acp wallet topup acp wallet topup --chain-id <id>

Not Yet Supported

The following features from the old CLI are not yet available in acp-cli. They are planned for future releases unless noted otherwise.

Feature Old Commands Status
Bounty system bounty create/poll/select/list/status/cleanup Coming later
Offering management sell init/create/delete/list/inspect Available: acp offering create/list/update/delete for provider-side CRUD. browse to discover offerings, client create-job --offering to create jobs from them.
Provider daemon serve start/stop/status/logs Replaced by events listen (see below)
Token management token launch/info Available: acp agent tokenize — tokenize an agent on a blockchain.
Profile management profile show/update Not yet supported
Wallet balance/topup wallet balance/topup Available: acp wallet balance --chain-id <id> and acp wallet topup.
Resource management sell resource init/create/delete Available: acp resource create/list/update/delete.
Resource query resource query <url> Not yet supported
Identity check whoami Available: acp agent whoami — show details of the currently active agent.

Why There's No Provider Daemon

The old CLI had acp serve start — a background daemon that polled for incoming jobs and ran your handlers.ts logic automatically. The new CLI deliberately replaces this with event streaming primitives (events listen + events drain). Here's why:

  1. Negotiation requires judgment. The new protocol has a multi-step lifecycle (set-budget → fund → submit → complete/reject). Each step is a decision point — what budget to propose, whether to accept a job, when a deliverable is ready. A static handler can't make these calls; an intelligent agent can.

  2. events listen already is the long-running process. It streams job events as NDJSON with an availableTools field on each event, telling the consumer exactly what actions are valid next. This is the input layer a daemon would need — but it leaves the decision layer to you.

  3. Your agent is the daemon. Whether it's an LLM loop (Claude Code consuming events via SKILL.md), a custom script, or a human at the terminal — the consumer of events listen decides how to respond. The CLI provides the primitives; the agent provides the intelligence.

  4. The old model was too rigid. Hardcoded handlers couldn't adapt to context, negotiate prices, or handle edge cases. The new model treats the provider as a first-class agent that participates in a conversation, not a function that runs on a trigger.

If you need a starting point, the typical provider agent loop looks like:

# Terminal 1: stream events to a file
acp events listen --output events.jsonl

# Terminal 2 (or your agent loop): drain and process
acp events drain --file events.jsonl --limit 10
# → inspect events, decide actions
acp provider set-budget --job-id <id> --amount 5 --chain-id 8453
# → later, after client funds
acp provider submit --job-id <id> --deliverable "https://..." --chain-id 8453

Key Architectural Differences

Aspect Old New
Job lifecycle Off-chain, managed by ACP API On-chain with USDC escrow
Roles Implicit client/provider Explicit client, provider, evaluator
Payment Handled by platform USDC escrow — fund, release, or refund
Auth API key in config.json Browser OAuth + OS keychain + P256 signers
Provider model Local daemon auto-handles jobs Event-driven — listen, respond, submit
Event handling Polling (bounty poll, job status) SSE streaming (events listen)
Chain support Single chain Multi-chain (--chain-id flag)
Output format Human-readable + --json Human-readable + --json (unchanged)

Migrating a Legacy Agent to ACP SDK 2.0

If you have agents created with the old ACP SDK (v1), you need to migrate them to v2. You can do this via the CLI or the web UI.

Option 1: CLI (acp agent migrate)

Migration is a two-phase process:

Phase 1 — Create the v2 agent and set up signer:

# Interactive — select from a list of legacy agents
acp agent migrate

# Or specify the agent directly
acp agent migrate --agent-id 123

This creates a new v2 agent linked to your legacy agent and runs the signer setup flow (generates a P256 key pair, opens a browser URL for approval). After this step, review migration.md prerequisites and verify your agent is ready before completing.

Phase 2 — Activate the migrated agent:

acp agent migrate --agent-id 123 --complete

This unhides the migrated agent and sets it as your active agent. The migration is now complete.

Migration statuses:

Status Meaning
PENDING Not yet started — run acp agent migrate --agent-id <id>
IN_PROGRESS Phase 1 done, signer set up — run acp agent migrate --agent-id <id> --complete
COMPLETED Already migrated — no action needed

Option 2: Web UI

Go to app.virtuals.io, navigate to the "Agents and Projects" section, and click "Upgrade" on the agent you want to migrate.

After Migration

Once migration is complete, remove the legacy openclaw-acp skill from your agent's skill configuration. It is no longer needed and may conflict with the new acp-cli.

Quick Start: Migrating a Client Agent

# 1. Authenticate
acp configure

# 2. Create or select an agent
acp agent create          # interactive
acp agent create --name "MyAgent" --description "My client agent"  # non-interactive
acp agent add-signer      # required for on-chain signing
acp agent use             # switch agents (interactive)
acp agent use --agent-id abc-123  # switch agents (non-interactive)

# 3. Find a provider and pick an offering
acp browse "data analysis" --json

# 4. Create a job from the offering and fund it
acp client create-job \
  --provider 0x... \
  --offering '<offering JSON from browse>' \
  --requirements '{"dataset": "sales_2024.csv"}' \
  --chain-id 8453
acp client fund --job-id <id> --amount 10 --chain-id 8453

# 5. Monitor progress
acp job history --job-id <id> --chain-id 8453
acp events listen --job-id <id>

# 6. Settle
acp client complete --job-id <id> --chain-id 8453 --reason "Looks good"
# or
acp client reject --job-id <id> --chain-id 8453 --reason "Incomplete"

Quick Start: Migrating a Provider Agent

# 1. Authenticate and set up agent (same as client)
acp configure
acp agent create
acp agent add-signer

# 2. Create offerings for your agent
acp offering create       # interactive
# Or non-interactive:
acp offering create --name "My Service" --description "Service description" \
  --price-type fixed --price-value 5.00 --sla-minutes 60 \
  --requirements "What you need" --deliverable "What you get" \
  --no-required-funds --no-hidden

# 3. Listen for incoming jobs
acp events listen --output events.jsonl

# 4. Process events (in your agent loop)
acp events drain --file events.jsonl

# 5. Respond to a job
acp provider set-budget --job-id <id> --amount 10 --chain-id 8453

# 6. Submit deliverable
acp provider submit --job-id <id> --deliverable "https://result.example.com/output" --chain-id 8453