Skip to content

Deepen ai-agent docs and reorganize for flow builders follow #1147

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
soheimam merged 1 commit into from
Feb 19, 2026
Merged

Deepen ai-agent docs and reorganize for flow builders follow #1147

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
63 changes: 53 additions & 10 deletions docs/ai-agents/core-concepts/agent-apps.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/-y0ZJ-0z7Ow?si=YtmXlwM_3m8Gm0WE"
title="Agent wallets on Base"
title="Building agent apps on Base"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>

## 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.

<Warning>
The Agent App Framework is experimental. APIs and conventions may change as the standard evolves.
</Warning>

<GithubRepoCard title="Agent App Framework" githubUrl="https://github.com/base/agent-apps-experimental" />

## Continue exploring

<GithubRepoCard title="Agent App Framework" githubUrl="https://github.com/base/agent-apps-experimental" />
<Card title="Back to overview" icon="arrow-left" href="/ai-agents/index">
Return to the AI agents overview for a summary of all components.
</Card>
51 changes: 41 additions & 10 deletions docs/ai-agents/core-concepts/agent-frameworks.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<iframe
className="w-full aspect-video rounded-xl"
src="https://www.youtube.com/embed/b5Wx2NAeY2E?si=r1FumIsbGt6nAt29"
title="Agent wallets on Base"
title="Building agents on Base"
allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
allowFullScreen
></iframe>

## 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 <Tooltip tip="Blockchain-based protocols and applications, such as decentralized exchanges or lending platforms">onchain services</Tooltip>. 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
<Tip>
**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.
</Tip>

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)
<Card title="Wallets" icon="arrow-right" href="/ai-agents/core-concepts/wallets">
Give your agent the ability to hold funds and make payments.
</Card>
70 changes: 59 additions & 11 deletions docs/ai-agents/core-concepts/identity-verification-auth.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.

<iframe
className="w-full aspect-video rounded-xl"
Expand All @@ -13,24 +13,72 @@ Your agent needs to be discoverable and verifiable. ERC-8004 registers your agen
allowFullScreen
></iframe>

## 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 <Tooltip tip="A pair of cryptographic keys: the public key is shared openly (like a return address) and identifies your agent, while the private key is kept secret (like a signature stamp) and proves you control the identity">key pair</Tooltip> 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.

<Steps>
<Step title="Register your agent">
Your agent registers its identity and public key in the ERC-8004 registry. This is a one-time setup step.
</Step>

<Step title="Sign each request">
When your agent calls a service, it signs the request using its private key. This creates a cryptographic signature unique to that specific request.
</Step>

<Step title="The service verifies the signature">
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.
</Step>
</Steps>

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).
<Tip>
**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.
</Tip>

## Next step

<Card title="Payment & Transactions" icon="link" href="/ai-agents/core-concepts/payments-and-transactions">
Enable your agent to make payments, execute transactions, and interact with protocols.
<Card title="Agent apps" icon="arrow-right" href="/ai-agents/core-concepts/agent-apps">
Build services designed for agents and make your app discoverable.
</Card>
Loading