つないでみよう：#35） Responses API － 画像生成

前回までで、一番単純な会話ができるようになったので、次は画像生成をさせてみましょう。

Responses API は、画像生成にも対応しているので、/images/generations など別の API をコールする必要はありません。例えば、次のような JSON を送信することで、Responses API に画像生成させることができます。

{    "model": "gpt-5-nano",    "input": "ビーチリゾートに行きたくなるような、白い砂浜とヤシの木の画像",    "tools": [       {          "type": "image_generation",          "model": "gpt-image-2",          "size": "1024x1024",          "output_format": "png",          "quality": "low"       }    ] }

重要なのは tools 配列を指定し、その中で type に image_generation を設定している点です。設定値からもわかるように、Responses API では画像生成も「ツール」の一つとして扱われます。次の model が画像生成を担当するモデルです。現在の推奨モデルは gpt-image-2 で、size、output_format、quality は画像生成時のオプションです。指定できる項目や設定値はモデルによって異なるため、必要に応じて公式ドキュメントを確認してください。

この例では、プロンプトの解釈を gpt-5-nano が担当し、実際の画像生成を gpt-image-2 が担当します。このように Responses API では、それぞれの役割に応じてモデルを組み合わせて利用できるのが特徴です。

画像生成機能の作成方針

前回までに紹介した会話のサンプルでは、新規と継続で別々のフォーム、エージェントで作成しました。今回の画像生成では、１つにまとめたいと思います。

新規か継続の判断は、文書に実行結果が入っているかで判断するものとします。具体的には、Result_ID に値が入っていれば、継続として処理します。

フォームの作成

画像生成用のフォームをサンプルアプリに追加します。

前回 #34 で作成した fGPT_Res02 フォーム（継続元ID フィールドがある）をコピペして、画像生成用フォーム fGPT_Res03 を作成します。

フィールドは基本的にはそのままなのですが、今回の返答が画像となります。そこで、実行結果のフィールドをリッチテキスト Result_Image に変更します。

エージェントの作成

フォームと同様にエージェントも前回作成のエージェントをコピペして作業を開始します。

◇ Initialize

基本的な処理の流れに変更はありません。ただ、新規と継続をまとめたことで中盤の太字の部分が大きく違います。また、この変更に関連して変数名や処理順を一部変更していますので、Initialize 全体を掲載しています。

Sub Initialize    Dim nuiw As New NotesUIWorkspace    Dim nuid As NotesUIDocument    Dim ndb As NotesDatabase    Dim ndCur As NotesDocument    'UI で開いている文書    Dim ndReq As NotesDocument   '問い合わせに利用する文書    Dim jnavRequest As NotesJSONNavigator    Dim jnavResponse As NotesJSONNavigator    Dim s As String    '初期化    Set xns = New NotesSession    Set ndb = xns.CurrentDatabase    '現在の文書（= 継続元の文書）    Set nuid = nuiw.Currentdocument    Set ndCur = nuid.Document    ' UI の文書は読み込みモードの前提    ' 新規 or 継続の判定    If ndCur.Result_ID(0) = "" Then       '新規リクエスト（現在の文書で問い合わせ）       Set ndReq = ndCur    Else       '継続したリクエスト（現在の文書を参照させる設定で新規作成）       s = nuiw.Prompt(PROMPT_OKCANCELEDIT, "継続", "次のプロンプトを入力してください。")       If s = "" Then Exit Sub       '新規文書作成       Set ndReq = ndb.CreateDocument()       ndReq.Form = "fGPT_Res03"       ndReq.Model = ndCur.Model       ndReq.PrevID = ndCur.Result_ID    '現在の文書を参照       ndReq.Prompt = s    End If    'Request Body(JSON) の作成    Set jnavRequest = xGetRequest_JSON(ndReq)    Call xSetJSON(ndReq, "Request", jnavRequest)    'Request Body の保存    '問い合わせ実行    Set jnavResponse = xAskResponses(jnavRequest)    Call xSetJSON(ndReq, "Response", jnavResponse)    'Response の保存    '返答を取得    If xGetResponce(ndReq, jnavResponse) Then       Call ndReq.Save(True, False)       '文書を開きなおす       Call nuid.Close()       Call nuiw.EditDocument(False, ndReq)    End If End Sub

◇ xGetRequest_JSON

Responses API に送信する関数で、画像生成を指定する tools 配列を追加しています。今回はサンプルですので、model や size などには固定値を追加しています。

Sub Function xGetRequest_JSON(vnd As NotesDocument) As NotesJSONNavigator    Dim jnav As NotesJSONNavigator    Dim jaTol As NotesJSONArray    Dim joTol As NotesJSONObject    'RequestBody（JSON） の準備    Set jnav = xns.CreateJSONNavigator("")    '1.model    Call jnav.AppendElement(vnd.Model(0),"model")    '1.previous_response_id  継続の場合のみ設定    If vnd.PrevID(0) <> "" Then       Call jnav.AppendElement(vnd.PrevID(0),"previous_response_id")    End If    '1.input    Call jnav.AppendElement(vnd.Prompt(0),"input")    '1.tools 配列    Set jaTol = jnav.AppendArray("tools")    '2.image_generation    Set joTol = jaTol.AppendObject()    Call joTol.AppendElement("image_generation", "type")    Call joTol.AppendElement("gpt-image-2", "model")    Call joTol.AppendElement("1024x1024", "size")    Call joTol.AppendElement("png", "output_format")    Call joTol.AppendElement("low", "quality")    Set xGetRequest_JSON = jnav End Function

◇ xAskResponses

画像生成は会話より応答時間がかかります。そこで、タイムアウトを 450 秒に設定します（デフォルトは 30 秒）。ちなみに私が試した限り上記生成条件で、300 秒以内で返答が返ってきました。

Sub Function xAskResponses(vjnavRequest As NotesJSONNavigator) As NotesJSONNavigator          ・・・（省略）・・・    'HTTP ヘッダーの設定    Call http.SetHeaderField("Content-Type", "application/json")    Call http.SetHeaderField("Authorization", "Bearer " & xcsBearer)    'API 実行    http.TimeOutSec = 450    '画像生成は時間がかかるので    http.PreferJSONNavigator = True          ・・・（省略）・・・ End Function

◇ xGetResponce

API のレスポンスから返答を取得する処理も変化します。生成された画像は output 配列内の type が image_generation_call にあります。これを取り出し、result の値が画像データとなります。

