TL;DR
私たちは次の機能を備えたTypeScriptアプリを構築しました：
- API仕様を、機械優先のストアフロントページへ変換
- 発見（discovery）、濃縮（enrichment）、推論（inference）のプロバイダに対してタスクを動的にルーティング
- AgentCashを介して有料API呼び出しを実行
- エージェントからアウトリーチおよび要約メールを自律的に送信
- トレース付きの実行アーティファクト（プロバイダ、レイテンシ、コスト、成功）を生成
この記事では、アーキテクチャ、設計上の判断、および実装の具体的な詳細を説明します。
Problem Statement
「AIオートメーション」の多くのデモは、コンテンツ生成で止まっています。実際のエージェント型コマースには次が必要です：
- 取引（トランザクション）実行のためのレール（リクエストごとに課金）
- ターゲティングとパーソナライズのためのリアルタイムデータ
- 品質／コスト／スピードを最適化するためのマルチプロバイダ・ルーティング
- 納品の証明（実際に送信された成果物＋ログ）
私たちは、これらの制約を前提としてこのアプリを設計しました。
System Overview
Provider Strategy
AgentCash (execution + payments)
AgentCashは、支払いと実行の基幹部分です：
- エンドポイントのチェック
- 有料のfetch呼び出し
stableemail経由でのメール送信
Tavily + Bright Data (research/enrichment)
- 広くて高速なWebシグナル収集にはTavily
- MCP対応のより深いデータワークフローとWebツールにはBright Data
OpenAI + Featherless (inference layer)
- 高品質な戦略的コピーにはOpenAI
- コスト効率の良い、OpenAI互換のバルク生成にはFeatherless
この切り分けにより、すべてを単一のベンダに固定せず、各ステップごとに最適化できます。
Code Walkthrough
1) Typed env schema
Zodを使って、起動時に環境変数の正しさを強制します。
const envSchema = z.object({
DRY_RUN: z.string().optional().transform((v) => (v ?? "true").toLowerCase() === "true"),
BRIGHT_DATA_API_TOKEN: z.string().optional(),
FEATHERLESS_BASE_URL: z.string().default("https://api.featherless.ai/v1"),
FEATHERLESS_MODEL: z.string().default("meta-llama/Meta-Llama-3.1-8B-Instruct")
});
2) Capability router
ポリシー駆動のルータが、タスクの種類と戦略に基づいてプロバイダを選択します。
forResearchTask(): RouteDecision[] {
if (this.policy === "speed") {
return [
{ provider: "tavily", reason: "Fast web research baseline" },
{ provider: "agentcash", reason: "Paid enrichment calls" }
];
}
// quality / cost variants...
}
3) Featherless with OpenAI-compatible API
await fetch(`${env.FEATHERLESS_BASE_URL}/chat/completions`, {
method: "POST",
headers: {
Authorization: `Bearer ${env.FEATHERLESS_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
model: env.FEATHERLESS_MODEL,
messages: [
{ role: "system", content: "送信先に合わせた簡潔なパーソナライズ文を書きます。" },
{ role: "user", content: prompt }
]
})
});
4) メール送信の契約（contract）での落とし穴
最初はccを使いましたが、stableemail.dev/api/sendはtoを配列として検証しており、ccには対応していません。
正しいパターン:
await this.agentcash.fetch("https://stableemail.dev/api/send", {
to: ["primary@example.com", "observer@example.com"],
subject,
text
});
5) アーティファクト生成を実行
await writeFile(`output/${runId}.md`, reportMarkdown, "utf-8");
await writeFile(`output/${runId}.brightdata.mcp.json`, JSON.stringify(mcpConfig, null, 2), "utf-8");
データと制御フロー
実行してみる
npm install
cp .env.example .env
npm run dev
npm run start
確認チェックリスト
- 起動ログに、本番実行では
dryRun=falseが含まれている - 出力レポートに、有料送信の非ゼロのレイテンシがある
- AgentCashの残高が、本番実行後に減っている
- 受信トレイに、
relay@stableemail.devからのサマリーメールが届いている
得られた学び
- スキーマ優先の統合は時間を節約します。ペイロードを作る前に
agentcash checkを使ってください。 - 「プロバイダ抽象化」は、それが実際の契約（contract）の差分に対応している場合に限り有用です。
- 実行アーティファクトは信頼とデバッグに不可欠です。
- 適切な指標は「送信したメール数」だけではなく、コンバージョンと、繰り返しの有料呼び出しです。
今後の改善
- リードの状態とキャンペーンの進行状況用に永続DBを追加する
- 送信操作に冪等性キーを追加する
- プロバイダごとのサーキットブレーカーとリトライを追加する
- 実行の掘り下げ（ドリルダウン）付きUIダッシュボードを追加する
- 件名とCTAの最適化のための評価（evaluator）ループを追加する
このプロジェクトは、「AI workflow」から「エージェント的コマースエンジン」へ至る実用的な道筋を示しています。コアとなるオーケストレーションのモデルを維持したまま、チームがプロバイダを差し替えられるよう、意図的にモジュール化されています。
Github Repo: https://github.com/harishkotra/AgentCash-Commerce-Router/
