aixyz

aixyz の使用方法

最新情報の確認場所

このプロジェクトは急速に進化しています。最新情報は必ず以下の情報源で確認してください。

• ドキュメントサイト： aixyz.sh — はじめに、API リファレンス、プロトコルのドキュメント、テンプレート
• GitHub： github.com/AgentlyHQ/aixyz — ソースコード、課題、サンプル
• CLI ヘルプ： すべてのコマンドで --help を使用できます。実行して最新のフラグを確認してください

変更されない事実

以下の事項は変更されません。

• ランタイムは常に Bun です — bun でインストールし、bun で実行し、bun test でテストします
• エージェントのロジックには Vercel AI SDK を使用します（ai パッケージ） — "ai" の ToolLoopAgent、tool()、stepCountIs() を使用します。現行バージョンは ai-sdk.dev で確認してください
• LLM プロバイダーには @ai-sdk/* アダプターを使用します — デフォルトは @ai-sdk/openai ですが、Vercel AI SDK の任意のプロバイダーを使用できます（@ai-sdk/anthropic、@ai-sdk/google、@ai-sdk/amazon-bedrock など）
• 新しいエージェントのひな型作成には、必ず create-aixyz-app を使用してください — 詳細は以下をご覧ください
• aixyz CLI は常に使用できます — 開発／テストには aixyz dev、ビルドには aixyz build を使用します
• 環境変数の読み込み順序は Next.js に従います — .env、.env.local（コミットしないでください）、.env.<NODE_ENV>、.env.<NODE_ENV>.local

はじめに

重要：新しいエージェントプロジェクトの作成には、必ず create-aixyz-app を使用してください。 aixyz.config.ts、package.json、app/agent.ts、その他のプロジェクトファイルを手動で作成しないでください。 これらのファイルを手動で作成すると、ビルドの失敗、依存関係の不足、設定の誤りが発生します。 まず bunx create-aixyz-app でひな型を作成してから、生成されたファイルを変更してください。

# See all scaffolding options (TTY is disabled in AI/CI — every prompt has a flag)
bunx create-aixyz-app --help

# Scaffold with defaults
bunx create-aixyz-app my-agent --yes

# Dev/test loop
cd my-agent && bun run dev   # aixyz dev — hot reload at http://localhost:3000

# Build for deployment
bun run build                # aixyz build

主な概念

プロジェクト構成

開始に必要な最小構成：

my-agent/
  aixyz.config.ts       # Agent identity, payment config, skills declaration
  app/
    agent.ts            # Root agent (ToolLoopAgent from "ai") — required
    tools/name.ts       # Tools (optional) — each file auto-registered; not exported directly
    agents/name.ts      # Sub-agents (optional) — each file → /name/agent endpoint
  package.json
  .env.local            # API keys — never commit

オプションのファイルを含む全体構成：

my-agent/
  aixyz.config.ts
  app/
    agent.ts
    agents/             # Sub-agents
    tools/              # Tools; _prefix files are ignored
    server.ts           # Custom server (overrides auto-generation)
    accepts.ts          # Custom x402 facilitator
    erc-8004.ts         # On-chain ERC-8004 identity
    icon.png            # Agent icon
  package.json
  vercel.json
  .env.local

収益化（x402）

app/agent.ts から accepts をエクスポートすると（/agent を制御）、またはツールファイルからエクスポートすると（/mcp で制御）、支払いを設定できます。

import type { Accepts } from "aixyz/accepts";

export const accepts: Accepts = { scheme: "exact", price: "$0.005" };

accepts をエクスポートしない場合、エンドポイントは公開されません。scheme: "free" の場合、明示的に無料になります。 詳しくは aixyz.sh/getting-started/payments をご覧ください。

A2A の機能

app/agent.ts から capabilities をエクスポートして、A2A エージェントカードとエグゼキューターの動作を設定します。

import type { Capabilities } from "aixyz/app/plugins/a2a";

export const capabilities: Capabilities = { streaming: false, pushNotifications: false };

デフォルトは { streaming: true, pushNotifications: false } です。streaming: false の場合、エグゼキューターは stream() の代わりに generate() を使用します。

オンチェーン ID（ERC-8004）

次のコマンドでエージェントをオンチェーンに登録します。

aixyz erc-8004 register --help   # see all non-TTY flags
aixyz erc-8004 register --url https://my-agent.vercel.app --broadcast

詳しくは aixyz.sh/protocols/erc-8004 をご覧ください。

テスト（任意）

テストは任意ですが、上級ユーザーには推奨されます。テストには Bun 組み込みのランナー（bun:test）を使用します。決定論的なテスト（API 呼び出しなし）を作成し、非決定論的なテストには test.skipIf(!process.env.OPENAI_API_KEY) を使用してください。完全にオフラインで、CI でも安全なテストには "aixyz/model" の fake() を使用します。

bun test                      # run all tests
bun test app/agent.test.ts    # run a specific file

詳しくは aixyz.sh/getting-started/testing をご覧ください。

プロトコルのエンドポイント

デプロイされたすべてのエージェントでは、以下のエンドポイントが自動的に公開されます。

エンドポイント	プロトコル	説明
/.well-known/agent-card.json	A2A	エージェントの検出用カード
/agent	A2A	x402 の支払いゲート付き JSON-RPC エンドポイント
/mcp	MCP	MCP クライアントとのツール共有

例

github.com/AgentlyHQ/aixyz の examples/ ディレクトリには、よく使われるパターンの実用的なエージェントが含まれています。迷った場合は、必要なものに合った例を探してください。

GitHub にアクセスできる場合は、リポジトリをクローンして examples/ を直接確認してください。

gh repo clone AgentlyHQ/aixyz
ls aixyz/examples/

各例には、参考にできる aixyz.config.ts、app/agent.ts、app/tools/ があります。 aixyz.sh のテンプレートタブでは、各例について説明しています。

リポジトリの構造（探索用）

リポジトリをクローンした場合、主な領域は次のとおりです。

packages/
  aixyz/              # Framework core (server, adapters, x402)
  aixyz-cli/          # CLI: dev, build, erc-8004 commands
  aixyz-config/       # Config loading (Zod-validated aixyz.config.ts)
  aixyz-erc-8004/     # ERC-8004 ABIs, addresses, schemas
  create-aixyz-app/   # Scaffolding CLI
docs/                 # Mintlify docs
examples/             # Working agent examples

最新情報については、任意の CLI コマンドで --help を使用するか、aixyz.sh のドキュメントを読むか、 github.com/AgentlyHQ/aixyz/tree/main/examples の例を参照してください。