エージェントをビルドする¶

エージェントの構造¶

エージェントは以下の部分で構成されます。

• エージェントの動作の基盤を提供するベースモデル

• 意図を解釈し、適切なツールを選択し、一連のアクションを計画するモデル（オーケストレーター）

• エージェントの動作の指示

• エージェントが使用するツール

• ツールのリソース

以下のセクションでは、モデルの選択とツール構成について説明します。この例では、セマンティックビュー、Cortex Search Service、カスタムツールを使用して回答を提供します。これらのツールを使用しない基本的なエージェントを作成することはできますが、その基本的なエージェントが回答の提供のために使用できるのはベースモデルのみです。その結果、エージェントはSnowflakeアカウント内のデータにアクセスできず、回答のためのコンテキストが限られます。

エージェントの他のコンポーネントについて詳しくは、:doc:`/user-guide/snowflake-cortex/cortex-agents`を参照してください。

前提条件¶

Cortex Agentを作成するには、次の権限を持つロールを使用する必要があります。

次のコードは、Cortex Agentの作成に必要な権限を付与するものです。

GRANT USAGE ON DATABASE <database_name> to ROLE <role_name>;
GRANT USAGE ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;
GRANT CREATE AGENT ON SCHEMA <database_name>.<schema_name> to ROLE <role_name>;

Copy

Cortex Agentの作成に必要な権限に加えて、エージェントを特定のツールに接続するには以下の前提条件が必要です。

• エージェントに接続するためのセマンティックビュー

  セマンティックビューの作成について詳しくは、:doc:`/user-guide/views-semantic/overview`を参照してください。

• エージェントに接続するためのCortex Analystツール

  Cortex Analystツールの作成について詳しくは、:doc:`/user-guide/snowflake-cortex/cortex-analyst`を参照してください。

• エージェントに接続するためのデータベース内の非構造化データ

• エージェントに接続するためのCortex Searchツール

  Cortex Searchツールの作成について詳しくは、:doc:`/user-guide/snowflake-cortex/cortex-search/cortex-search-overview`を参照してください。

• エージェントに接続するためのカスタムツール

  カスタムツールとして使用するユーザー定義関数（UDFs）およびストアドプロシージャの作成について詳しくは、:doc:`/developer-guide/extensibility`を参照してください。

エージェントにツールをアタッチするには、エージェントの作成に使用されるロールに以下の権限が必要です。

エージェント構成の基本¶

エージェントを作成するときは、名前、説明、モデルなど、エージェントに関する情報を指定する必要があります。また、エージェントが使用できるツールや、エージェントがアクセスできるリソースを指定することもできます。これらのリソースは、:code:`CREATE AGENT`コマンドの:code:`FROM SPECIFICATION`句におけるYAML仕様として渡されます。

以下の推奨事項は、この構成のベストプラクティスを示しています。

**エージェントのスコープを絞り込む：**ツールを追加したり手順を記述したりする前に、エージェントが存在する理由、サービスを提供する対象、答える必要がある具体的な質問を定義します。このステップによって、ツールの選択からパフォーマンスと信頼に至るまで、これ以降のすべてが形成されます。Snowflakeでは、エージェントのスコープを特定の価値の高いユースケースに絞り込むことを推奨しています。

エージェントが1つの領域で信頼できることが証明された後で、他の領域でもそのパターンを複製できます。例えば、あるエージェントに店舗の最近の売上とマーケティングデータを分析させ、別のエージェントに小売業者に提案する最適なSKUsを推奨させることができます。

**ツールの数を慎重に選択する：**すべてのエージェントが必要なツールにのみアクセスできるようにする必要があります。それを判断するには、エージェントがその目的を果たすために必要なドキュメントまたはデータを検討します。エージェントが非構造化データにアクセスする必要がある場合は、/user-guide/snowflake-cortex/cortex-search/cortex-search-overview`を使用します。エージェントが構造化データにアクセスする必要がある場合は、:doc:/user-guide/snowflake-cortex/cortex-analyst`を使用します。エージェントに他のツールが必要な場合は、カスタムツールを使用できます。

**役立つツールの説明を記述する：**これらの説明は、エージェントがそのツールの機能や使用方法を理解するのを助けるために使用されます。ツールの説明が不明確な場合は、連鎖的な障害が発生し、「ハルシネーション」につながる可能性があります。

役立つツールの説明を作成するには、以下のガイドラインに従ってください。

• ツールのドメイン（「顧客」、「売上」）と機能（「分析」、「検索」）を明確にする、明確で具体的なツール名を追加します。

• エージェントに以下を伝える、目的主導なツールの説明を記述します。

  • ツールの機能

  • ツールがアクセスするデータ

  • ツールを使用するべきタイミング

  • ツールを使用するべきではないタイミング

• ツールへの期待される入力について明確に説明してください。ツールへのあいまいな入力は、ツールの誤った呼び出しやエラーにつながります。

  • 具体的に説明する。

  • データ形式を指定する。

  • 明確なデータの指示を提供する。

  • デフォルトのガイダンスを提供する。

  • 一貫した用語を使用する。

エージェント構成の推奨事項について詳しくは、`Cortex Agent構築のベストプラクティス<https://www.snowflake.com/en/developers/guides/best-practices-to-building-cortex-agents/>`_を参照してください。

モデル選択¶

