LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@ig_ouchiin株式会社イグアス

watsonx OrchestrateからGmail APIを使用してメールを送信する

Last updated at Posted at 2025-08-28

はじめに

AIエージェントでGmailを送信する様子

どんな記事か

IBM watsonx Orchestrateを使ってgmailを送信するAIエージェントを作成しました。様々難しい点やややこしい部分があったので、エージェント作成の流れを共有します。

AIエージェント作成の流れ

  1. Gmail API準備
  2. IBM watsonx Orchestrate環境準備
    • watsonx Orchestrate 環境を作成
    • watsonx Orchestrate ADKをインストール
  3. AIエージェントの作成
    • connectionの作成
    • toolの作成
    • Agentの作成
  4. 動作確認

IBM watsonx Orchestrateとは

IBM watsonx Orchestrate
簡単に言えば、IBMが提供するAIエージェント作成ツールです。
詳細は上記公式サイトをご確認ください。

1. Gmail API準備

今回はブラウザ認証をせずにAPIにアクセスしたいので、リフレッシュトークンフローでGmail APIにアクセスします。
※ リフレッシュトークン取得について、CURL等で認可コードフローを用いて取得する方法があります。（参考：OAuth 2.0 トークンを取得する）

補足：少し複雑なGoogle APIの認証方法（折り畳み）

参考：OAuth 2.0 を使用して Google API にアクセスする

  • APIキー認証
    一般公開されているもののみアクセス可能（機能がかなり制限される）

  • サービスアカウントを用いたJWT認証

    • ユーザーの同意（ブラウザ認証）は必要ない
    • 個人アカウントだとできることが少ない

  • OAuth2.0認可コードフロー

    • ユーザーの同意（ブラウザ認証）が必要
    • 事前に同意を済ませてリフレッシュトークンを取得してしまうこともできる（リフレッシュトークンフローに利用）

2. watsonx Orchestrate環境準備

watsonx Orchestrate 環境を作成

トライアル環境準備や基本的な利用方法についての説明は割愛します。
参考：watsonx Orchestrate トライアル

watsonx Orchestrate ADKをインストール

参考：IBM watsonx Orchestrate ADK
（ADKについてインストール手順や使い方について全て記載があります）

ADK(Agent Development Kit)とは

AIエージェントや、エージェントを構成するコンポーネントをPython,yaml,CLIで作成するツールセットのことです。
ローカルで開発したコンポーネントを、コマンド操作でIBM Cloud上のwatsonx Orchestrate環境にデプロイできます
APIキーを用いてIBM Cloud上のwatsonx Orchestrate環境に接続させることができます。

ADK大まかな導入手順

※ 詳細は上記URLをご確認ください

  • ローカルにwatsonx Orchestrate ADKをインストール（pipまたはuv）
  • watsonx OrchestrateがあるIBM CloudからAPIキーを取得し、ローカルのADKと紐づける
  • orchestrateコマンドがインストールされるので、このコマンドで操作を行う

3. AIエージェントの作成

watsonx OrchestrateとADKを準備できたので、早速Gmail送信をしてくれるAIエージェントを作成していきます。

AIエージェント作成の流れ

  • Web上で、Gmail APIの認証情報を設定するConnectionを作成
  • ADKでPythonを用いて、Gmail APIを使ったメール送信のToolを作成
  • Web上で、Agentの作成

Connectionの作成（Web上で作成）

Gmail APIにアクセスするための認証情報を設定する、Connectionというコンポーネントを作成します。

Connection作成方法

WebのIBM watsonx Orchestrateに入ったら、
左上メニュー ＞ Manage ＞ Connections ＞ Add new connection +
から作成します。

認証情報の設定

  • Connection ID：gmail-conn
  • Display name：任意のもの
  • key-value pair
  • 左下のConnectで接続確認を行う

※ ConnectionでDraftとLiveがありますが、watsonx Orchestrateのトップ画面のChatからエージェントを使う場合は、Liveを設定する必要があります。

Toolの作成（ADKで作成）

AIエージェントにメールを送信させたいので、メール送信のツールを作成します。
IBM watsonx Orchestrate ADK を参考にGmailを送信するツールを作成します。

Pythonツールの作成

@toolというデコレータを使うことで、watsonx Orchestrateでツールとして認識されます。
また、@toolの関数でreturnする値はwatsonx Orchestrateのクライアントに渡されるので、チャットで表示可能です。

Pythonサンプル（折り畳み）
send_gmail.py
import os
import base64
from email.mime.text import MIMEText
from email.mime.multipart import MIMEMultipart
from email.mime.base import MIMEBase
from email import encoders

from google.oauth2.credentials import Credentials
from google.auth.transport.requests import Request
from googleapiclient.discovery import build
from ibm_watsonx_orchestrate.agent_builder.tools import tool, ToolPermission
from ibm_watsonx_orchestrate.run import connections
from ibm_watsonx_orchestrate.agent_builder.connections import ConnectionType, ExpectedCredentials



def authenticate_gmail():
    """Gmail APIの認証（ConnectionのKey-Valueから取得した情報を使用）"""
    # connは辞書として返される: {'key1': 'value1', 'key2': 'value2'}
    kv = connections.key_value('gmail-conn-t')

    # kv は辞書
    client_id = kv.get('client_id')
    client_secret = kv.get('client_secret')
    refresh_token = kv.get('refresh_token')
    token_url = kv.get('token_url')
    scopes = kv.get('scope')
    scopes_list = [scopes]

    creds = Credentials(
        token=None,  # アクセストークンはrefreshで取得
        refresh_token=refresh_token,
        token_uri=token_url,
        client_id=client_id,
        client_secret=client_secret,
        scopes=scopes_list,  # スコープはリスト形式で指定
    )

    if not creds.valid:
        creds.refresh(Request())

    return build('gmail', 'v1', credentials=creds)