Function xGetResponce(vnd As NotesDocument, vjnav As NotesJSONNavigator) As Boolean    Dim je As NotesJSONElement    Dim sBase64 As String    Set je = vjnav.Getfirstelement()    'id 取得    vnd.Result_ID = GetPropertyValue(vjnav, "id")    'output 取得してセット    Set je = GetProperty(vjnav, "output")    '"type": "image_generation_call" の要素を取得    Set je = FindInArray(je, "type", "image_generation_call")    '生成画像（result）を取得してセット    sBase64 = GetPropertyValue(je, "result")    Call xSetImageFile(vnd, "Result_Image", sBase64)    xGetResponce = True End Function

画像データは Base64 でエンコードされているので、以下の３つの関数を通して、デコードし、画像ファイルに変換します。

◇ xSetImageFile

Base64 の画像データをデコード、画像ファイル化し、文書に添付する関数です。

Private Function xSetImageFile(vnd As NotesDocument, ByVal vsFld As String, vsBase64 As String)    Dim nsImg As NotesStream    Dim nrti As NotesRichTextItem    Dim sFP As String    sFP = xns.GetEnvironmentString("Directory", True)    sFP = sFP & "\" & Format(Now, "yyyymmddhhnnss") & ".png"    On Error Resume Next    Kill sFP    '存在してたら削除    On Error GoTo Err_General    Set nsImg = xns.CreateStream()    Call Base64ToBinary(vsBase64, nsImg)   'デコード    Call StreamToImageFile(nsImg, sFP)    '画像ファイルとして保存    '画像ファイルを文書に添付    Call vnd.RemoveItem(vsFld)    Set nrti = vnd.CreateRichTextItem(vsFld)    Call nrti.EmbedObject(EMBED_ATTACHMENT, "", sFP) Exit_Proc:    Exit Function Err_General:    MsgBox Error$    Resume Exit_Proc End Function

◇ Base64ToBinary / StreamToImageFile

これらの関数は  OpenNTF の LotusScript Gold Collection プロジェクトから拝借した関数です。詳しくは #28 で紹介しているので必要に応じて参照ください。関数自体は下記に再掲載します。

%REM    Sub Base64ToBinary    Description: Given a string of base64-encoded data, write into a binary stream we are passed.       This is done rather than creating the stream here and returning it, so that you can    stream directly into a file if you choose. %END REM Sub Base64ToBinary(strBase64$, streamOut As NotesStream)    ' Given a string of base64 encoded data, this routine decodes and writes the original binary data into a NotesStream    Dim doc As NotesDocument    Dim mime As NotesMIMEEntity    Dim streamIn As NotesStream    Dim db As NotesDatabase    Dim session As New NotesSession    Set db = session.CurrentDatabase    Set doc = db.CreateDocument    Set mime = doc.CreateMIMEEntity("Body") ' the mime classes already know how to do this conversion,    Set streamIn = session.CreateStream    Call streamIn.WriteText(strBase64)    streamIn.Position = 0    Call mime.SetContentFromText(streamIn, "binary", ENC_BASE64)    Call mime.GetContentAsBytes(streamOut, True) ' decode as you stream out the data. End Sub

Sub StreamToImageFile(vnstImage As NotesStream, ByVal vsFP As String)    Dim nstOut As NotesStream    On Error Resume Next    Kill vsFP '存在してたら削除    Set nstOut = xns.CreateStream()    Call nstOut.Open(vsFP)    vnstImage.Position = 0    Do Until vnstImage.Position >= vnstImage.Bytes       Call nstOut.Write(vnstImage.Read(16000))    Loop End Sub

想定外の改造

画像生成のサンプルとしては、上記までで完了のつもりでした。ただ、実行するとエラーが発生しました。

原因は、API のレスポンスが大きく、リッチテキストに書き込む処理で  リッチテキストの制限 に引っ掛かっていたためだと思われます（どちらも 64 KB まで）。

• リッチテキストフィールドの単一段落の最大サイズ
• 文書当たりのテキスト (要約) データの最大量

そこで、JSON のサイズが大きい場合、添付ファイルとして保存するように変更します。

◇ xSetJSON

JSON を文書に保存する関数で、サイズが大きい場合（10000 バイト）、後述する JSONToFile を通して、ファイルに保存します。

Private Function xSetJSON(vnd As NotesDocument, ByVal vsFld As String, vjnav As NotesJSONNavigator)             ・・・（省略）・・・    '日時の記録    Call vnd.ReplaceItemValue(vsFld & "_DT", Now)    'JSON の記録    'いったん削除してからセット    Dim sFP As String    Call vnd.RemoveItem(vsFld & "_JSON")    Set nrti = vnd.CreateRichTextItem(vsFld & "_JSON")    If Len(sText) > 10000 Then       '大きいのでファイルで保存       sFP = JSONToFile(vjnav, "")    'ファイル名は指定なし       Call nrti.EmbedObject(EMBED_ATTACHMENT, "", sFP)       Kill sFP    '添付したのでファイルは削除    Else       'そのままテキストで保存       Call nrti.AppendText(sText)    End If End Function

◇ JSONToFile

JSON をファイルに保存する関数です。この関数はほかでも使いそうなので、lsJSONNavi ライブラリに作成します。

Public Function JSONToFile(vjnav As NotesJSONNavigator, ByVal vsFileName As String) As String    Dim ns As New NotesSession    Dim nstOut As NotesStream    Dim sFP As String    sFP = ns.Getenvironmentstring("Directory", True)    If vsFileName = "" Then       sFP = sFP & "\" & Format(Now, "yyyymmddhhnnss") & ".json"    Else       sFP = sFP & "\" & vsFileName    End If    On Error Resume Next    Kill sFP   '存在してたら削除    On Error GoTo Err_General    Set nstOut = ns.CreateStream()    Call nstOut.Open(sFP)    Call nstOut.WriteText(vjnav.Stringify())    Call nstOut.Close()    JSONToFile = sFP Exit_Proc:    Exit Function Err_General:    MsgBox Error$    Resume Exit_Proc End Function

動作検証

出来上がったら動作検証します。

最初のリクエストを書いた文書を開き、エージェントを実行します。しばらくすると文書が開きなおし、画像が添付された状態となります。API からの返答は大きくなるので、JSON は返答だけが添付ファイルになっているはずです。この状態から再度エージェントを実行すると作成された画像に対するリクエストが送信できます。