エージェントを作成するときは、モデルに:ui:`auto`を選択することをお勧めします。このオプションを使用すると、Cortexは自動的にアカウントの最高品質のモデルを選択し、新しいモデルが利用可能になると自動的に品質が向上します。利用可能なモデルについて詳しくは、:ref:`label_snowflake_intelligence_models`を参照してください。

次の例は、エージェントのモデルを指定する方法を示しています。

models:
  orchestration: auto

ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';

Cortex Analystを使用してセマンティックビューを接続する（構造化データ）¶

Snowflake Intelligenceはセマンティックビューをサポートしています。これは、エージェントにデータのクエリや解釈の方法を伝える指示を含む構造化データの一種です。Cortex AgentはCortex Analystを使用して、自然言語リクエストをSQLクエリに変換することで、セマンティックビューから構造化データを取得します。Agentは、複数のセマンティックビューにルーティングして応答を提供できます。

各セマンティックビューは、同様のテーブルセットをカバーする必要があります。指定されていない場合は常に過去3か月の日付フィルターを追加したり、内部アカウントを常に除外したりするなど、データ固有のデフォルトを設定できます。

ツールリソースの一部としてセマンティックビューを指定することで、セマンティックビューをエージェントに接続できます。次の例は、セマンティックビューをエージェントに接続する方法と、Cortex Analystツールを指定してセマンティックビューから構造化データを取得する方法を示しています。

tools:
  - tool_spec:
      type: "cortex_analyst_text_to_sql"
      name: "<your cortex analyst tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex analyst tool name>:
    semantic_view: "<db>.<schema>.<semantic_view>"

Cortex Searchを接続する（非構造化データ）¶

非構造化データを処理するには、YAML仕様においてCortex Searchツールをツールリソースの一部として指定することで、Cortex Searchツールをエージェントに接続できます。Cortex Search Serviceは、セマンティック検索を使用して非構造化データソースからドキュメントと記録を取得します。Cortex Searchの2つの主なユースケースは、検索拡張世代（RAG）とエンタープライズ検索です。Cortex Search Serviceの作成については、 Cortex Search をご参照ください。共有されているCortexナレッジ拡張機能（CKE）も使用できます。

Cortex Searchツールをエージェントに接続する場合は、パラメーターとその期待値に関する次の情報を含めることが特に重要です。

• 型と形式（例を含む）

• 必須かオプションか（デフォルト値と合わせて）

• 有効な値または制約（列挙、範囲、形式）

• 他のパラメーターとの関係（依存関係、競合）

• 値の取得方法（特にIDsについて）

次の例は、Cortex Searchツールをエージェントに接続する方法と、YAML仕様においてCortex Searchツールを指定する方法を示しています。

tools:
  - tool_spec:
      type: "cortex_search"
      name: "<your cortex search tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your cortex search tool name>:
    name: "<db>.<schema>.<search_service_name>"
    max_results: "5"
    filter:
      "@eq":
        region: "North America"
    title_column: "<title_name>"
    id_column: "<column_name>"

カスタムツールを追加する¶

Snowflake Intelligenceはカスタムツールをサポートしています。これは、カスタムビジネスロジックの実装に使用できるユーザー定義関数またはストアドプロシージャです。YAML仕様においてカスタムツールをツールリソースの一部として指定することで、カスタムツールをエージェントに接続できます。

次の例は、カスタムツールをエージェントに接続する方法と、YAML仕様においてカスタムツールを指定する方法を示しています。

tools:
  - tool_spec:
      type: "custom_tool"
      name: "<your custom tool name>"
      description: "<clear and specific tool description>"

tool_resources:
  <your custom tool name>:
    user-defined-function-argument: "argument1"

エージェントの作成¶

• すべてのツールとコンポーネントを組み合わせ、SQLを使用してエージェントを作成します。

  CREATE OR REPLACE AGENT <agent_name>
      COMMENT = 'agent level comment'
      PROFILE = '{"display_name": "My Business Assistant", "avatar":  "business-icon.png", "color": "blue"}'
      FROM SPECIFICATION
      $$
      models:
      orchestration: claude-4-sonnet
  
      orchestration:
      budget:
          seconds: 30
          tokens: 16000
  
      instructions:
      response: "You will respond in a friendly but concise manner"
      orchestration: "For any revenue question, use Analyst; for policy questions, use Search"
      system: "You are a friendly agent that helps with business questions"
      sample_questions:
          - question: "What was our revenue last quarter?"
          answer: "I'll analyze the revenue data using our financial database."
  
      tools:
      - tool_spec:
          type: "cortex_analyst_text_to_sql"
          name: "<your cortex analyst tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "cortex_search"
          name: "<your cortex search tool name>"
          description: "<clear and specific tool description>"
      - tool_spec:
          type: "data_to_chart"
          name: "data_to_chart"
          description: "Generates visualizations from data"
  
      tool_resources:
      <your cortex analyst tool name>:
          semantic_view: "<db>.<schema>.<semantic_view>"
      <your cortex search tool name>:
          name: "<db>.<schema>.<search_service_name>"
          max_results: "5"
          filter:
          "@eq":
              region: "North America"
          title_column: "<title_name>"
          id_column: "<column_name>"
      $$;
  

  Copy

既存のエージェントを変更する¶

ツールの追加やその他の詳細の更新など、既存のエージェントの構成を変更する手順については、ツールを追加する をご参照ください。