はじめに

Mindsクライアントライブラリ

設定済みのMindsをアプリケーションに組み込むための、型付きNodeクライアントです。Minds CLIでのセットアップ後、メッセージング・イベント・Builder APIルートに対応します。

@animocabrands/minds-client-lib は、アプリケーションやプロダクトに Mindsをラップして埋め込むための手段 です。多くのビルダーはまず Minds CLI から始め、Mindsの一覧表示・詳細確認・Cognitionの監視・Circlesの管理・Bazaarの閲覧を行い、準備が整ったらこちらに移行します。このライブラリは、同じ Builder API をTypeScriptの型付きで公開します：メッセージング、 waitForReply 、SSEイベント、そしてすでにターミナルで実行したアカウント関連のルートです。

パッケージはプロジェクトの サーバー側 に追加してください。UI・ブランディング・ユーザーフローはそのままあなたのものです。クライアントはapi.buildへの型付きHTTP通信とストリーミングを担当します。アカウント設定を完了し、CLIでMindを検証したら、以下の例を組み込むか、設定が終わり次第コーディングエージェントに渡してください。

インストール

Node 22+ が必要です。

npm install @animocabrands/minds-client-lib

認証

アカウントおよびメッセージング関連のルートには、Builder APIキーを渡してください。ライブラリは認証済みルート（≥0.1.2）で X-Api-Key のみ を送信します。X-Access-Key は非推奨のため使用しないでください。環境変数名は引き続き MINDS_BUILDER_API_KEY です。

import {
  BUILDER_API_KEY_ENV,
  BUILDER_API_KEY_HEADER,
  createMindsClient,
} from "@animocabrands/minds-client-lib";
 
const builderApiKey = process.env[BUILDER_API_KEY_ENV];
if (!builderApiKey) throw new Error(`${BUILDER_API_KEY_ENV} is not set`);
 
const client = createMindsClient({ builderApiKey });

クライアントの作成

import { createMindsClient } from "@animocabrands/minds-client-lib";
 
const client = createMindsClient({ builderApiKey: yourBuilderApiKey });

createMindsClient({}) は、公開Bazaarカタログ（ client.bazaar.* ）のみで有効です。認証が必要なメソッドは、キーが渡されていない場合、構築時ではなく呼び出し時に missing_builder_api_key というコードで MindsApiError をスローします。

Mindsの一覧表示

listMinds() は、アカウント上のすべてのMind（ mindId ・ name ・ model ・ species 、および関連フィールド）を返します。

const minds = await client.listMinds();
const mindId = minds[0]?.mindId;

humanId はBuilder APIキーから自動的に解決されます。明示的に上書きしたい場合は listMinds({ humanId }) を渡してください。

Mindの詳細

getMind(mindId) は、メールアドレス・ウォレットアドレス・チェーン・species・ isEnabled など、完全な詳細情報を返します：

const detail = await client.getMind(mindId);
console.log(detail.email, detail.walletAddress, detail.chain);

Cognition残高と使用量

MindごとのCognition使用量と残高は、CLIコマンドと同じ仕組みです。Mindは会話中だけでなく、推論・ツール実行・自律的なタスク遂行の際にもCognitionを消費します。どちらのメソッドも mindId （UUID）と、オプションで AbortSignal を受け取ります。 Cognition は、Mindの推論・ツール利用・自律的な作業を支えます。時間経過やツールごとの使用状況を見るには getCognitionUsage と getCognitionUsageByTool を、残りのCognition残高を確認するには getCognitionBalance を使用してください：

const mindId = (await client.listMinds())[0]?.mindId;
if (!mindId) throw new Error("No Minds on this account");
 
const usage = await client.getCognitionUsage(mindId, { interval: "1d" });
console.log(usage.items); // [{ bucket, value }, ...]
 
const byTool = await client.getCognitionUsageByTool(mindId, { interval: "day" });
console.log(byTool.summary); // [{ tool, callCount, creditsUsed, ... }, ...]
console.log(byTool.timeline); // [{ tool, timeBucket, callCount, creditsUsed }, ...]
 
const balance = await client.getCognitionBalance(mindId);
console.log(balance.cognition);

2つの使用量取得メソッドは、それぞれ異なる間隔の値を受け付けます： getCognitionUsage は 1m ・ 5m ・ 15m ・ 1h ・ 1d ・ 1w ・ 1M を、 getCognitionUsageByTool は hour ・ day ・ week ・ month のみを受け付けます。オプションの startTime と endTime （ISO日時形式）で、どちらも期間を絞り込めます。

Mindのステータス

Mindを削除せずに有効化・無効化できます：

await client.updateMindStatus(mindId, { isEnabled: false });
await client.updateMindStatus(mindId, { isEnabled: true });