今日も朝から暑い中 Notes 三昧なので、『ビーチリゾートに行きたくなるような、白い砂浜とヤシの木の画像』ネタだけは休日仕様にしてみました。

結果は次のような感じでした。

青い海に真っ白な砂浜、デッキチェアにパラソル、イメージ通りの画像ですね。次のリクエストでは『この画像を夕景に変更してください。』と送信しました。構図は少々変わってしまってますが、見事な夕焼けですね。

あぁ、リゾートしたい...

前回

連載：つないでみよう

つないでみよう：#34） Responses API － サンプルアプリ作成 ③

Responses API では過去のリクエストを参照させて、会話を継続する機能があります。仕組みは単純で、リクエストで送信する JSON に参照する過去のリクエストの id を previous_response_id に指定するだけでした。

{    "model": "gpt-5-nano",    "previous_response_id": "resp_xxxxx",    "input": "そこの面積は？" }

今回は、作成中のサンプルアプリに会話を継続する機能を追加します。

フォームの作成

前回作成したフォームをコピペして継続用のフォームを作成します。後述のプログラムで使用するので別名は fGPT_Res02 とします。

追加するのは参照するリクエストの id を指定する継続元 ID（PrevID）フィールドだけです。

エージェントの作成

エージェントも前回作成したものをコピペで作成し、変更を加える形で進めます。このエージェントの使い方は次の通りです。

1. 継続元の文書を開く
2. 今回のエージェント実行
3. 次の問い合わせのプロンプトを入力
4. Responses API に問い合わせ（会話の継続）
5. 結果を記録して、UI に表示

エージェントの修正箇所を順に説明します。

◇ Initialize

メインルーチンでは、プロンプトの入力（青字）と会話の継続用の文書を新規作成（赤字）する処理を追加します。 それ以外に変更はありません。

Sub Initialize    Dim nuiw As New NotesUIWorkspace    Dim nuid As NotesUIDocument    Dim ndb As NotesDatabase    Dim nd As NotesDocument    Dim jnavRequest As NotesJSONNavigator    Dim jnavResponse As NotesJSONNavigator    '初期化    Set xns = New NotesSession    Set ndb = xns.CurrentDatabase    '次のプロンプトを入力    Dim s As String    s = nuiw.Prompt(PROMPT_OKCANCELEDIT, "継続", "次のプロンプトを入力してください。")    If s = "" Then Exit Sub      '未入力で処理終了    '現在の文書（= 継続元の文書）    Dim ndPrev As NotesDocument    Set nuid = nuiw.Currentdocument    Set ndPrev = nuid.Document    '新規文書作成    Set nd = ndb.CreateDocument()    nd.Form = "fGPT_Res02"    nd.Model = ndPrev.Model    nd.PrevID = ndPrev.Result_ID     '継続元のID    nd.Prompt = s          'プロンプト    '① Request Body(JSON) の作成    Set jnavRequest = xGetRequest_JSON(nd)    Call xSetJSON(nd, "Request", jnavRequest) 'Request Body の保存    '② 問い合わせ実行    Set jnavResponse = xAskResponses(jnavRequest)    Call xSetJSON(nd, "Response", jnavResponse) 'Response の保存    '返答を取得    If xGetResponce(nd, jnavResponse) Then       Call nd.Save(True, False)       '文書を開きなおす       Call nuid.Close()       Call nuiw.EditDocument(False, nd)    End If End Sub

◇ xGetRequest_JSON

送信する JSON を作成する処理では、previous_response_id の指定を追加します。会話の継続で一番重要な点なのですが、修正作業としては単純ですね...

Function xGetRequest_JSON(vnd As NotesDocument) As NotesJSONNavigator    Dim jnav As NotesJSONNavigator    'RequestBody（JSON） の準備    Set jnav = xns.CreateJSONNavigator("")    '1.model    Call jnav.AppendElement(vnd.Model(0),"model")       '1.previous_response_id    If vnd.PrevID(0) <> "" Then       Call jnav.AppendElement(vnd.PrevID(0),"previous_response_id")    End If    '1.input    Call jnav.AppendElement(vnd.Prompt(0),"input")    Set xGetRequest_JSON = jnav End Function

動作検証

完成したら実行します。

前回（#33）で作成した文書を開き、今回作成したエージェントを実行します。『そこの面積は？』と聞いただけなのに、前回の「大阪の県庁所在地」を参照して、大阪市の面積に関して答えてくれました。

前回

連載：つないでみよう

次回

つないでみよう：#33） Responses API － サンプルアプリ作成 ②

サンプルアプリ作成の２回目は、取得したレスポンス（JSON）から必要な値を取得する部分を作成します。

Responses API のレスポンスは #31 で紹介したように複雑な構造になっています。例えば API の返答が含まれる output ノードは配列となっており、要素の個数や順序が固定ではありません。その中から type が message となっているものを探し出す必要がありました。

{    "id": "resp_xxxxx",    "object": "response",          ・・・（省略）・・・    "moderation": null,    "output": [       {          "id": "rs_xxxxx",          "type": "reasoning",          "content": [],          "summary": []       },       {          "id": "msg_xxxxx",          "type": "message",          "status": "completed",          "content": [             {                "type": "output_text",                "annotations": [],                "logprobs": [],                "text": "大阪府の県庁所在地は大阪市です。"             }          ],          "role": "assistant"       }    ],          ・・・（省略）・・・ }

← output は配列 ← １つ目の要素は回答ではない ← ２つ目の要素が回答 ← 回答

実際にコーディングを行うと JSON の構造をたどるコードと Responses API 特有の意味を解釈するコードが混在し、煩雑で理解しがたいコードになります。

そこで、今回のサンプルでは JSON の汎用的な操作をライブラリに定義します。「JSON の構造をたどるコード」をライブラリに外出しにして、メインルーチンは「JSON の意味を解釈するコード」に特化させ、コードの可読性を上げようという算段です。

ライブラリの作成

今回利用する Responses API のレスポンス調査では、次のような JSON 操作が必要となります。

関数名	機能	使用例
GetProperty	名前を指定して、子ノードを取得します。	output ノードを取得
GetPropertyValue	名前を指定して、子ノードの値を取得します。	text ノードを探してその値を取得
FindInArray	配列からノードと値が一致した要素を返します。	output ノードから type = message の子ノードを取得

