はじめに
本稿では、OCI Generative AI Agents PlatformサービスをOCIエージェント開発キット(ADK：Agent Development Kit)を使って触ってみた記録と、躓きポイントを共有いたします。
本稿の記述は、2025年12月7日時点のOCI TokyoおよびChicagoリージョンでの実機検証結果を根拠としています。最新の情報については、必ず公式ドキュメントをご参照ください。
2025年の3月にOracle Cloud Infrastructure（OCI）AIエージェント・プラットフォームがGAされた
2025年の3月に、OCI Generative AI Agents Platform(以下AI Agents Platform)がGAとなりました。
Announcing the General Availability of OCI Generative AI Agents Platform
https://blogs.oracle.com/ai-and-datascience/ga-of-oci-gen-ai-agent-platform
GA以前にもOCI Generative AI Agentsサービス自体は存在していましたが、顧客体験の向上と生産性の改善のため、より高度なAIエージェントを構築、展開、管理するためのフルマネージドサービスとして機能拡張が行われました。
AI Agents Platformの主要な機能
※Announcing the General Availability of OCI Generative AI Agents Platformより著者整理
| 機能カテゴリー | 機能 | 概要 |
|---|---|---|
| エージェントの構築とデプロイ | シームレスなセットアップとデプロイメント | 効率性とスケーラビリティのために設計された、完全に管理されたクラウドネイティブソリューションを提供し、エージェントのセットアップとデプロイメントを合理化します。技術ユーザーが必要な柔軟性と制御を維持しつつ、最新のワークフローをサポートします。 |
| ツールオーケストレーション | 複数のツールやサービスをオーケストレーションし、複雑なワークフローを作成し、会話を自動化します。エージェントがツールをシームレスに統合および実行できるようにする、柔軟でスケーラブルなオーケストレーションを可能にします。 | |
| 対話能力と制御 | マルチターンチャット体験 | エージェントとユーザーの間でダイナミックな会話を可能にし、エージェントが複数のやり取りにわたる対話を実行できるようにすることで、より人間味のあるインタラクティブな体験を提供します。 |
| コンテキスト保持 | マルチターンチャットからの会話ターン全体でコンテキストを記憶し、ダイアログとともに進化する、パーソナライズされ一貫性のある対話を可能にします。 | |
| カスタム指示 | 特定の指示を提供することで、エージェントがさまざまな状況でどのように応答し、実行するかをガイドし、エージェントの振る舞いを微調整します。 | |
| ガードレール | エージェントが安全で信頼性の高い対話を維持できるように境界を設定し、ビジネスおよび倫理基準に沿って責任を持って動作するのを支援します。 | |
| ヒューマン・イン・ザ・ループ | 精度、正確性、およびユーザーエクスペリエンスの向上を助けるため、必要に応じて会話中にプロアクティブに人間の確認と明確化を求めます。 | |
| 拡張機能と統合 | カスタムツールサポート | エージェントの機能を拡張するカスタムツールとして、適切なパラメーターを渡して呼び出す関数を作成する「関数呼び出し」や、外部APIと連携するツールを定義する「APIエンドポイント呼び出し」（限定提供）が含まれます。 |
| ネイティブOracle統合 | Oracle Database 23aiおよびより広範なOracleエコシステムと完全に統合されており、デプロイメントを簡素化し、価値を高めるのに役立ちます。 | |
| サードパーティシステムサポート | OpenAPIスキーマ統合を介して外部システムに安全に接続できます 。 | |
| スケーラビリティとセキュリティ | OCIのインフラストラクチャ上に構築されており、ビジネスの成長に合わせてスケールするように設計され、強力なセキュリティ、信頼性、コンプライアンスを提供します。 |
また、プラットフォームには、一般的なエンタープライズニーズに対応するための事前構築済みツールが付属しています。
| ツール名 | 概要 |
|---|---|
| RAG (Retrieval Augmented Generation) | 自然言語を使用して非構造化エンタープライズデータとチャットするための、すぐに使えるツールです。関連データを動的に引き出し、応答の精度と文脈の深さを向上させます。 |
| SQL (NL2SQL) | 自然言語を通じて構造化エンタープライズデータの取得と分析を可能にするツールです。最小限の労力で貴重なインサイトを引き出すことができます。 |
ADKを使ってAI Agents Platformを触ってみた
ADKは、OCI生成AIエージェント・サービス上でのエージェント・アプリケーションの構築を簡素化するクライアント側ライブラリです。
Oracle Cloud Infrastructureドキュメントの記載を参考に、実際にADKを使ってAI Agents Platformを触ってみました。
STEP１．事前準備
事前準備として以下を行います。
- OCIテナンシの用意
- インターネット接続性を持つComputeインスタンスの作成
- ComputeインスタンスからのAPIキーもしくはインスタンスプリンシパルによるCLI利用の設定
全体像
今回、ADKをComputeインスタンス上に導入し、開発を行うため上記の準備を行っています。自端末から行う場合には読み替えて実施してください。Computeインスタンスからエージェント開発を行うためには、インターネット接続可能なネットワークとCLI利用の設定が必要です。CLI導入手順は公式のドキュメントを参照ください。
- AI Agents Platformを利用可能なリージョンのSubscribe
- agent-countのサービスリミット拡張(必要に応じて)
2025年12月7日現在、OCIでAI Agents Platformは一部リージョンでしかGAとなっておらず、Japan East(Tokyo)リージョンではまだ使えません。本稿ではChicago リージョンをSubscribeしています。
またテナンシのサービスリミット設定値 agent-countなども事前に確認しておきましょう。
（出典：生成AIエージェントの制限および制限
STEP２．クライアント側の環境整備
クライアントとなる、Computeインスタンス側の環境準備を行います。
コマンドは、ADKを使ってエージェントの構成及び実行を行うユーザで打鍵してください。今回は全てopcユーザで実施しています。
２－１．uvのインストール
curl -LsSf https://astral.sh/uv/install.sh | sh
２－２．仮想環境の作成
uv venv
仮想環境のアクティブ化
source .venv/bin/activate
ADKと必要なパッケージをインストール
uv pip install oci "oci[adk]" rich pydantic docstring_parser
実行結果例（クリックすると表示）
[opc@aiagentdemo ~]$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.9.13 x86_64-unknown-linux-gnu
no checksums to verify
installing to /home/opc/.local/bin
uv
uvx
everything's installed!
[opc@aiagentdemo ~]$
[opc@aiagentdemo ~]$
[opc@aiagentdemo ~]$ uv venv
Using CPython 3.9.21 interpreter at: /usr/bin/python
Creating virtual environment at: .venv
Activate with: source .venv/bin/activate
[opc@aiagentdemo ~]$ source .venv/bin/activate
(opc) [opc@aiagentdemo ~]$ uv pip install oci "oci[adk]" rich pydantic docstring_parser
Resolved 20 packages in 131ms
Prepared 20 packages in 2.05s
█aaaaaaaaaaaaaaaaaaa [1/20] python-dateutil==2.9.0.post0 █aaaaaaaaaaaaaaaaaaa [1/20] six==1.17.0 ██aaaaaaaaaaaaaaaaaa [2/20] six==1.17.0 ██aaaaaaaaaaaaaaaaaa [2/20] certifi==2025.11.12 ███aaaaaaaaaaaaaaaaa [3/20] certifi==2025.11.12 ███aaaaaaaaaaaaaaaaa [3/20] pydantic-core==2.41.5 ████aaaaaaaaaaaaaaaa [4/20] pydantic-core==2.41.5 ████aaaaaaaaaaaaaaaa [4/20] typing-extensions==4.15.0 █████aaaaaaaaaaaaaaa [5/20] typing-extensions==4.15.0 █████aaaaaaaaaaaaaaa [5/20] cffi==2.0.0 ██████aaaaaaaaaaaaaa [6/20] cffi==2.0.0 ██████aaaaaaaaaaaaaa [6/20] annotated-types==0.7.0 ███████aaaaaaaaaaaaa [7/20] annotated-types==0.7.0 ███████aaaaaaaaaaaaa [7/20] circuitbreaker==2.1.3 ████████aaaaaaaaaaaa [8/20] circuitbreaker==2.1.3 ████████aaaaaaaaaaaa [8/20] mdurl==0.1.2 █████████aaaaaaaaaaa [9/20] mdurl==0.1.2 ███████████████████a [19/20] oci==2.164.0 ████████████████████ [20/20] oci==2.164.0 Installed 20 packages in 236ms
+ annotated-types==0.7.0
+ certifi==2025.11.12
+ cffi==2.0.0
+ circuitbreaker==2.1.3
+ cryptography==45.0.7
+ docstring-parser==0.17.0
+ markdown-it-py==3.0.0
+ mdurl==0.1.2
+ oci==2.164.0
+ pycparser==2.23
+ pydantic==2.12.5
+ pydantic-core==2.41.5
+ pygments==2.19.2
+ pyopenssl==25.1.0
+ python-dateutil==2.9.0.post0
+ pytz==2025.2
+ rich==14.2.0
+ six==1.17.0
+ typing-extensions==4.15.0
+ typing-inspection==0.4.2
(opc) [opc@aiagentdemo ~]$
STEP３．ADKを使用したエージェントの構成および実行
このステップでは、ADKを使用してエージェントを設定および実行します。ADKは先ほど準備したComputeインスタンス上から使用しますが、Agentインスタンスとエンドポイントはコンソール上から事前に作成する必要があります。
３－１．AI Agents作成
AI Agents PlatformサービスでAI Agentsを作成します。
アナリティクスとAI > 生成AIエージェントからAI Agents Platformのダッシュボードを開きます。
ガイドからエージェントを作成を押下
エージェントの情報を入力します。ルーティング指示は後ほどADKで構成する箇所なので、この時点では何も入力しません。
エージェントが使用するツールを設定する画面です。これもADKで構成するので追加を行わずに先へ進みます。
エージェント・エンドポイントを設定する画面です。このエージェントのエンドポイントの自動作成にチェックを入れます。ガードレールに関しては、コンテンツモデレーションやPI保護などが設定可能ですが、今回は特に要求値はないため任意の設定で進みます。
エージェント作成時にLlama 3のライセンス契約及び利用規定が表示される場合があります。これはエージェントが内部的にLlama 3のモデルを利用するためであり、エージェントがツールとして利用するLLMとは別です。規約を確認し問題がなければチェックを入れて先へ進んでください。
無事にエージェントが作成されました。ADKで利用するためにエンドポイントのOCIDが必要なので確認します。
作成されたエージェントを選択し、詳細を確認。
エージェントの詳細画面に、先ほど自動作成されたエンドポイントが表示されているので押下して詳細画面を開きます。
表示されたエンドポイントのOCIDをメモっておきます。
３－２．ADKを使用したエージェントの構成および実行
先ほど環境整備を行ったComputeインスタンスにログインして、サンプルのPython/Javaコードでエージェントの構成および実行をしてみます。
サンプルコード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()
（Oracle Cloud Infrastructureドキュメントより）
躓きポイント
Oracle Linux8,9系でOS 標準の Python-3.9で以下のようなエラーが出る場合があります。
[opc@aiagentdemo02 ~]$ python agentdemo.py
Traceback (most recent call last):
File "/home/opc/agentdemo.py", line 2, in <module>
from oci.addons.adk import Agent, AgentClient, tool
File "/usr/lib/python3.9/site-packages/oci/addons/__init__.py", line 5, in <module>
from oci.addons.adk import (
File "/usr/lib/python3.9/site-packages/oci/addons/adk/__init__.py", line 9, in <module>
from .agent import Agent
File "/usr/lib/python3.9/site-packages/oci/addons/adk/agent.py", line 14, in <module>
from oci.addons.adk.agent_client import AgentClient
File "/usr/lib/python3.9/site-packages/oci/addons/adk/agent_client.py", line 40, in <module>
from oci.addons.adk.agent_error import AgentError, UserError
File "/usr/lib/python3.9/site-packages/oci/addons/adk/agent_error.py", line 8, in <module>
class AgentException(Exception):
File "/usr/lib/python3.9/site-packages/oci/addons/adk/agent_error.py", line 11, in AgentException
def __init__(self, message: str = "", response: Response | None = None):
TypeError: unsupported operand type(s) for |: 'type' and 'NoneType'
記事執筆時点で、OCIでOracle提供のOracle Linux8/9系イメージからComputeインスタンスを構築した場合のデフォルトのPythonバージョンが3.9となっていることが原因です。
上記のエラーが出力された場合、新しい3.10以降のバージョンをインストールして実行してあげましょう。
３－３．実行結果
この例ではユーザの「シアトルは寒いですか？」という問い合わせに対して、ADKで追加されたツールを使ってエージェントが回答します。
サンプルプログラムが実行されると、ADKによってローカルのツールget_weatherがエージェントが使用するツールとして追加されます。
天候を取得するツールに対し、エージェントが使う付加情報として場所を与えます。（この例ではシアトル）
最終結果として、エージェントから「シアトルは７２°Fなのでそんなに寒くないです。」と回答が返ってきています。
#華氏72度＝摂氏22度程度
今回、エージェントにADKから「Functionツール(機能ツール)」を追加して利用しましたが、Functionツールはローカル側に保存・実行されるアーキテクチャですので、本番運用を行う際には注意が必要です。
