action-creator

アクションクリエイター

チャットインターフェースからワンクリックで実行できる、再利用可能なユーザー固有の操作を定義する TypeScript アクションテンプレートファイルを作成します。

このスキルを使用するタイミング

ユーザーが次のことを希望している場合に、このスキルを使用します。

• 特定のワークフローで再利用できるアクションを作成する（「ACME Corp に支払いのリマインダーを送ることがよくあります」）
• ベンダーや顧客に対するワンクリック操作を設定する（「バグをエンジニアリングチームに転送する」）
• 特定の状況に応じた、繰り返し発生するメール作業を自動化する（「TechCrunch／Morning Brew のニュースレターをアーカイブする」）
• ビジネスプロセス向けに、個別にカスタマイズしたメール管理ツールを構築する

リスナーとの主な違い：アクションはユーザーが起動（チャット内でクリック）し、リスナーはイベントが起動（自動）します。

アクションの仕組み

アクションは agent/custom_scripts/actions/ にある TypeScript ファイルで、次の内容を含みます。

1. テンプレートのメタデータとパラメータースキーマを定義する config オブジェクトをエクスポートする
2. 指定されたパラメーターを使って操作を実行する handler 関数をエクスポートする
3. ActionContext メソッドを使用して操作を行う（メール API、メールの送信、AI の呼び出しなど）

会話中にエージェントが特定のパラメーターを指定してアクションインスタンスを作成し、チャット内にクリック可能なボタンとして表示します。

アクションテンプレートの作成

1. ユーザー固有のワークフローを把握する

ユーザーのリクエストを分析し、次の点を特定します。

• ユーザーの状況：具体的なベンダー、顧客、チームはどこか？
• 操作：どのような具体的なアクションが必要か？（ACME Corp に送る、エンジニアリングチームに転送するなど）
• パラメーター：実行ごとに何が変わるか？（請求書番号、優先度、経過日数）
• 頻度：どのくらいの頻度で使用するか？

2. アクションテンプレートファイルを作成する

次の構成で agent/custom_scripts/actions/ にファイルを作成します。

import type { ActionTemplate, ActionContext, ActionResult } from "../types";

export const config: ActionTemplate = {
  id: "unique_action_id",                    // kebab-case, user-specific
  name: "Human Readable Name",                // For UI display
  description: "What this action does",       // Explain the operation
  icon: "📨",                                 // Optional emoji icon
  parameterSchema: {
    type: "object",
    properties: {
      paramName: {
        type: "string",                      // or "number", "boolean"
        description: "Parameter description",
        enum: ["option1", "option2"],        // Optional: restrict values
        default: "defaultValue"              // Optional: default value
      }
    },
    required: ["paramName"]                  // List required parameters
  }
};

export async function handler(
  params: Record<string, any>,
  context: ActionContext
): Promise<ActionResult> {
  const { paramName } = params;

  context.log(`Starting action: ${config.name}`);

  try {
    // 1. Perform operations using context methods
    // 2. Use AI for intelligent processing if needed
    // 3. Update emails, send emails, etc.

    context.notify("Action completed successfully", {
      type: "success",
      priority: "normal"
    });

    return {
      success: true,
      message: "Action completed successfully",
      data: { /* optional structured data */ },
      refreshInbox: true  // Optional: refresh inbox after action
    };
  } catch (error: any) {
    context.log(`Action failed: ${error}`, "error");
    return {
      success: false,
      message: `Failed: ${error.message}`
    };
  }
}

3. ファイルの命名規則

ユーザー固有の操作内容がわかる kebab-case の名前を使用します。

• send-payment-reminder-to-acme.ts（send-email.ts ではなく）
• forward-bugs-to-engineering.ts（forward-email.ts ではなく）
• archive-newsletters-from-techcrunch.ts（archive-emails.ts ではなく）
• summarize-weekly-updates-from-ceo.ts（summarize-emails.ts ではなく）

重要：テンプレートは、ユーザーが実際に行うワークフロー、ベンダー、チーム、プロセスに合わせて作成してください。

4. 利用可能なコンテキストメソッド

ActionContext では次の機能を利用できます。