新規でスクリプトライブラリ lsJSONNavi を作成して、以下のコードを記述します。

Option Declare %REM 名前を指定して、子ノードを取得します。 ◆ 引数 1. voParent　 Variant 取得もととなる親ノード 　NotesJSONElement の場合：値が NotesJSONObject であれば、子ノードを調査 　NotesJSONObject、NotesJSONNavigator の場合：その子ノードを調査 2. vsName String 取得するノード名 ◆ データ型（戻り値）　 NotesJSONElement 　一致したノードを返します。 　見つからない場合は Nothing を返します。 %END REM Public Function GetProperty(voParent As Variant, ByVal vsName As String) As NotesJSONElement    Dim jobj As NotesJSONObject    Dim sType As String    On Error GoTo Err_General    sType = TypeName(voParent)    If sType = "NOTESJSONELEMENT" Then       Set jobj = voParent.Value       Set GetProperty = jobj.GetElementByName(vsName)    ElseIf sType = "NOTESJSONNAVIGATOR" Then       Set GetProperty = voParent.GetElementByName(vsName)    ElseIf sType = "NOTESJSONOBJECT" Then       Set GetProperty = voParent.GetElementByName(vsName)    End If Exit_Proc:    Exit Function Err_General:    Set GetProperty = Nothing    Resume Exit_Proc End Function %REM 名前を指定して、子ノードの値を取得します。 ◆ 引数 1. voParent　 Variant 取得もととなる親ノード 　NotesJSONElement の場合：値が NotesJSONObject であれば、子ノードを調査 　NotesJSONObject、NotesJSONNavigator の場合：その子ノードを調査 2. vsName String 取得するノード名 ◆ データ型（戻り値）　 String 　一致したノードの値を返します。 　見つからない場合は Null を返します。 %END REM Public Function GetPropertyValue(voParent As Variant, ByVal vsName As String) As String    Dim je As NotesJSONElement    Dim sType As String    On Error GoTo Err_General    sType = TypeName(voParent)    If sType = "NOTESJSONELEMENT" Then       Set je = GetProperty(voParent, vsName)    ElseIf sType = "NOTESJSONNAVIGATOR" Then       Set je = voParent.GetElementByName(vsName)    ElseIf sType = "NOTESJSONOBJECT" Then       Set je = voParent.GetElementByName(vsName)    End If    GetPropertyValue = je.Value Exit_Proc:    Exit Function Err_General:    GetPropertyValue = ""    Resume Exit_Proc End Function %REM 配列の要素からノードと値が一致した要素を返します。 ◆ 引数 1. voArray 　 Variant 調査する配列 　NotesJSONAarray の場合：その配列の各要素を調査 　NotesJSONElement の場合：値が配列の場合、各要素を調査 2. vsName String ノード名 3. vsValue String ノード名の値 ◆ データ型（戻り値）　 NotesJSONElement 　一致した要素（= ノード）を返します。 　見つからない場合は Nothing を返します。 %END REM Public Function FindInArray(voArray As Variant, ByVal vsName As String, ByVal vsValue As String) As NotesJSONElement    Dim je As NotesJSONElement    Dim ja As NotesJSONArray    Dim sType As String    Dim sVal As String    On Error GoTo Err_General    sType = TypeName(voArray)    If sType = "NOTESJSONARRAY" Then       '配列なのでセット       Set ja = voArray    ElseIf sType = "NOTESJSONELEMENT" Then       'Elemetの値が配列なら処理       Set ja = voArray.Value    End If    If Not ja Is Nothing Then       Set je = ja.GetFirstElement()       Do Until je Is Nothing          sVal = GetPropertyValue(je, vsName)          If sVal = vsValue Then             '発見             Set FindInArray = je             Exit Do          End If          Set je = ja.GetNextElement()       Loop    End If Exit_Proc:    Exit Function Err_General:    Set FindInArray = Nothing    Resume Exit_Proc End Function

要素の取得もとは、JSON ツリーのトップレベルである NotesJSONNavigator であっても、サブツリーを表す NotesJSONObject でも動作するようにします。また、NotesJSONElement であっても値が NotesJSONObject であればそこから取得するようにしています。関数の利用者は、JSON オブジェクトの型をあまり気にすることなく利用できるようにしてみました。

今のところ JSON の操作は手探りで、例外処理も不完全と思います。まだまだよい関数というには程遠いですが、いったん掲載しておきます。今後改善や機能追加することもあるので、その点はご了承ください。

 Responses API レスポンス取得

作成しているサンプルアプリに戻ります。

まず、取得した回答を記録するフィールドをフォームに作成します。

続いて、前回作成したエージェントにライブラリを組み込み、レスポンス取得の関数を追加します。取得するのは、レスポンスの最初の項目である id と返答です。

Use "lsJSONNavi" Function xGetResponce(vnd As NotesDocument, vjnav As NotesJSONNavigator) As Boolean    Dim je As NotesJSONElement    Set je = vjnav.Getfirstelement()    ' id の値を取得    vnd.Result_ID = GetPropertyValue(vjnav, "id")    ’ 返答を取得    ' ① output ノードを取得    Set je = GetProperty(vjnav, "output")    ' ② "type": "message" のノードを取得    Set je = FindInArray(je, "type", "message")    ' ③ content ノードを取得    Set je = GetProperty(je, "content")    ' ④ "type": "output_text"    Set je = FindInArray(je, "type", "output_text")    ' ⑤ 返答を取得してセット    vnd.Result_Content = GetPropertyValue(je, "text")    xGetResponce = True End Function

最後に作成した関数をメインルーチンに組み込んで完成です。

Sub Initialize          ・・・（省略）・・・    '問い合わせ実行    Set jnavResponse = xAskResponses(jnavRequest)    Call xSetJSON(nd, "Response", jnavResponse)    'Response の保存    '返答を取得    If xGetResponce(nd, jnavResponse) Then       Call nd.Save(True, False)       '文書を開きなおす       Call nuid.Close()       Call nuiw.EditDocument(False, nd)    End If End Sub

実行して、ID と回答が取得できれば OK です。

まとめ

今回はレスポンス JSON から必要な情報を取得する部分を作成しました。

その過程で JSON から必要な情報を効率よく抽出するための関数群作成し、利用しました。xGetResponce 関数を見ていただけるとわかると思いますが、JSON をどのようにたどっているのか、一目瞭然になっています。これだけシンプルになっていれば、処理内容が一瞬で理解できます。

