From f7cb6724c50e238b8af6194615866af9ec0a5b83 Mon Sep 17 00:00:00 2001 From: eric-brown Date: Thu, 19 Feb 2026 01:33:53 -0700 Subject: [PATCH] deepen ai-agent docs and reorganize for flow builders follow --- docs/ai-agents/core-concepts/agent-apps.mdx | 63 +++++++++++-- .../core-concepts/agent-frameworks.mdx | 51 ++++++++-- .../identity-verification-auth.mdx | 70 +++++++++++--- .../payments-and-transactions.mdx | 93 +++++++++++++++---- docs/ai-agents/core-concepts/wallets.mdx | 57 +++++++++--- docs/ai-agents/index.mdx | 45 +++++++++ docs/ai-agents/introduction/index.mdx | 44 --------- docs/docs.json | 12 ++- 8 files changed, 325 insertions(+), 110 deletions(-) create mode 100644 docs/ai-agents/index.mdx delete mode 100644 docs/ai-agents/introduction/index.mdx diff --git a/docs/ai-agents/core-concepts/agent-apps.mdx b/docs/ai-agents/core-concepts/agent-apps.mdx index d9071ddc8..d41d1acb1 100644 --- a/docs/ai-agents/core-concepts/agent-apps.mdx +++ b/docs/ai-agents/core-concepts/agent-apps.mdx @@ -1,32 +1,75 @@ --- title: "Agent Apps" -description: "Build services for agents and make your app discoverable" +description: "Build services designed for agents and make your app discoverable" --- + import { GithubRepoCard } from "/snippets/GithubRepoCard.mdx"; -Agent Apps are services built with agents as the primary user. This page covers how to build for agents and how to make your app discoverable so agents can find and interact with it. +An agent app is a service built with AI agents as the primary user. Instead of rendering a visual UI for humans to click through, an agent app exposes structured endpoints that agents can discover, understand, and call programmatically. +## How agents discover your app + +Agents find your service through a `SKILL.md` file hosted at a well-known URL path: `/.well-known/SKILL.md`. If you've worked with web development, this pattern may be familiar: + +- Apple uses `/.well-known/apple-app-site-association` for universal links +- SSL certificate authorities use `/.well-known/acme-challenge/` to verify domain ownership +- OAuth uses `/.well-known/openid-configuration` for discovery + +The `/.well-known/` convention is a standard way to host metadata at a predictable location. For agent apps, your `SKILL.md` file lives there so any agent can find it by checking `yourdomain.com/.well-known/SKILL.md`. + +### What goes in a SKILL.md + +Your `SKILL.md` file describes what your app does, what endpoints are available, and how to use them. Here's a conceptual template: + +```markdown Title "SKILL.md template" +# Your App Name -## How agents interact with apps +## Description +What your app does, in plain language. -Agents discover services via a `SKILL.md` file hosted at `/.well-known/SKILL.md`. This file describes what your app does, what endpoints are available, and how to use them. When an agent reads your `SKILL.md`, it understands how to interact with your service. +## Endpoints -Build your app with this in mind: expose clear endpoints, document them in `SKILL.md`, and let agents find you. +### POST /api/action-name +- **Description:** What this endpoint does +- **Inputs:** What parameters it expects +- **Output:** What it returns +- **Payment:** Whether it requires x402 payment and the cost -## Building trust with humans +## Authentication +How agents should authenticate (e.g., SIWA, API key, x402). +``` -Agent Apps serve agents, but humans own those agents. Be explicit about what actions your app takes and what transactions it may execute - if a human can't quickly understand what your app does, they won't let their agent use it. +When an agent reads your `SKILL.md`, it understands what your service offers and how to interact with it, no human in the loop required. + +## Designing for agent users + +Agents aren't humans. They don't browse, guess, or interpret visual cues. When building an agent app, follow these guidelines: + +- **Document side effects**: if an endpoint transfers funds, modifies state, or triggers external actions, say so explicitly in your `SKILL.md` +- **Return structured JSON**: agents parse JSON, not HTML. Every endpoint should return well-structured JSON responses with consistent field names +- **Support x402 for paid access**: if your service costs money, implement the [x402 protocol](/ai-agents/core-concepts/payments-and-transactions) so agents can pay per request without pre-registration +- **Use clear error responses**: return descriptive error messages with appropriate HTTP status codes so agents can handle failures gracefully ## Making your app discoverable -Register your app via ERC-8004 so agents can find it. The same registry used for agent identity is used for app discovery. Once registered, agents can query the registry, find your service, and read your `SKILL.md` to understand how to interact. +Host your `SKILL.md` at `/.well-known/SKILL.md` and register your app in the [ERC-8004 registry](/ai-agents/core-concepts/identity-verification-auth). The same registry used for agent identity is used for app discovery. Once registered, agents can query the registry, find your service, and read your `SKILL.md` to understand how to interact with it. + + +The Agent App Framework is experimental. APIs and conventions may change as the standard evolves. + + + + +## Continue exploring - \ No newline at end of file + + Return to the AI agents overview for a summary of all components. + diff --git a/docs/ai-agents/core-concepts/agent-frameworks.mdx b/docs/ai-agents/core-concepts/agent-frameworks.mdx index 73e12920c..5fac08b50 100644 --- a/docs/ai-agents/core-concepts/agent-frameworks.mdx +++ b/docs/ai-agents/core-concepts/agent-frameworks.mdx @@ -1,30 +1,61 @@ --- title: "Frameworks" -description: "Tools for building and running agents on Base" +description: "Choose the right framework for building and running AI agents on Base" --- -Build your own agent or use an existing service to get started. +Your first decision when building an AI agent on Base is choosing a framework. This determines how you write your agent's logic, where it runs, and how much infrastructure you manage yourself. -## Agent SDK +## Comparing your options + +| | BANKR | OpenClaw | Agent SDK | +|---|---|---|---| +| **What it is** | A managed Agent API, plus skill and wallet plugins for OpenClaw | An open-source personal AI assistant that runs across multiple channels (Discord, Telegram, web) | A developer toolkit for building custom agents with full control over behavior and integrations | +| **Language** | Any (REST API) for Agent API; TypeScript for OpenClaw plugins | TypeScript | TypeScript / Python | +| **Hosting** | Agent API is managed by BANKR; OpenClaw plugins run in your self-hosted agent | Self-hosted | Self-hosted | +| **Best for** | Agent API for adding onchain capabilities without managing infrastructure; OpenClaw plugins for adding onchain skills to a self-hosted agent | Running a multi-channel assistant with pre-built skills and plugin support | Production agents where you need full control over logic, integrations, and deployment | + +## BANKR + +BANKR offers two ways to work with agents on Base. The **BANKR Agent API** is a hosted agent you interact with through a REST API: you send prompts and receive results, including the ability to execute trades and check balances, without building or deploying your own agent. This is the fastest way to add onchain agent capabilities to an existing application. + +BANKR also provides **skills and wallet plugins for OpenClaw**. If you're building with OpenClaw, you can install BANKR's skill packages to give your self-hosted agent wallet capabilities, token swaps, and other onchain actions without using the managed API. + +Use the BANKR Agent API when you want onchain agent capabilities without managing infrastructure. Use BANKR's OpenClaw plugins when you want BANKR's onchain skills inside your own self-hosted agent. + +[Get started with BANKR Agent API →](https://docs.bankr.bot/getting-started/quick-start) -Build agents with Coinbase's Agent SDK. [Get started →](https://docs.cdp.coinbase.com/agent-kit/welcome) +[Browse BANKR skills for OpenClaw →](https://github.com/BankrBot/openclaw-skills) ## OpenClaw -Run a personal AI assistant across multiple channels. +OpenClaw is an open-source AI assistant that connects to multiple messaging platforms out of the box. It comes with a plugin system for adding skills (pre-built actions your agent can perform) and handles the infrastructure for receiving messages, processing them, and responding across channels. + +Use OpenClaw when you want to run a conversational agent across Discord, Telegram, or web and extend it with community-built plugins. + +[Get started with OpenClaw →](https://docs.openclaw.ai/start/getting-started) + +## Agent SDK + +Coinbase's Agent SDK gives you the building blocks to create agents that can interact with onchain services. You write the agent logic, define its tools, and deploy it on your own infrastructure. This is the most flexible option: you control every aspect of the agent's behavior, from how it processes prompts to which services it calls. + +Use Agent SDK when you're building a production agent and want full control over its architecture. -[Get started →](https://docs.openclaw.ai/start/getting-started) +[Get started with Agent SDK →](https://docs.cdp.coinbase.com/agent-kit/welcome) -## BANKR Agent API + +**How to choose:** Use the **BANKR Agent API** to call an agent via API without building one, or add **BANKR's skill plugins** to an OpenClaw agent for onchain capabilities. Use **OpenClaw** if you need a multi-channel chatbot with plugins. Use **Agent SDK** if you want full control over logic, integrations, and deployment. + -If you want to interact with an onchain agent without building your own, BANKR provides an Agent API. Send prompts, get results, execute trades - via REST. +## Next step -[Get started →](https://docs.bankr.bot/getting-started/quick-start) \ No newline at end of file + + Give your agent the ability to hold funds and make payments. + diff --git a/docs/ai-agents/core-concepts/identity-verification-auth.mdx b/docs/ai-agents/core-concepts/identity-verification-auth.mdx index 4c00bbe0e..ecbda67db 100644 --- a/docs/ai-agents/core-concepts/identity-verification-auth.mdx +++ b/docs/ai-agents/core-concepts/identity-verification-auth.mdx @@ -1,9 +1,9 @@ --- title: "Identity, Verification, and Auth" -description: "How your agent becomes discoverable, verifiable, and trusted by other agents and services" +description: "Make your agent discoverable and verifiable so other agents and services can trust it" --- -Your agent needs to be discoverable and verifiable. ERC-8004 registers your agent onchain. ERC-8128 verifies actions come from the registered agent. SIWA lets your agent authenticate into services. This page covers how these standards work together to establish trust. +When your agent calls a service, how does that service know it's really your agent and not an impersonator? When your agent receives a response, how does it know the response came from a legitimate service? Identity, verification, and authentication solve these problems. -## Registry and verification +## Why identity matters -A trusted agent registry allows agents and services to register their identity onchain. When registered, your agent has a publicly auditable identity declaring what it does and where its endpoints live. Other agents can check this registry before interacting. +In a world where agents interact with each other and with services autonomously, trust is the foundation. Without identity: -Discovery alone isn't enough. Verification happens at execution time. When your agent registers, its identity is tied to a cryptographic keypair. When your agent calls a service, the service signs its response using those keys. Your agent checks the signature against the registry. If they match, you're talking to the right endpoint. +- A service can't verify that a request came from an authorized agent +- Your agent can't verify that a response came from the real service (not a malicious impersonator) +- Other agents can't discover what your agent does or how to interact with it -[Learn more about Agent Registry →](https://www.8004.org/) +Identity standards on Base solve all three problems: they let your agent register itself in a public directory, prove its identity with every request, and discover other agents and services. -[Learn more about Agent Verification →](https://erc8128.slice.so/concepts/overview) +## Registry: a public directory for agents + +A registry is a public directory where agents and services publish their identity. Any participant can query the registry to resolve an agent's name to its metadata: what it does, where its endpoints live, and which public key it uses for signing. + +On Base, this is implemented through the **ERC-8004** standard. When your agent registers, its entry is stored onchain, which means anyone can verify it without relying on a central authority. + +A registry entry typically includes: + +- Your agent's name and description +- The endpoints where it can be reached +- A key pair that ties the agent's identity to its cryptographic credentials + +[Learn more about Agent Registry (ERC-8004) →](https://www.8004.org/) + +## Verification: proving identity at runtime + +Registration tells the world your agent exists. Verification proves it's really your agent making each request. This is handled by the **ERC-8128** standard. + + + + Your agent registers its identity and public key in the ERC-8004 registry. This is a one-time setup step. + + + + When your agent calls a service, it signs the request using its private key. This creates a cryptographic signature unique to that specific request. + + + + The service looks up your agent's public key from the registry, then checks the signature. If the signature matches, the service knows the request came from your registered agent and not an impersonator. + + + +This works in both directions: your agent can also verify that a service's response is authentic by checking the service's signature against the registry. + +[Learn more about Agent Verification (ERC-8128) →](https://erc8128.slice.so/concepts/overview) ## Sign In With Agent (SIWA) -SIWA is the easiest way to implement registry and verification together. One SDK instead of wiring up two standards yourself. Your agent proves its identity via the registry, then signs every subsequent request for verification. +SIWA bundles registry and verification into a single SDK, similar to how "Sign in with Google" bundles OAuth and identity verification into one integration. Instead of wiring up ERC-8004 and ERC-8128 separately, you integrate SIWA and get both capabilities out of the box. + +With SIWA, your agent can: + +- **Register its identity** in the onchain directory +- **Authenticate into services** by proving it is the registered agent +- **Sign every request** so services can verify authenticity + +SIWA is the fastest path to giving your agent a verifiable identity. Use ERC-8004 and ERC-8128 directly only if you need more granular control over the registration and verification process. + +[Learn more at siwa.id →](https://siwa.id) -Learn more at [siwa.id](https://siwa.id). + +**Start with SIWA** for the simplest integration path. Use ERC-8004 and ERC-8128 directly if you need fine-grained control over how your agent registers and how verification is performed. + ## Next step - - Enable your agent to make payments, execute transactions, and interact with protocols. + + Build services designed for agents and make your app discoverable. diff --git a/docs/ai-agents/core-concepts/payments-and-transactions.mdx b/docs/ai-agents/core-concepts/payments-and-transactions.mdx index b1de1fc87..79fa27205 100644 --- a/docs/ai-agents/core-concepts/payments-and-transactions.mdx +++ b/docs/ai-agents/core-concepts/payments-and-transactions.mdx @@ -1,35 +1,94 @@ --- -title: "Payment & Transactions" -description: "Enable your agent to make payments, execute transactions, and interact with protocols" +title: "Payments and Transactions" +description: "How your agent pays for services, receives payments, and executes onchain actions" --- +Your agent has a wallet. Now it needs to use it. This page covers two key concepts: how your agent pays for services automatically using the x402 protocol, and how skills define the actions your agent can perform. + -Your agent has a wallet and a verified identity. Now it needs to act. -Onchain actions are driven by skills. Skills give your agent tools to interact with X402 payments, smart contracts, and other services. +## x402: pay-per-request with stablecoins + +x402 lets your agent pay for API requests using stablecoins without subscriptions or API keys. Your agent requests a resource, the server tells it the price, your agent pays, and the server delivers the data. + +The name comes from HTTP status code `402 Payment Required`, which has been reserved in the HTTP specification since the 1990s but was never widely adopted. x402 finally puts it to use. + +### How x402 works + + + + Your agent sends a standard HTTP request to an API endpoint, just like any other API call. + + + + Instead of returning data, the server responds with a `402` status code and includes payment details: how much it costs, which stablecoin to pay in, and where to send the payment. + + + + Your agent's wallet constructs and sends a onchain payment based on the server's instructions. This happens automatically, no human approval needed. + + + + Once the payment is confirmed, the server returns the requested data. The entire flow takes seconds. + + + +This model is powerful for agents because it requires no pre-existing relationship between your agent and the service. Any agent with a funded wallet can pay for any x402-enabled API on the fly. + +[Learn more about x402 →](https://www.x402.org/) + +## Skills: actions your agent can perform + +Skills are typed function definitions that describe an action your agent can invoke. Each skill specifies a name, expected inputs, and return type similar to a tool or function schema in any LLM tool-use integration. Your agent parses these definitions at runtime and calls them when relevant. + +Skills cover actions like checking a token balance, executing a swap, sending a payment, or calling a smart contract. + +### What a skill looks like + +A skill definition includes the action name, a description of what it does, the required inputs, and the expected output. Here's a simplified example: + +```json Title "Conceptual skill definition" +{ + "skill": "check-balance", + "description": "Check the token balance of a wallet address", + "inputs": { + "wallet_address": "The address to check", + "token": "The token symbol (e.g., USDC, ETH)" + }, + "output": "The current balance of the specified token" +} +``` + +Your agent reads this definition, understands what inputs it needs to provide, and calls the skill when it's relevant to the task at hand. + +### Skill providers -## How agents transact + + + **What they are:** Pre-built skills for agents running on OpenClaw. BANKR skills cover common actions like token swaps, balance checks, and DeFi interactions. -Agents build their own transactions based on the prompts defined in skill files. The skill file tells the agent what actions are available, what parameters are required, and how to construct the transaction. The agent interprets these prompts and executes accordingly. + **Best for:** Agents using OpenClaw or BANKR that need ready-to-use onchain capabilities. -## X402 + [Browse BANKR skills →](https://github.com/BankrBot/openclaw-skills) + -X402 is an open payment protocol for instant stablecoin payments over HTTP. Your agent requests a resource, pays programmatically, and receives access. -[Deep dive on X402 →](/learn/onchain-concepts/x402) + + **What they are:** Skills provided by Coinbase's developer platform. CDP skills integrate with the Agentic Wallet and cover wallet management, token operations, and protocol interactions. -## Skills + **Best for:** Agents using Agent SDK with a CDP Agentic Wallet. -Skills are tools your agent can call. If you've used Claude or other LLMs with tool use, it's the same concept - predefined capabilities the agent can invoke when needed. -Each skill defines what it does, what inputs it expects, and what the agent can do with it. Your agent reads the skill, understands its purpose, and calls it when relevant to the task. + [Browse CDP skills →](https://docs.cdp.coinbase.com/agentic-wallet/skills/overview) + + -**BANKR Skills** -Install from [github.com/BankrBot/openclaw-skills](https://github.com/BankrBot/openclaw-skills) +## Next step -**CDP Skills** -Install from [docs.cdp.coinbase.com/agentic-wallet/skills/overview](https://docs.cdp.coinbase.com/agentic-wallet/skills/overview) + + Make your agent discoverable and verifiable so other agents and services can trust it. + diff --git a/docs/ai-agents/core-concepts/wallets.mdx b/docs/ai-agents/core-concepts/wallets.mdx index d4b7a2f46..a62988e67 100644 --- a/docs/ai-agents/core-concepts/wallets.mdx +++ b/docs/ai-agents/core-concepts/wallets.mdx @@ -1,9 +1,9 @@ --- title: "Wallets" -description: "Give your agent economic agency by integrating a wallet" +description: "Give your agent the ability to hold funds, send payments, and sign messages" --- -Wallets give your agent the ability to hold funds and execute transactions. This page covers the wallet options available on Base and how to integrate them with your agent. +An onchain wallet gives your agent the ability to hold funds, authorize transactions, and sign messages. Without one, your agent can read data but can't pay for services, receive payments, or prove its identity.