updateMindStatus は更新された BuilderMind を返します。

Circles

Mindのcircleは、そのMindと関わる人間の協力者の集合です。 getCircle は CircleMember[] 配列を直接返します。 addCircleMembers と removeCircleMembers は、メールアドレスごとの結果とベストエフォートのサマリーを含む CircleMutationResult エンベロープを返します：

const members = await client.getCircle(mindId);
console.log(members.map((m) => m.email));
 
const added = await client.addCircleMembers(mindId, {
  emails: ["someone@company.com", "peer@company.com"],
  isActive: true,
});
console.log(added.summary);
 
const removed = await client.removeCircleMembers(mindId, {
  emails: ["someone@company.com"],
});
console.log(removed.items);

Circleに追加できるのは 人間の協力者のメールアドレスのみ です。ビルダー向けMindの @hellominds.ai アドレスは対象外です。このAPIを通じたMind同士のCircleメンバーシップはサポートされていません。 listCirclesForAccount() は、 listMinds() を呼び出してから各Mindに対し並行して getCircle() を呼び出す便利なメソッドです。頻繁に呼び出す処理ではなく、アカウント全体の概要把握に使用してください。

Bazaarカタログ

公開Bazaarカタログは client.bazaar として利用でき、APIキーは不要です。 IDの検索 （ skillId 、 appId ）にBazaarを使用し、下記のMind装備メソッドでそれらのIDを装備してください。ルートの形状は APIリファレンスのBazaarおよびMindsタグに記載されています。CLIも minds bazaar で同じカタログを提供しています。リスト項目には equippedCount が含まれる場合があります。これは プラットフォーム全体 でそのアイテムを装備しているMindの数です。これはプラットフォーム全体での人気であり、Mindごとの装備セットには listEquippedSkills / listEquippedApps を使用してください。

const catalog = createMindsClient({}).bazaar;
 
const skills = await catalog.listSkills({ search: "research", page: 1, pageSize: 25 });
const skill = await catalog.getSkill("skill_abc123");
 
const apps = await catalog.listApps({ search: "notion", tier: "verified" });
const app = await catalog.getApp("app_xyz789");
 
const result = await catalog.collectSearchResults({
  scanMax: 200,
  max: 50,
  sort: "equipped",
  fetchPage: (page, pageSize) => catalog.listSkills({ search: "agent", page, pageSize }),
  getEquippedCount: (s) => s.equippedCount ?? 0,
  getName: (s) => s.name,
  getCreatedAt: (s) => s.createdAt,
});

Appは appId と appName （ name ではない）を使用します。 collectSearchResults は scanMax まで自動的にページ送りし、クライアント側でソート・フィルタリングを行い、スキャン範囲が max を超えると truncated を報告します。 sort: "equipped" は、Mindごとの装備状況ではなく、 equippedCount の降順（プラットフォーム全体の人気順）で並び替えます。

SkillとAppの装備

MindでSkillやAppを一覧表示・装備・装備解除できます（Builder APIキーが必要です）。ボディは { ids: string[] } を使用します。ミューテーションは skillId / appId 、 isEquipped 、 changed を含む { results: [...] } を返します（App結果には appVersionId と version も含まれる場合があります）：

const equippedSkills = await client.listEquippedSkills(mindId);
await client.equipSkills(mindId, { ids: [skill.skillId] });
await client.unequipSkills(mindId, { ids: [skill.skillId] });
 
const equippedApps = await client.listEquippedApps(mindId);
await client.equipApps(mindId, { ids: [app.appId] });
await client.unequipApps(mindId, { ids: [app.appId] });

カタログを閲覧する必要がある場合は、まず client.bazaar でIDを検索してください。装備済みのSkillには source が含まれます： mind はカタログまたはMindが作成したSkill、 system はプラットフォーム提供のSkill（例：Skill Architect）を表します。

会話

メッセージ送信前に、安定した alias （例：main）をMindに紐づけます：

await client.ensureConversation("main", mindId);

ensureConversation はべき等です。そのMindにすでに同じaliasが存在する場合は、既存の会話がそのまま返されます。 aliasを自分で管理したい場合の、より低レベルなヘルパー関数：

const conversations = await client.listConversations();
const conversation = await client.getConversation("main");
await client.createConversation({ alias: "main", mindId });

送信と履歴

await client.sendMessage({ alias: "main", messageText: "Hello" });
 
const rows = await client.getHistory("main", { limit: 50 });
const after = rows.at(-1)?.fingerprint;
const newer = await client.getHistory("main", { after, limit: 50 });