def create_message(to, subject, body, from_email):
    """テキストメールのメッセージ作成"""
    message = MIMEMultipart()
    message['to'] = to
    message['from'] = from_email
    message['subject'] = subject

    message.attach(MIMEText(body, 'plain', 'utf-8'))
    raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
    return {'raw': raw_message}


def send_message(service, message):
    """メール送信"""
    try:
        sent_message = service.users().messages().send(userId='me', body=message).execute()
        return sent_message
    except Exception as error:
        print(f'メール送信エラー: {error}')
        # エラー詳細を辞書で返す
        return {'error': str(error), 'error_type': type(error).__name__}


def format_send_email_output(sent_message, to, subject, body):
    """送信結果を整形"""
    try:
        if sent_message and not isinstance(sent_message, dict) or not sent_message.get('error'):
            message_id = sent_message.get('id', '不明')
            output_lines = [
                'メール送信完了:',
                f'  - 送信先: {to}',
                f'  - 件名: {subject}',
                f'  - メッセージID: {message_id}',
                f"  - 本文プレビュー: {body[:100]}{'...' if len(body) > 100 else ''}",
            ]
            return "\n".join(output_lines)
        elif isinstance(sent_message, dict) and sent_message.get('error'):
            # エラー情報が含まれている場合
            error_info = sent_message.get('error', '不明なエラー')
            error_type = sent_message.get('error_type', '不明')
            return f'メール送信に失敗しました\n  - エラー種別: {error_type}\n  - 詳細: {error_info}'
        else:
            return 'メール送信に失敗しました（詳細不明）'
    except Exception as e:
        return f'出力フォーマットエラー: {str(e)}'


@tool(
    name='send_gmail_test',
    description='Send a text email using Gmail API',
    permission=ToolPermission.READ_WRITE,
    expected_credentials=[ExpectedCredentials(
        app_id='gmail-conn-t',
        type=ConnectionType.KEY_VALUE
    )]
)
def send_gmail_test(to: str, subject: str, body: str, from_email: str) -> str:
    """
    Gmail API を用いてテキストメールを送信します（ConnectionのKey-Valueを使用）。

    :param to: 送信先メールアドレス
    :param subject: 件名
    :param body: 本文
    :param from_email: 送信元メールアドレス
    :returns: 送信結果の整形文字列
    """
    try:
        service = authenticate_gmail()
        # return service
        message = create_message(to, subject, body, from_email)
        sent_message = send_message(service, message)
        return format_send_email_output(sent_message, to, subject, body)
    except Exception as e:
        error_message = f"メール送信エラー: {str(e)}"
        print(error_message)
        return error_message

requirements.txtの作成

作成したToolをこの後watsonx Orchestrateにorchestrateコマンドでインポートしますが、必要ライブラリをまとめたrequirements.txtが必要になります。

requirements.txt
google-auth==2.23.4
google-auth-oauthlib==1.1.0
google-auth-httplib2==0.1.1
google-api-python-client==2.108.0
requests>=2.31.0
ibm-watsonx-orchestrate
typing-extensions>=4.0.0

watsonx Orchestrateへのインポート

ADKでToolをwatsonx Orchestrateにインポートします。
作成したpythonツール、Connectionのapp-id(Connection ID)、requirements.txtを指定します。

orchestrate tools import \
-k python \
-f tools/send_gmail.py \ # pythonファイルのパス
-a gmail-conn-t=gmail-conn \ # <@toolで指定したapp-id>=<Connectionのapp-id(Connection ID)
-r requirements.txt # requirements.txtのパス

Agentの作成（Web上で作成）

Agentを作成し、ツールを渡してあげることで、チャット上でメールの送信をお願いできるようになります。

WebのIBM watsonx Orchestrateに入ったら、
左上メニュー ＞ Build ＞ Agent Builer ＞ Create Agent +
から作成します。

Agentの設定項目

  • Create from scratch / Create from template：Create from templateを選択
  • Name：任意のもの
  • Description：作成するエージェントの説明
  • Agent Style：今回はDefault（参考：Choosing a style for your agent）
  • Tools：send_gmail_test（作成したツール）を選択
  • Behavior：今回は無し（AIエージェントに渡すシステムプロンプトです）
  • Model：llama-3-2-90b-vision-instruct

※ 今回はWeb上で作成しましたが、ADKで作成することもできます。（ADKだとModelでgpt-oss-120bを使うこともできます）

4. 動作確認

中国の簡体字っぽくなっていますが、ちゃんとメールを送信できました。（Behaiviorで"日本語で回答してください"と添える、Modelを高性能なものに変更する等で改善は可能かと思います）

おわりに

今回、watsonx Orchestrateを使ってエージェントを作成する中で、AIエージェント開発のリアルな側面を改めて感じました。

  • API実装の難しさ： APIの認証周りのように、外部サービスとの連携は考慮すべき点が多く、つまずく点は多い
  • LLMの挙動： 本稿では試行していませんが、実用的なAIエージェントの作成にはシステムプロンプトの調整が必須です
  • 実業務への応用： 本稿では単純なメール送信のみ行いましたが、実際は課題の抽出、AIエージェントの適用範囲の決定、実現可能性の検証... 等技術だけではない様々な考慮が必要です

このように、AIエージェントを実用的なレベルに引き上げるには様々な壁がありますが、大きな可能性も秘めているとも感じます。
本稿が、皆さんのAIエージェント開発における一助となれば幸いです。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?