// Email API operations
const emails = await context.emailAPI.getInbox({ limit: 30, includeRead: false });
const results = await context.emailAPI.searchEmails({ from: "[email protected]" });
const results = await context.emailAPI.searchWithGmailQuery("from:sender after:2024/01/01");
const emails = await context.emailAPI.getEmailsByIds(["id1", "id2"]);
const email = await context.emailAPI.getEmailById("email-id");

// Direct email operations
await context.archiveEmail(emailId);
await context.starEmail(emailId);
await context.unstarEmail(emailId);
await context.markAsRead(emailId);
await context.markAsUnread(emailId);
await context.addLabel(emailId, "label-name");
await context.removeLabel(emailId, "label-name");

// Send emails
const result = await context.sendEmail({
  to: "[email protected]",
  subject: "Email subject",
  body: "Email body content",
  cc: "[email protected]",           // Optional
  bcc: "[email protected]",          // Optional
  replyTo: "[email protected]"     // Optional
});

// AI-powered processing
const analysis = await context.callAgent<ResultType>({
  prompt: "Analyze this email and extract key info...",
  systemPrompt: "You are an expert at...",  // Optional
  tools: ["Read", "WebSearch"],              // Optional
  maxTokens: 2000                            // Optional
});

// Session messaging (inject into chat)
context.addUserMessage("User said this");
context.addAssistantMessage("Assistant responds");
context.addSystemMessage("System notification");

// Notifications
context.notify("Operation completed", {
  priority: "high" | "normal" | "low",
  type: "info" | "success" | "warning" | "error"
});

// External API access
const response = await context.fetch("https://api.example.com/data");
const data = await response.json();

// Logging (visible in server logs)
context.log("Info message", "info");
context.log("Warning message", "warn");
context.log("Error message", "error");

アクションの結果

必ず ActionResult オブジェクトを返します。

return {
  success: true,                          // Required: boolean
  message: "Human-readable result",       // Required: string
  data: { key: "value" },                // Optional: structured data
  suggestedActions: [],                   // Optional: follow-up actions
  refreshInbox: true                      // Optional: refresh inbox
};

例とテンプレート

一般的なパターンについては、テンプレートファイルを参照してください。

• send-payment-reminder.ts：特定のベンダーに請求書のリマインダーを送信します
• forward-bug-report.ts：AI による分析を加えて、バグをエンジニアリングチームに転送します
• archive-old-newsletters.ts：特定の配信元からのニュースレターをアーカイブします

ベストプラクティス

1. ユーザー固有のテンプレート：ユーザーが実際に利用するベンダー、顧客、チーム、プロセスに合わせてテンプレートを作成する
2. わかりやすい命名：「send-email」のような一般的な名前ではなく、操作内容がわかる具体的な名前を使用する
3. 充実したパラメータースキーマ：説明付きで明確なパラメーター型を定義する
4. AI の活用：インテリジェントな処理には context.callAgent() を使用する
5. エラー処理：操作は必ず try-catch で囲み、意味のあるエラーを返す
6. 明確なメッセージ：人が理解しやすい成功／失敗メッセージを返す
7. 冪等性：可能な場合は、安全に再実行できるようハンドラーを設計する
8. ログ記録：デバッグと監査証跡には context.log() を使用する

パラメータースキーマのガイドライン

JSON Schema を使ってパラメーターを定義します。

parameterSchema: {
  type: "object",
  properties: {
    // String parameter
    emailId: {
      type: "string",
      description: "Email ID to process"
    },

    // Number parameter with default
    daysOld: {
      type: "number",
      description: "Number of days old",
      default: 30
    },

    // Enum parameter (dropdown)
    priority: {
      type: "string",
      description: "Priority level",
      enum: ["P0 - Critical", "P1 - High", "P2 - Medium", "P3 - Low"]
    },

    // Boolean parameter
    sendNotification: {
      type: "boolean",
      description: "Send notification when complete"
    }
  },
  required: ["emailId", "priority"]  // List required params
}

ファイルの作成

ユーザーがアクションテンプレートをリクエストした場合：