『動けばいい』でとどめず、後々のメンテナンス性まで考えてコーディングしたいですね。

内容的には、本題の Responses API からは少々外れてしまったような気もしますが ...

前回

連載：つないでみよう

次回

つないでみよう：#32） Responses API ー サンプルアプリ作成 ①

今回からは Responses API で会話を行うサンプルアプリを作成します。

前回紹介したように Responses API と Chat Completion API は、エンドポイントと送受信する JSON が違うだけで、サンプルアプリの構造に特別なことはありません。以前作成した Chat Completion API のサンプルを改造して進めることも可能なのですが、記事が独立するよう、今回は初めから順に作成したいと思います。

フォームの作成

Responses API に送信する情報と結果を記録するためのフォームを作成します。

各フィールドの説明は詳細にはしませんが、『リクエスト設定』が Responses API に送信する内容の入力欄、『リクエスト』が送信した情報、『レスポンス』が Responses API の応答を記録するエリアです。

JSON を保存するリッチテキストフィールドはセクション内に配置し、展開/省略を次のように設定します。

画像の生成や解析を行う場合など JSON が大きくなると、文書を開くのが遅くなります。ただ、閉じたセクション内にフィールドが存在する場合は、文書を開くタイミングではなく、セクションを開くタイミングで遅くなります。

上記のように最初は閉じるようにしておくと、見たいときだけ待たされる構造にできます。フィールドサイズを表示しているので、待たされるかどうかもわかりますね。

エージェントの作成

上記フォームで作成された文書を使って、Responses API に問い合わせを行うエージェントを作成します。

まずは、メインルーチンです。① API に送信する JSON を作成、② API をコール、最後に、結果を保存して UI に再表示しています。

Option Declare Private xns As NotesSession Private Const xcsBearer = "sk-xxxxx"   'API キーをここにセット Sub Initialize    Dim nuiw As New NotesUIWorkspace    Dim nuid As NotesUIDocument    Dim ndb As NotesDatabase    Dim nd As NotesDocument    Dim jnavRequest As NotesJSONNavigator    Dim jnavResponse As NotesJSONNavigator    '初期化    Set xns = New NotesSession    Set ndb = xns.CurrentDatabase    Set nuid = nuiw.Currentdocument    Set nd = nuid.Document   ' UI の文書は読み込みモードの前提    '① Request Body(JSON) の作成    Set jnavRequest = xGetRequest_JSON(nd)    Call xSetJSON(nd, "Request", jnavRequest)   'Request Body の保存    '② 問い合わせ実行    Set jnavResponse = xAskResponses(jnavRequest)    Call xSetJSON(nd, "Response", jnavResponse)   'Response の保存    '保存して開きなおす    Call nd.Save(True, False)    Call nuid.Close()    Call nuiw.EditDocument(False, nd) End Sub

作成する JSON は単純なものでした。

{    "model": "gpt-5-nano",    "input": "大阪府の県庁所在地は？" }

なので、この JSON を作成する関数はいたってシンプルです。

Function xGetRequest_JSON(vnd As NotesDocument) As NotesJSONNavigator    Dim jnav As NotesJSONNavigator    'RequestBody（JSON） の準備    Set jnav = xns.CreateJSONNavigator("")    '1.model    Call jnav.AppendElement(vnd.Model(0),"model")    '1.input    Call jnav.AppendElement(vnd.Prompt(0),"input")    Set xGetRequest_JSON = jnav End Function

続いて、Responses API に問い合わせを行う関数です。

Function xAskResponses(vjnavRequest As NotesJSONNavigator) As NotesJSONNavigator    Dim sURL As String    Dim http As NotesHTTPRequest    Dim jnav As NotesJSONNavigator    'HTTP リクエストの準備    Set http = xns.CreateHTTPRequest()    'HTTP ヘッダーの設定    Call http.SetHeaderField("Content-Type", "application/json")    Call http.SetHeaderField("Authorization", "Bearer " & xcsBearer)    'API 実行    http.PreferJSONNavigator = True    sURL = "https://api.openai.com/v1/responses"      'エンドポイント    Set jnav = http.Post(sURL, vjnavRequest.Stringify())    'Response をセット    Set xAskResponses = jnav End Function

戻り値はレスポンスの JSON で、NotesJSONNavigator のオブジェクトを返します。

最後は送受信した JSON を文書に記録する関数です。引数の NotesJSONNavigator から JSON を抽出し、指定したフィールドにセットします。その際、JSON のサイズと時刻も記録しています。

Private Function xSetJSON(vnd As NotesDocument, ByVal vsFld As String, vjnav As NotesJSONNavigator)    Dim nrti As NotesRichTextItem    Dim sText As String    On Error Resume Next    'JSON（文字列）を取得 と サイズの記録    If vjnav Is Nothing Then       sText = "（Nothing）"       Call vnd.ReplaceItemValue(vsFld & "_Size", "")    Else       sText = vjnav.Stringify()       Call vnd.ReplaceItemValue(vsFld & "_Size", Len(sText))    End If    '日時の記録    Call vnd.ReplaceItemValue(vsFld & "_DT", Now)    'JSON の記録    Call vnd.RemoveItem(vsFld & "_JSON")   'いったん削除してからセット    Set nrti = vnd.CreateRichTextItem(vsFld & "_JSON")    Call nrti.AppendText(sText) End Function

動作検証

ここまで出来上がったらテスト実行します。

AI model に gpt-5-nano を指定し、プロンプトを記述します。文書を保存して、エージェントを実行します。

うまくいくと、次のように送受信の結果が記録されます。

まとめと今後の予定

今回は Responses API に問い合わせを行う基本的な部分を作成しました。ここまでは、以前の Chat Completion API のサンプルと大差がなく、あまり目新しさがありませんでしたが、今後はこれを拡張しながら、Responses API のさまざまな機能を確認していきます。

まず、次回は、レスポンスの JSON から必要な情報を抽出する部分を作成します。

前回

連載：つないでみよう

次回

つないでみよう：#31） Responses API － 会話

今回から  Responses API を実際に使ってみましょう。まずは、会話から始めます。#2 で紹介した Chat Completion API と比較しながら進めたいと思います。

API のコールの仕方

まず、API の URL であるエンドポイントは以下の通りです。

Responses API	Chat Completion API
https://api.openai.com/v1/responses	https://api.openai.com/v1/chat/completions

