エージェント (Agent)

概要 (What is it?)

Agent（エージェント）ノードを使用すると、ツールやルールセットなどのカスタマイズ可能な機能を備えた AI エージェントを設定できます。このノードは、自身のプロンプトを指定して即座に実行するエージェントを作成することも、他のノードの "agent" 入力ピンに渡すエージェントオブジェクトを構築することもできます。

使用する場面 (When would I use it?)

以下のような場面でこのノードを使用します：

設定可能な AI エージェントをゼロから作成したい場合
特定のツールやルールセットをエージェントに装備させたい場合
ワークフロー全体で再利用可能なエージェントを用意したい場合
カスタムプロンプトを使用してエージェントから即時レスポンスを取得したい場合

使い方 (How to use it)

基本セットアップ

ワークフローに Agent ノードを追加します
エージェントの機能（ツールやルールセット）を設定します

パラメータ一覧 (Parameters)

agent: 既存のエージェント設定（オプション）。指定した場合、プロンプト実行時に既存のエージェントインスタンスが使用されます。
provider: 使用する AI プロバイダ（例: Griptape Cloud、Ollama、LM Studio、またはカスタムエンドポイント）。セットアップ手順については AI プロバイダを参照してください。
prompt model: 選択したプロバイダで利用する特定のモデル。
prompt: エージェントに依頼する指示または質問。
additional_context: エージェントに提供する追加のコンテキスト（文字列または Key-Value ペア）。
tools: エージェントに付与したい機能・ツール。
rulesets: エージェントの実行可能な操作および禁止事項を定義するルール。
output_schema: エージェントのレスポンスが準拠すべき正確なフォーマットを定義する JSON Schema テンプレート（オプション）。

出力 (Outputs)

output: エージェントからのテキスト応答（プロンプトが指定されている場合）
agent: 設定されたエージェントオブジェクト（他のノードの入力ピンに接続可能）

使用例 (Example)

プロンプトコンテキストに基づいて俳句（haiku）を詠むエージェントを作成する例：

KeyValuePair ノードを追加します
"key" を "topic" に、"value" を "swimming" に設定します
Agent ノードを追加します
Agent の "prompt" を "Write me a haiku about {{topic}}" に設定します
KeyValuePair の辞書出力を Agent の "prompt_context" 入力に接続します
ワークフローを実行します
Agent の "output" に水泳に関する俳句が出力されます！

出力スキーマの活用 (Using Output Schemas)

出力スキーマとは？

出力スキーマは、AI に記入してもらう「フォーム」のようなものだと考えてください。自由記述のテキスト応答を受け取る代わりに、必要な情報の項目とそれらの構造を正確に指定できます。

例えば、「この製品について教えて」と尋ねてテキストの段落を受け取る代わりに、以下のような項目を指定して受け取ることができます：

製品名（テキスト）
価格（数値）
在庫状況（はい/いいえ）
主な機能の一覧（複数のテキスト項目）

これにより、AI は要求された仕様に完全に一致する構造化データで応答します。

出力スキーマを使用するメリット

以下のような要件がある場合に役立ちます：

一貫したフォーマット: すべてのレスポンスが同じ構造に従うため、後続の処理が容易になります
特定のデータ型の保証: 数値が必要な場所には数値、リストが必要な場所にはリストが確実に返されます
自動化の円滑化: 構造化データは、ワークフロー内の他のノードへの受け渡しが非常にスムーズです
バリデーション（検証）: AI はすべての必須フィールドを正しいフォーマットで提供する必要があります

出力スキーマの作成方法

ワークフローに JSON Input ノードを追加します
目的の出力を定義する JSON Schema を記述・追加します（作成を支援するオンラインツールも利用可能です）

出力スキーマの例

レビュー文からレストランの情報を抽出したい場合の例：

スキーマフィールドを作成：
- フィールド "restaurant_name" (type: string)
- フィールド "rating" (type: integer)
- フィールド "price_range" (type: string)
- フィールド "cuisine_type" (type: string)
- フィールド "recommended_dishes" (type: list, list_type: string)
すべてのフィールドを Create Schema ノードに接続します
スキーマを Agent の output_schema 入力に接続します
Agent のプロンプトを「以下のレビューからレストランの情報を抽出してください: [レビューテキスト]」と設定します
Agent はプレーンテキストの代わりに、指定されたフィールドを正確に含んだ構造化データで応答します
生成されるスキーマは次のようになります：

{
  "type": "object",
  "properties": {
    "restaurant_name": { "type": "string" },
    "rating": { "type": "integer" },
    "price_range": { "type": "string" },
    "cuisine_type": { "type": "string" },
    "recommended_dishes": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["restaurant_name", "rating", "price_range", "cuisine_type", "recommended_dishes"]
}

スキーマ使用時の挙動の変化

出力タイプ: エージェントの出力がプレーンテキストから構造化データ (JSON フォーマット) に変わります
バリデーション: 要求されたフォーマットでデータを提供できない場合、AI は再試行するかエラーを返します

重要な注意点 (Important Notes)

プロンプトを指定しない場合、ノードはエージェントを実行せずに作成のみを行い、output には "Agent Created" と正確に出力されます
ノードはストリーミングおよび非ストリーミングの両方のプロンプトドライバをサポートします
ツールおよびルールセットは、個別の項目としてもリストとしても提供できます
additional_context パラメータにより、文字列または Key-Value ペアの辞書としてエージェントに追加コンテキストを渡せます
デフォルトでは Griptape Cloud を使用するため、有効な GT_CLOUD_API_KEY が必要です。provider パラメータを使用してローカルまたはカスタムプロバイダに切り替えることができます（詳細は AI プロバイダを参照）。
エージェントの入出力ピンを使用してあるノードから別のノードへエージェントを受け渡すと、対話履歴（会話メモリ）が維持されます。つまり：
- エージェントは同じフロー内の過去のやり取りを「記憶」しています
- 過去のプロンプトのコンテキストが、新しいプロンプトの解釈に影響を与えます
- 複数のノードにまたがるマルチターンの対話を構築できます
- ワークフローの前のステップで提供された情報をエージェントが参照できます
output_schema パラメータ用の JSON Schema の書き方がわからない場合は、JSON Schema Builder などのオンラインツールを使用して目的の構造を定義できます。あるいは、エージェントに欲しい出力例を提示してスキーマを生成させることも可能です！

ワークフロー内でのエージェントの挙動制御 (Controlling Agent Behavior in Workflows)

ワークフロー内でエージェントの振る舞いを調整するには、Rulesets（または Behaviors (Rulesets) 入力に接続されたプレーンな TextInput）を使用します。これにより、エージェントが実行できることや禁止すること、ペルソナの設定、出力スタイルの制限などを定義できます。

Agent ノードでは Skills はサポートされていません

チャットサイドバーで使用される .agents/skills フォルダは、ワークフロー内の Agent ノードには適用されません。エージェントの振る舞いを制御するには、代わりに Ruleset ノード または Agent の Behaviors (Rulesets) 入力に接続した TextInput を使用してください。

よくある問題 (Common Issues)

プロバイダが設定されていない: プロバイダが設定されていない場合、ノードはデフォルトで Griptape Cloud を使用するため、有効な GT_CLOUD_API_KEY が必要になります。Ollama、LM Studio、またはカスタムエンドポイントを追加するには AI プロバイダを参照してください。
ストリーミングの問題: ストリーミングプロンプトドライバを使用している場合、フローがストリーミング出力を適切に処理できる構成になっているか確認してください。