getHistory は人間とMindの完全な会話履歴を返します。行には senderType （ 1 = 人間、 0 = Mind）が含まれます。同じフィールドは subscribeEvents / eventsIterator / waitForReply からのSSEイベントにも表示されます。 sendMessage には alias と messageText が必須です。オプションの attachments は送信側のオブジェクトを受け付けます。 fileName と mimeType を伴う公開HTTPS url の使用を推奨します：

await client.sendMessage({
  alias: "main",
  messageText: "Summarize this PDF in one sentence.",
  attachments: [
    {
      url: "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
      fileName: "dummy.pdf",
      mimeType: "application/pdf",
      extension: "pdf",
    },
  ],
});

画像URLも同じ形式です（ mimeType: "image/png" など）。 getHistory ・ waitForReply ・SSEイベントにおけるMindの返信には、次のような 受信側 のartifactが含まれることがあります：

// One attachment on a Mind reply (PDF; artifact body truncated)
{
  artifactId: "7388b65d-144a-49ff-a4dc-cb7c23ded982",
  slug: "whale_watchtower_skill_artifact_1_0_5",
  logicalType: "document",
  mimeType: "application/pdf",
  extension: "pdf",
  artifact: "JVBERi0xLjQK...",
}

送信側では、インラインのペイロードに content を使用し、受信側では同じ役割を artifact が担います。 slug と logicalType はオプションの文字列で、固定の列挙型ではなくヒントとして扱ってください。フィールドの詳細は APIリファレンスを参照してください。 getLatestHistoryFingerprint は最新メッセージのフィンガープリントを返します。これを getHistory の after として渡して新しい行のみを取得するか、 waitForReply の前に afterFingerprint として渡して、送信後に到着した返信を見つけます。

エイリアスが最後に話したMindを解決する：

const mindId = await client.getMindIdForAlias("main");

Mindの返信を待つ

waitForReply は、最初にライブイベントストリームを監視し、その後は返信が届くかタイムアウトになるまで履歴をポーリングします。

const before = await client.getLatestHistoryFingerprint("main");
 
await client.sendMessage({ alias: "main", messageText: "Summarize our plan." });
 
const outcome = await client.waitForReply({
  alias: "main",
  timeoutMs: 180_000,
  afterFingerprint: before,
  sentMessageText: "Summarize our plan.",
});
 
if (!outcome.timedOut) {
  console.log(outcome.reply.messageText);
}

SSEまたは履歴の行を自分でフィルタリングする場合は、パッケージの isReplyEvent を使用してください。

ライブイベント（SSE）

コールバックでサブスクライブする：

const sub = client.subscribeEvents({
  alias: "main",
  onEvent: (event) => {
    console.log(event.messageText);
  },
  onError: (err) => console.error(err),
});
 
// later
sub.close();

または非同期イテレータを使用する：

for await (const event of client.eventsIterator({ alias: "main" })) {
  console.log(event.fingerprint, event.messageText);
}

プロセスがシャットダウンしたときに、イテレータまたはサブスクライブをキャンセルするには、オプションに signal を渡します。

エラー

HTTP呼び出しが失敗すると、 status ・ code ・ message を持つ MindsApiError がスローされます。 builderApiKey なしで認証メソッドを呼び出すと、呼び出し時に missing_builder_api_key がスローされます。401/403はBuilder APIキーの欠落または失効を示します。429には再試行のガイダンスが含まれる場合があります。

メソッド

領域	メソッド
Account	`listMinds`, `getMind`
Cognition	`getCognitionUsage`, `getCognitionUsageByTool`, `getCognitionBalance`
Mind status	`updateMindStatus`
Equip	`listEquippedSkills`, `equipSkills`, `unequipSkills`, `listEquippedApps`, `equipApps`, `unequipApps`
Circles	`getCircle`, `addCircleMembers`, `removeCircleMembers`, `listCirclesForAccount`
Bazaar	`bazaar.listSkills`, `bazaar.getSkill`, `bazaar.listApps`, `bazaar.getApp`, `bazaar.collectSearchResults`
Conversations	`createConversation`, `listConversations`, `getConversation`, `ensureConversation`, `getMindIdForAlias`
Messaging	`sendMessage`, `getHistory`, `getLatestHistoryFingerprint`
Replies	`waitForReply`, `isReplyEvent`, `isReplyHistoryRow`
Events	`subscribeEvents`, `eventsIterator`, `parseSseChunk`

型（ BuilderMind 、 Conversation 、 MessageRecord 、 MessagingEvent 、 CognitionBalance 、 BazaarSkill 、 BazaarApp 、 EquippedSkill 、 EquippedApp 、 CircleMember 、 CircleMutationResult 、 CognitionUsageResponse 、 CognitionUsageByToolResponse 、 UpdateMindStatusBody など）と parseHumanIdFromBuilderApiKey は、パッケージエントリからエクスポートされます。