HTTP ヘッダの指定方法には変化はないようです。どちらの API も以下の項目を指定します。

HTTP ヘッダ	設定値	補足
Content-Type	application/json	送信するリクエストは JSON
Authorization	Bearer （API キー）	別途取得した API キーを送信し認証

リクエストの記述は大きく変わっています。Chat Completion API では messages ノードに記述しましたが、Responses API では input ノードとなっています。

Chat Completion API では、構造がシンプルになっている点がありがたいですね。

Responses API	Chat Completion API
{    "model": "gpt-5-nano",    "input": "大阪府の県庁所在地は？" }	{    "model": "gpt-5-nano",    "messages": [       {          "role": "user",          "content": "大阪府の県庁所在地は？"       }    ] }

この事例では『大阪府の県庁所在地は？』とテキストで問い合わせるだけなのでシンプルな構造となっています。この input ノードの書き方で、テキストの問い合わせに画像を添えたり、柔軟に指定できます。結果的には、仕組みとしては messages ノードと大差ないと言えますね。

API コール

今回は、API の動作検証を兼ねて Postman でテスト実行してみます。

まず、”POST” を選択し、エンドポイントを入力します。ヘッダーには Authorization を追加し、API キーを指定します（Content-Type はデフォルトでセット済み）。最後に、ボディに送信する JSON を入力して完了です。

準備ができたら［送信］ボタンをクリックします。正しく送信できると、画面下部にレスポンスの JSON が表示されます。

Chat Completion API のレスポンスと比較しながら確認します。赤字の部分がリクエストに対する返答にあたる部分です。

Responses API

Chat Completion API

{    "id": "resp_xxxxx",    "object": "response",    "created_at": 1782125043,    "status": "completed",    "background": false,    "billing": {       "payer": "developer"    },    "completed_at": 1782125046,    "error": null,    "frequency_penalty": 0.0,    "incomplete_details": null,    "instructions": null,    "max_output_tokens": null,    "max_tool_calls": null,    "model": "gpt-5-nano-2025-08-07",    "moderation": null,    "output": [       {          "id": "rs_xxxxx",          "type": "reasoning",          "content": [],          "summary": []       },       {          "id": "msg_xxxxx",          "type": "message",          "status": "completed",          "content": [             {                "type": "output_text",                "annotations": [],                "logprobs": [],                "text": "大阪府の県庁所在地は大阪市です。"             }          ],          "role": "assistant"       }    ],          ・・・（省略）・・・ }

{    "id": "chatcmpl-xxxxx",    "object": "chat.completion",    "created": 1782126352,    "model": "gpt-5-nano-2025-08-07",    "choices": [       {          "index": 0,          "message": {             "role": "assistant",             "content": "大阪府の県庁所在地は大阪市です。",             "refusal": null,             "annotations": []          },          "finish_reason": "stop"       }    ],          ・・・（省略）・・・ }

Responses API は、Chat Completions API よりも汎用的かつ拡張性の高い API です。推論やツール実行などの情報を含めて返却するため、レスポンス JSON はより複雑な構造になっています。

output ノード内の要素で type が message となっているものが返答にとなります。output ノードは配列になっていて、リクエストに応じて要素数が可変となります。ですので、各要素の type を判定して返答を探す必要があります。

type にはさまざまな種類があり、抜粋すると次の通りです。

type	役割
message	最終回答
reasoning	内部推論の情報
function_call	関数（ツール）の呼び出し要求
function_call_output	関数実行結果
image_generation_call	画像生成の実行

会話の継続

Responses API では、会話の継続がサポートされています。

使い方は簡単で、previous_response_id に継続元のレスポンスを指定するだけです。具体的には、レスポンスの最初にある id（resp_ で始まる id）を指定するだけです。

Responses API	Chat Completion API
{    "model": "gpt-5-nano",    "previous_response_id": "resp_xxxxx",    "input": "そこの面積は？" }	{    "model": "gpt-5-nano",    "messages": [       {          "role": "user",          "content": "大阪府の県庁所在地は？"       },       {          "role": "assistant",          "content": "大阪府の県庁所在地は大阪市です。"       },       {          "role": "user",          "content": "そこの面積は？"       }    ] }

Chat Completion API では、過去の会話をリクエストの JSON に含める必要がありました。会話が長くなると送信する JSON が膨大になります。

Responses API で会話を継続を使えば、課金額の節約にもなりますね。

前回

連載：つないでみよう

次回

エージェントと実行対象③ - UnprocessedDocuments の特徴と注意点

前回は、UnprocessedDocuments と UpdateProcessedDoc を紹介しました。

UnprocessedDocuments でエージェントがまだ処理していない文書の取得、UpdateProcessedDoc で処理済みフラグを設定し、次の実行では対象外にできるという使い方でした。処理すべき文書を効率的に取得できる機能なのですが、その陰に Notes/Domino アプリ開発的に意識すべき重要な点が 3 つあります。

• ”未読/既読”に対する影響
• 最終更新日の変化
• エージェントの仕様変更時の影響

フィールドで管理

アプリ開発において、処理したかを記録するためには、フラグやステータスフィールドで管理するのが一般的です。例えば、次のようなプログラムです。

Dim ns As New NotesSession    Dim ndb As NotesDatabase    Dim nv As NotesView    Dim ndc As NotesDocumentCollection    Set ndb = ns.CurrentDatabase    Set nv = ndb.GetView("ByIsProcessed")   '処理済みフラグでソートされたビュー    Set ndc = nv.GetAllDocumentsByKey("0", True)   '未処理を検索    '未処理文書を順に処理    Dim nd As NotesDocument    Set nd = ndc.GetFirstDocument()    While Not(nd Is Nothing)       '（処理をここに記述）       nd.IsProcessed = "1"   '処理済みフラグをセット       Call nd.Save(True, True)   'フラグを保存       Set nd = ndc.GetNextDocument(nd)   '次の文書を取得    Wend

処理済みフラグ IsProcessed が "0" が未処理で、"1" が処理済みを表し、ビューで "0" の文書を検索して、ヒットした文書を順に処理をするという仕組みです。

ポイントは、Save メソッドをコールしている点です。文書が更新されるので、その文書が未読となってしまいます。

ちなみに、Save メソッドには引数が 3 つあって、最後の引数で未読をコントロールする機能があります。

