はじめに

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

Builder APIをTypeScriptの型付きで呼び出します。Builder APIキーは自分のアカウント、OAuthアクセストークンはMinds Connectでサインインしたユーザーを対象にします。

@animocabrands/minds-client-lib は、アプリケーションから Builder APIを呼び出す手段 です。多くのビルダーはまず自分のアカウントで Minds CLI を使い、同じ呼び出しをTypeScriptの型付きで出荷するためにこのライブラリへ移ります。対象はメッセージング、 waitForReply 、SSEイベント、アカウント操作です。ユーザーがサインインするブラウザアプリは Minds Connect SDK を使います。Connectはこのクライアントを包み、呼び出しの前にユーザーのアクセストークンを更新します。

Nodeのバックエンドから使うか、Connect経由でブラウザから使ってください。UI・ブランディング・ユーザーフローはそのままあなたのものです。クライアントはapi.buildへの型付きHTTP通信とストリーミングを担当します。Builder APIキーを使う場合は始め方を完了し、CLIで確認してから以下の例を組み込みます。ユーザーのサインインにはOAuthクライアントを登録し、Connectのガイドに従ってください。

インストール

Nodeアプリには Node 22+ が必要です。Connectは同じパッケージをブラウザで読み込みます。

npm install @animocabrands/minds-client-lib

認証

アカウントおよびメッセージングの呼び出しは、OAuthアクセストークン または Builder APIキー を受け付けます。両方を渡した場合はアクセストークンが優先され、クライアントは Authorization: Bearer を送ります。トークンが無いときは X-Api-Key を送ります。X-Access-Key は非推奨のため使用しないでください。ライブラリは .env を読み込みません。アプリ側で MINDS_BUILDER_API_KEY（定数 BUILDER_API_KEY_ENV）を読み、引数として渡してください。ブラウザアプリは Minds Connect SDK を使います。Connectの oauth.client は、リクエストの前に新しいトークンを渡します。バックエンドでは、ブラウザでユーザーがサインインしたあと、そのアクセストークンを createMindsClient に渡します。 Builder APIキーはビルダー自身のアカウントとして動作します。アクセストークンはサインインしたユーザーとして動作し、許可されたスコープの範囲だけです。 Builder APIキー:

import { BUILDER_API_KEY_ENV, 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 });

OAuthアクセストークン:

import { createMindsClient } from "@animocabrands/minds-client-lib";
 
const client = createMindsClient({ accessToken });
client.setAccessToken(nextToken);
client.setAccessToken(null);

setAccessToken(null) または空文字はトークンを消します。構築時にBuilder APIキーも渡していれば、その後の呼び出しはキーを使います。 getAccessToken は、認証が必要なHTTPまたはSSEリクエストの前に実行されます。返したトークンは、そのリクエストでは静的な accessToken より優先されます。Connectは oauth.client でこれを接続します。関数が null を返した場合、クライアントは静的なトークンまたはキーに戻ります。

const client = createMindsClient({
  getAccessToken: async () => accessTokenFromYourSession,
});

ブラウザのセッションがすでにあるバックエンド:

import { createMindsClient } from "@animocabrands/minds-client-lib";
 
const accessToken = req.headers.authorization?.replace(/^Bearer\s+/i, "");
const minds = await createMindsClient({ accessToken }).listMinds();

定数	値
`BUILDER_API_KEY_ENV`	`MINDS_BUILDER_API_KEY`
`BUILDER_API_KEY_HEADER`	`X-Api-Key`

クライアントの作成

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

createMindsClient({}) は、公開Bazaarカタログ（ client.bazaar.* ）のみで有効です。アクセストークンもBuilder APIキーも無い場合、認証が必要なメソッドは構築時ではなく 呼び出し時 に missing_builder_api_key というコードで MindsApiError をスローします。コード名は変わりません。

Mindの作成

Mindの名前は一意です。すでに使われている名前ではないか、先に checkMindName で確認します（公開、認証情報は不要）。その後に awakenMind を呼び出します（Builder APIキーまたはアクセストークンが必要です）。 id は作成する事前構築済みMindのタイプを選びます。パッケージはカタログをエクスポートしません。各タイプの短い説明付き一覧は、Minds CLI で minds mind awaken --help を実行すると確認できます。同じ一覧はAPIリファレンスにもあります。名前が既に使われている、または id が無効な場合、 awakenMind は MindsApiError をスローします。例は sales Mind「J-Belfort」です。このペンを売ってみて。

const check = await client.checkMindName("J-Belfort");
if (!check.isAvailable) throw new Error("name taken");
 
const mind = await client.awakenMind({ name: "J-Belfort", id: "sales" });
await client.ensureConversation("main", mind.mindId);

Mindsの一覧表示

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

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

アクセストークンを使うと、listMinds() はトークンの sub を userId として GET /v1/users/{userId}/minds を呼びます。Builder APIキーは GET /v1/humans/{humanId}/minds のままです。listMinds({ humanId }) を渡すと humans のパスになります。

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 は { msg, result } を返します。

Circles

MindのCircleは、そのMindの協力者の集合です - 人間および他の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", "the.dude@hellominds.ai"],
  isActive: true,
});
console.log(added.items);
 
const removed = await client.removeCircleMembers(mindId, {
  emails: ["someone@company.com"],
});
console.log(removed.items);

人間のメールアドレスは任意のアドレス、Mindのメールアドレスは @hellominds.ai で終わります。 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 });
// rows[0] is newest. Last fingerprint → next older page (wire `before`).
const cursor = rows.at(-1)?.fingerprint;
const older = await client.getHistory("main", { cursor, limit: 50 });

getHistory は人間とMindの完全な会話履歴を 新しい順（newest-first） で返します。行には senderType （ 1 = 人間、 0 = Mind）が含まれます。SDKの cursor （および非推奨の after ）はクエリ before として送信され、排他的な次のより古いページを取得します。同じ senderType フィールドは 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 は最新メッセージのフィンガープリントを返します。これを waitForReply に afterFingerprint として渡すことで、送信後に届いた返信のみを受け入れることができます。最初の getHistory ページ（カーソルなし）はすでに最新のウィンドウです - 新しい行を期待してそのフィンガープリントを cursor として渡さないでください。

エイリアスが最後に話した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 がスローされます。アクセストークンもBuilder APIキーも無い状態で認証メソッドを呼び出すと、呼び出し時に missing_builder_api_key がスローされます。401/403は、認証情報の欠落・期限切れ・失効、またはユーザーが許可していないスコープを示します。429には再試行のガイダンスが含まれる場合があります。

メソッド

領域	メソッド
Auth	`setAccessToken`
Account	`listMinds`
Minds	`checkMindName`, `awakenMind`, `getMind`, `updateMindStatus`
Cognition	`getCognitionUsage`, `getCognitionUsageByTool`, `getCognitionBalance`
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 、 UpdateMindStatusResult 、 CheckMindNameResult 、 AwakenMindResult など）、 parseUserIdFromAccessToken 、 parseHumanIdFromBuilderApiKey は、パッケージエントリからエクスポートされます。