1. ユーザー固有のコンテキストを確認します：

   • 取引先、顧客、チームはどこですか？
   • 具体的なワークフローはどのようなものですか？
   • 実行ごとに変わるパラメーターは何ですか？

2. agent/custom_scripts/actions/ に TypeScript ファイルを作成します

3. Write ツールを使って、次の内容でファイルを作成します：

   • "../types" から適切なインポートを行います
   • ユーザー固有の設定を使用します（汎用的な設定は使用しません）
   • 必須フィールドをすべて含むパラメータースキーマを定義します
   • エラー処理を含むハンドラーを用意します
   • 成功・失敗を明確に伝えるメッセージを設定します

4. パラメーターをテストします：必須パラメーターがすべて定義されていることを確認します

5. アクションがユーザーのワークフローに合っていることを確認します

一般的なパターン

1. 特定の宛先へのメール送信

ユーザー固有の内容 → テンプレートを使ってメールを作成 → 送信 → 結果を返す

const body = `Hi ${recipientName},
Your invoice ${invoiceNumber} for ${amount} is ${daysPastDue} days past due...`;

await context.sendEmail({
  to: "[email protected]",
  subject: `Payment Reminder: Invoice ${invoiceNumber}`,
  body
});

2. 一括メール操作

メールを検索 → 絞り込む → 各メールに操作を適用 → 件数を返す

const emails = await context.emailAPI.searchWithGmailQuery(query);
for (const email of emails) {
  await context.archiveEmail(email.messageId);
}
return { success: true, message: `Archived ${emails.length} emails` };

3. AI を活用したメール処理

メールを取得 → AI を呼び出して分析 → AI の結果を使用 → アクションを実行 → 概要を返す

const email = await context.emailAPI.getEmailById(emailId);
const analysis = await context.callAgent({
  prompt: `Analyze this bug report: ${email.body}...`,
  maxTokens: 1000
});
await context.sendEmail({ to: "[email protected]", ... });

4. 強化処理を伴うメール転送

メールを取得 → AI で分析 → 内容を強化した転送メールを作成 → 送信 → 元のメールにラベルを付ける

const email = await context.emailAPI.getEmailById(emailId);
const analysis = await context.callAgent({ /* analyze */ });
await context.sendEmail({
  to: "[email protected]",
  subject: `[${priority}] ${email.subject}`,
  body: `AI Analysis:\n${analysis}\n\nOriginal:\n${email.body}`
});
await context.addLabel(emailId, "FORWARDED");

型のインポート

常に正しい場所から型をインポートしてください：

import type { ActionTemplate, ActionContext, ActionResult } from "../types";

// ActionTemplate: Template metadata and parameter schema
// ActionContext: Runtime context with all capabilities
// ActionResult: Return type for handler function

ユーザーがアクションを実行する方法

アクションテンプレートを作成した後：

1. エージェントがテンプレートを検出します：会話中に、エージェントが利用可能なアクションを読み取ります
2. エージェントがインスタンスを作成します：エージェントがユーザーの状況に応じた具体的なパラメーターを指定します
3. ユーザーにボタンが表示されます：アクションインスタンスがチャット内にクリック可能なボタンとして表示されます
4. ユーザーがクリックします：事前入力されたパラメーターを使ってアクションが実行されます
5. 結果が表示されます：成功・失敗のメッセージがチャットに表示されます

実行例：

User: "I need to follow up on the ACME invoice"
Agent: [searches emails, finds Invoice #2024-001 is 15 days overdue]
Agent: Creates action instance with parameters:
  {
    templateId: "send_payment_reminder_acme",
    params: { invoiceNumber: "INV-2024-001", amount: "$5,000", daysPastDue: 15 }
  }
User: [sees button "Send payment reminder to ACME Corp for Invoice #2024-001"]
User: [clicks button]
Action: Executes, sends email, returns "Payment reminder sent to ACME Corp"

参考資料

完全な仕様については、プロジェクトルートにある ACTIONS_SPEC.md を参照してください。次の詳細が記載されています：

• 型定義の全体
• ActionsManager の実装
• WebSocket プロトコル
• フロントエンドとの統合
• 高度な例
• ログ記録と監査証跡