ただ、ヘルプにも記載がある通り、この引数でコントロールできるのは処理を実行しているユーザだけです。その他ユーザに対してはすべて未読になるので、今回のような要件では効果がありません。

掲示板のように未読情報が重要なアプリでは、システム上の処理で未読になってしまっては、仕様上問題となります。例えば、削除日の１週間前に削除を通知する機能を作ったとしましょう。エージェントで送信済みフラグを書き込むと、未読になります。削除前なのに突然未読になり、逆に目立ってしまうということになってしまいます。

また、保存するということは、最終更新日が変化します。ビューで最終更新日順に表示しているビューではトップに表示されます。また、10 年更新がない文書は削除する機能があった場合、また 10 年間保持されることになります...。

文書が更新されるということは、複製の対象になり、すべての複製先のサーバに反映される点にも注意が必要ですね。

UnprocessedDocuments の注意点

UnprocessedDocuments、UpdateProcessedDoc を使った処理済みフラグの管理では、文書を更新しません。よって、先の「フィールドで管理」で挙げた未読/既読情報や最終更新日は変化しません。

だからといって、この方法が全能で優れているわけではなく、使用時には注意があります。

それは、エージェントを更新するとリセットされるということです。そのため、機能変更などによりエージェントを修正すると、次回実行時には修正前に処理した文書も含めて実行対象となります。

14.5.1 を使って検証したところ、エージェントのコードに変更がなければ処理済みフラグはリセットされないようです。例えば、エージェントを開き再保存したり、「すべての LotusScript をリコンパイル」しただけではクリアされませんでした。ただ、機能は一切変えず、コメントを追記しただけでもフラグはクリアされてしまいました。内部的にどのように管理しているのでしょうね ??

機能強化はもちろん、バグ修正、リファクタリングなどを行う時の制限となりうるのです。「作成または変更されたすべての文書」を使って効率的に文書を取得しているのに、エージェントの最終更新日と比較するのもなんだか変ですよね...

ただ、この問題には回避策があります。

それは、エージェント内のコードをすべてスクリプトライブラリに外だしすることです。例えば、エージェントで行う処理の中身を UnprocessedDocsMain 関数に記述し、lsUnprocessedDocs ライブラリの中に記述します。

そしてエージェントでは、次のようにライブラリの関数を呼ぶだけにします。

Option Declare Use "lsUnprocessedDocs" Sub Initialize    Call UnprocessedDocsMain() 'エージェントの本体 End Sub

将来仕様が変わっても更新するのは、lsUnprocessedDocs ライブラリとなるので、エージェントは更新されません。これにより処理済みフラグを維持することができます。

また、この処理済みフラグはエージェントごとに保持される仕組みなのですが、各文書に対して、どのエージェントで処理済みなのか確認するすべがありません。フィールドを利用したフラグ管理の場合には、文書のプロパティや確認用のビューを作成するなど、効率的に調査ができます。

このように UnprocessedDocuments の利用では、開発終了後、運用フェーズになってからの注意点が多いことに注意しましょう。

まとめ

処理済みフラグの管理方法には 2 種類あることを紹介しました。改めてそれぞれの特徴を整理しましょう。

	UnprocessedDocuments	フィールドで管理
文書の更新	なし	あり（最終更新日が変化）
未読/既読	変化なし	未読になる
調査/確認	対象文書を確認できない	文書のプロパティやビューなどで確認可能
処理時刻	不明 別途処理ログを出力するなどすれば確認可能	最終更新日やフィールドに記録することで確認できる

これまでの経験でいうと、障害や問い合わせ対応は想定外な場合が多いです。その際により詳細に情報収集できる、フィールドで管理する方法が安心だといえます。文書を更新しても構わない（未読/既読にあまりこだわらない）場合は、ステータスを文書に保存する方法をおススメします。

UnprocessedDocuments を使った処理済みフラグの管理は、文書を更新できないというような条件がある場合にとどめたほうが良いと思います。

どちらの方法も、メリット/デメリットがありますので、特徴を理解したうえで使い分けましょう。

エージェントと実行対象② - UpdateProcessedDoc

前回は、エージェントの実行対象と UnprocessedDocuments プロパティについて整理しましたが、前回触れられなかった「作成または変更されたすべての文書」をいう設定を紹介します。

まずは単純に前回と同じプログラムで、最後に取得した文書の件数を表示するように修正します。

Dim ns As New NotesSession    Dim ndb As NotesDatabase    Dim ndc As NotesDocumentCollection    Set ndb = ns.CurrentDatabase    Set ndc = ndb.UnprocessedDocuments   '未処理の文書の一覧    MsgBox ndc.Count   '文書件数を表示

エージェントのプロパティでは対象に「作成または変更されたすべての文書」を指定します。

実行するとデータベース内にすべての文書数が返されます。

「なるほど、初回の実行だから『すべての文書』が返ってくるのか...」

と思いながら、もう一度エージェントを実行します。すると、またしても『すべての文書』が対象となってしまいます。

「前回実行時に処理した文書は除外されるのでは？」

そう思うかもしれません。そこで登場するのが UpdateProcessedDoc メソッドです。

UpdateProcessedDoc メソッド

これは NotesSession クラスのメソッドで、デザイナーヘルプによると『エージェントで処理された文書に処理済みのマークを付けます。』とあります。構文は、

Call notesSession.UpdateProcessedDoc( notesDocument )

となっており、処理済みにしたい文書を引数にセットします。

たとえば、コレクションから最初の文書を取得して処理する場合、次のようなコードとなります。

Dim ns As New NotesSession    Dim ndb As NotesDatabase    Dim ndc As NotesDocumentCollection    Set ndb = ns.CurrentDatabase    Set ndc = ndb.UnprocessedDocuments      '１件目の処理    Dim nd As NotesDocument    Set nd = ndc.GetFirstDocument()   '１件目の文書を取得    '（処理をここに記述）    Call ns.UpdateProcessedDoc(nd)   '処理済みフラグをセット

対象の文書をすべて処理する場合には、GetNextDocument を使用して順に処理します。

'すべての文書を処理    Dim nd As NotesDocument    Set nd = ndc.GetFirstDocument()    While Not(nd Is Nothing)       '（処理をここに記述）       Call ns.UpdateProcessedDoc(nd)   '処理済みフラグをセット       Set nd = ndc.GetNextDocument(nd)   '次の文書を取得    Wend

まとめ

