クイックスタート

概要

この2ステップ・ガイドに従って、エージェントのプロビジョニング、設定および実行を行います。

ステップ1: OCIコンソールでのエンドポイントを含むエージェントのプロビジョニング

このステップでは、OCIコンソールで、エージェントのエージェント・インスタンスおよびエンドポイントを作成します。このエージェントにツールを追加する必要はありません。このステップはインフラストラクチャの設定に関するもので、OCIコンソールを使用して設定します。また、OCI SDKまたはTerraformを使用して、エージェント・インスタンスとそのエンドポイントを作成することもできます。

ノート: エージェント・インスタンスの構成手順またはツールについては、ステップ2で説明します。

ステップ2: ADKを使用したエージェントの構成および実行

このステップでは、ADKを使用してエージェントを設定および実行します。エージェントを設定するために、指示およびツールをローカルで反復できます。エージェントがローカルに設定されたら、agent.setup()メソッドを実行して、エージェント情報をリモート・エージェント・インスタンスにプッシュします。実行中のエージェントの場合、agent.run()メソッドを実行して、セッションの管理、ファンクションの検索および呼出しなどの低レベルのクライアント/サーバー相互作用を処理するためのコードを記述しなくても、リクエストを処理します。

前提条件

• 権限: OCIアカウントがあり、アイデンティティがOCI生成AIエージェント・サービスにアクセスできることを確認します。必要なポリシーを設定し、アクセス権を付与するようOCI管理者に依頼する必要がある場合があります。

• リージョン: OCI生成AIエージェント・サービスをサポートするリージョン(us-chicago-1、eu-frankfurt-1、ap-osaka-1など)を使用していることを確認します。次の両方のステップで同じリージョンを使用する必要があります。

ステップ1: エージェント・エンドポイントのプロビジョニング

このガイドに従って、OCIコンソールを使用して、次の詳細を含むエージェント・インスタンスおよびエージェント・エンドポイントを作成します:

• OCIコンソールからツールを追加しないでください。

• エージェント・エンドポイントを取得するには、「このエージェントのエンドポイントを自動的に作成」チェック・ボックスを選択したままにします。

• エージェントの作成後、エージェント・エンドポイントのID (OCID)をコピーして、次のステップのメモ帳に貼り付けます。

開発しているエージェントごとに、このステップを1回のみ実行する必要があります。

---

ノート: このステップでは、OCIコンソールからツールを追加しません。

かわりに、次のステップでは、ADKを使用してツールをローカルに設定します。次に、ADKを使用して、ローカル・ツールとリモート・エージェント・インスタンスを自動的に同期します。目的は、ADKを使用して、ファンクション・スキーマと、ファンクション・コールを処理する実際のコール可能オブジェクトを含むツールに対して信頼できる唯一の情報源を使用できることです。

---

このステップでは、クラウドでエージェント・インスタンスおよびエージェント・エンドポイントをプロビジョニングします。このエージェント・エンドポイントは、ADKが接続するLLM APIエンドポイントのように考えてください。ただし、エージェント動作、事前登録済ツールによって拡張され、アプリケーション専用です。ステップ2で、ADKエージェント・オブジェクトをこのエージェント・エンドポイントに接続します。

ステップ2: エージェントの構成と実行

仮想環境でプロジェクトを作成します。

# Create a project folder with name of your choice
mkdir <your-project-name>
cd <your-project-name>

# Create and activate a virtual environment under `<myenv>` subfolder
python -m venv <myenv>
source <myenv>/bin/activate

Python ADKにはPython 3.10以降が必要です。環境に正しいバージョンのPythonがインストールされていることを確認してください。

ADKのインストール

プロジェクトおよび仮想環境を作成した後、最新バージョンのADKをインストールします。

pip install "oci[adk]"

---

ヒント: "connection to pypi.org timed out"エラーが返されましたか?

pip installコマンドの実行時に前述のエラーが発生した場合は、ネットワークの問題が原因である可能性があります。VPNから切断して、コマンドを再実行してください。

---

OCIへのADKアプリケーションの認証

ADKには、エージェント・リソースの認証および管理を簡略化するAgentClientクラスが用意されています。次の4つの認証タイプがサポートされています。

APIキー認証(デフォルト)

APIキー認証は、OCIサービスで認証するためのデフォルトの最も一般的な方法です。

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="api_key",
    profile="DEFAULT",
    region="<your-region>"  # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

APIキー認証を設定するには、OCI APIキー設定ガイドに従います。

セキュリティ・トークン認証

セキュリティ・トークン認証では、OCIサービスを使用するためのADKの認証に使用できる一時セッション・トークンが作成されます。この方法は、通常、ローカル・テストで使用されます。

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="security_token",
    profile="DEFAULT",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

CLIセッションを認証するには、端末で次のコマンドを実行します。プロファイル名とリージョンを値に置き換えます。

oci session authenticate --auth security_token --profile-name DEFAULT --region <your-region>

認証に成功すると、同じ端末から実行されているADKアプリケーションも認証されます。

インスタンス・プリンシパル認証

OCIコンピュート・インスタンスにはインスタンス・プリンシパル認証をお薦めします。

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="instance_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

リソース・プリンシパル認証

FunctionsなどのOCIリソースには、リソース・プリンシパル認証をお薦めします。

from oci.addons.adk import AgentClient

client = AgentClient(
    auth_type="resource_principal",
    region="<your-region>" # OCI region such as "us-chicago-1" or airport code such as "ORD"
)

認証されているユーザーに、OCI生成AIエージェント・サービスを使用する権限があることを確認します。

エージェントを構成および実行しています

エージェント・エンドポイントがアクティブになったら、ADKを使用して次の単純な天気エージェントの例を設定して実行できます。

プロジェクト・ルートにquickstart.pyという名前のファイルを作成し、次のコードをファイルにコピーします。

quickstart.py

from typing import Dict
from oci.addons.adk import Agent, AgentClient, tool

# Use @tool to signal that this Python function is a function tool.
# Apply standard docstring to provide function and parameter descriptions.
@tool
def get_weather(location: str) -> Dict[str, str]:
    """
    Get the weather for a given location.

    Args:
      location(str): The location for which weather is queried
    """
    return {"location": location, "temperature": 72, "unit": "F"}


def main():
    # Create an agent client with your authentication and region details
    # Replace the auth_type with your desired authentication method.
    client = AgentClient(
        auth_type="api_key",
        profile="DEFAULT",
        region="us-chicago-1",
    )

    # Create a local agent object with the client, instructions, and tools.
    # You also need the agent endpoint id. To obtain the OCID, follow Step 1.
    agent = Agent(
        client=client,
        agent_endpoint_id="<your-agent-endpoint-OCID>",
        instructions="You perform weather queries using tools.",
        tools=[get_weather]
    )

    # Sync local instructions and tools to the remote agent resource
    # You only need to invoke setup() when you change instructions and tools
    agent.setup()

    # Run the agent. You can embed this method in your webapp, slack bot, etc.
    # You invoke the run() when you need to handle your user's request.
    input = "Is it cold in Seattle?"
    response = agent.run(input)

    # Print the response
    response.pretty_print()

if __name__ == "__main__":
    main()

スクリプトを実行します。

次に、quickstart.pyスクリプトを実行すると、次のような出力が表示されます。

これで、ADKをローカルで実行し、OCI上のエージェント・エンドポイントへのアウトバウンド接続を使用して、単純な天気エージェントを使用できるようになりました。

---

ノート: エージェント・エンドポイントが必要な理由は何ですか。リモート・エージェント・エンドポイントなしでADKをローカルで使用できますか。

ADKでは、クライアント側のエージェント・フレームワークにLLMエンドポイントが必要な場合と同様に、エージェント・エンドポイントが機能する必要があります。エージェント・エンドポイントは、最適化された推論プロンプトやOCIのサーバーサイド・ツールなど、高度なエージェント機能を提供する拡張LLMエンドポイントと考えてください。ADKでは、RAW LLMエンドポイントへの直接接続はサポートされていません。

---

このエージェントには、実装したローカル・カスタム関数ツールget_weatherが装備されています。エージェントは、自然言語で表現されたユーザーのリクエストを処理する準備ができています。

バックグラウンドでは、ADKは低レベルのクライアント/サーバー・オーケストレーションを処理しますが、エージェント・エンドポイントはコア・エージェント・ループの実行、LLMとの通信、およびRAGツール(このクイックスタートでは実装されていない)などの他のホスト・ツールの起動を処理します。

機能

通常、ADKコードは大規模なアプリケーションに埋め込まれ、環境にデプロイされます。より大きなアプリは、Webアプリ、Slackbot、サービス、またはスクリプトです。

ADKファンクション・ツールを使用すると、環境に固有の認証を使用して、エージェントをローカル・コードベース、リモート・データベース、リモート・マイクロサービスなどと統合できます。

ADKは、OCI生成AIエージェント・サービスによって公開されるエージェント・エンドポイントをコールします。これにより、エージェント・ループが環境にリモートで実行されます。

エージェント・ループがホスト・ツール(RAGツールなど)をコールすると、そのコールはADKに戻ることなく実行されます。

エージェント・ループがローカル機能ツールの呼出しを決定すると、制御はADKに戻されます。ADKはローカル・ファンクション・ツールをコールし、ファンクション・ツール出力を生成AIエージェントに戻し、エージェント・ループの次の反復を続行します。

次のステップ

• エージェント機能ツールの例の確認
• 他の例を見る
• ベスト・プラクティスのレビュー
• OCI Generative AI Agentsのドキュメントを読む