今回は、「作成または変更されたすべての文書」の設定と UpdateProcessedDoc というメソッドの使い方を紹介しました。この機能を利用すると、新たに作成や更新された文書だけを取得する処理が簡単に記述できるようになります。

対象文書を取得する UnprocessedDocuments プロパティが NotesDatabase クラス、処理済みフラグをセットするメソッドが NotesSession クラスとオブジェクトが違うので、少々わかりにくい点に注意しましょう。

なお、この機能はエージェントの処理済みフラグ、要は Notes/Domino の組み込みの機能を利用します。この処理済み情報は文書そのものに保存されるわけではありません。そのため、エージェントの修正や設計変更時には思わぬ挙動につながることがあります。次回はそのあたりの注意点について紹介したいと思います。

エージェントと実行対象① - UnprocessedDocuments

NotesDatabase クラスには UnprocessedDocuments というプロパティがあります。これを使えば「現在実行中のエージェントにとって未処理の文書集合」 を取得することができます。

例えば、

Dim ns As New NotesSession    Dim ndb As NotesDatabase    Dim ndc As NotesDocumentCollection    Set ndb = ns.CurrentDatabase    Set ndc = ndb.UnprocessedDocuments   '未処理の文書の一覧

と記述すると、ndc に未処理の文書の一覧が取得できます。

どの文書が返る？

では、未処理の文書とは具体的にどのように決定されるのでしょうか？実はエージェントのプロパティにある ”対象” により変化します。

「データベースのすべての文書」を選択するとその名称の通りの動作をします。よって、以下の記述はどちらも同じ結果を返すことになります。

Set ndc = ndb.UnprocessedDocuments    Set ndc = ndb.AllDocuments

それ以外の選択肢についての挙動を順にまとめます。

ビューのすべての文書

この設定も名称の通りの動作となります。現在のビューに存在するすべての文書が返されます。

ビューが基準となりますので、文書を開いている状態など、ビュー以外を開いている状態では、エージェントの実行自体がエラーとなります。

ビューのすべての未読文書

この設定もビューを基準とした機能ですので、ビューを開いた状態で実行する必要があります。

ビュー内の未読文書だけを抽出してくれるのですが、ビューの設計で未読文書を表示していなくても構わないようです。こんな設計はわかりにくいだけなのでおすすめはしませんが...

もちろん、データベースのプロパティで「未読マークを使用しない」を設定すると、この機能は動作しなくなります。この場合、UnprocessedDocuments は Count が 0 の空のコレクションを返します。

すべての選択文書

この設定の挙動は３パターンに分かれます。

まず、ビューを表示していて、カーソルで文書を選んだ状態です。この場合は、カーソルのある文書だけが返ります。

同じビューでも、チェックマークを付けて文書を選択している場合は、選択した文書が返ります。この時カーソルのある文書は返されません。例えば以下の例の場合では３文書が返され、「総務部」の文書は含まれません。

ビューではなく文書を開いている場合には、開いている文書１つだけを含むコレクションが返されます。「ビューのすべての文書」や「ビューのすべての未読文書」のようにエラーになりません。

選択肢が「すべての選択文書」となっており”ビューの”といついていない理由なのかもしれませんね。

ただ、ワークスペースでDBアイコンを選択した状態でエージェントを実行すると『選択したエージェントはビューウィンドウから実行してください。』とエラーが出ます。このエラーメッセージにはいただけないですね...。

続きは次回

今回は、エージェントの実行対象と UnprocessedDocuments プロパティの関係についてまとめました。まだ、「作成または変更されたすべての文書」が残っていますが、この設定については次回紹介したいと思います。

ドメイン検索：索引の再作成の注意点

ドメイン検索について注意点をまとめた記事を以前に書かせていただきました。

• ドメイン検索 と 運用上の注意点

その中で、索引の更新には削除文書の反映が含まれないため定期的に索引を再作成することをおススメしました。

今回はその具体的な方法と最新バージョン 14.5.1 で遭遇した新たな現象についてまとめます。

索引を削除するには？

まず、索引の削除のコマンドは load domidx -d です。このコマンドを実行すると索引のフォルダがまるごと消去されます。

次に索引を作成をしようとしたタイミングで、既存の索引が何もないので、対象の全文書を索引するので、再作成となるということですね。

また、索引の削除に関しては下記の技術文書が公開されています。

• ドメイン検索のインデックスを再作成するためには Domino サーバーを再起動する必要がある

2020 年の記事なので現在は改善されているかもしれませんが、再作成前に再起動するほうが良いと考えられます。

サーバ環境や対象の DB 数、文書サイズにもよりますが、索引の再作成には通常長い時間が必要となります。索引作成中は正しい検索結果を得られませんので、業務に影響がないようにするためには、土日などの週末を利用するのがおススメです。

索引の再作成の設定

まず、索引の更新は毎日 7:30、12:00、21:00 の 3 回行う前提とします。

この環境において、土曜日を索引再作成の日として、7:30 の索引作成前に索引を削除します。これで土曜の朝は、索引がない状態で索引を更新しようとするので、すべての索引を再作成することになります。

索引削除の設定はプログラム文書で行います。

プログラム文書を新規で作成し、load domidx -d を実行します。索引作成開始時刻の 30 分前の 7:00、土曜日を指定します。

その後、7:30 の索引作成に間に合うように、サーバを OS ごと再起動させます。

14.5.1 では追加の設定が必要

先日ドメイン検索サーバを 14.5.1 にアップグレードした際、気が付いた問題があります。

14.0 までは load domidx -d の実行だけで索引が削除できていたのですが、14.5.1 では削除されなくなっていたんです（14.5 は未検証なので不明）。調査した結果、14.5.1 では稼働中の domidx タスクを停止しておかないと、load domidx -d が正しく動作してくれないようです。

• 別の domidx プロセスが実行されている場合に「domidx -d」コマンドでドメイン索引を削除できない

これに対応するため、14.5.1 では load domidx -d の実行前（例えば 10 分前）にタスクを停止させます。具体的には以下のプログラム文書を追加することになります。

まとめ

今回は、ドメイン検索の索引再作成の方法についてまとめました。

14.5.1 では少し挙動が違うので注意してください。というか、仕様変更の理由がファイルの共有違反の回避のようなので、過去のバージョンでタスクを停止することなく、索引を削除できたことの方が問題かもしれませんね。

ただ、索引の更新に文書の削除が反映されないことがそもそもの問題だと思うで、早く改善してほしいと思います...。