Graph APIをAIに使わせる!Azure AI Agentの関数呼び出し活用術
はじめに
MS開発部の松坂です。
Azure OpenAI Serviceでは、「関数呼び出し(Function Calling)」機能を使って、AIが外部サービスに動的にアクセスすることができます。
本記事では、Azure AI AgentとMicrosoft Graph APIを連携し、AIにOutlookメール情報を取得させる方法を解説します。
C#で実装し、AIから安全にGraph APIを操作できる構成を構築します。
「業務に合わせたAIエージェントを作ってみたい」「API呼び出しをAIにやらせたい」
そんな方におすすめの内容です。
構成概要
-
Azure AI Agent Service
-
Outlook(Microsoft Graph API経由でメール情報取得)
-
C# SDK
1. 事前準備
-
Azureサブスクリプション
-
Azure AI Agent Serviceのプロジェクト作成
-
Microsoft Graph APIのアプリ登録(Outlookメールアクセス権限付与)
-
必要なNuGetパッケージのインストール(例:
Azure.Identity,Microsoft.Graph,azure.ai.projects等)
2. Outlookのメールを取得する関数の作成
Azure AI Agentの関数呼び出しを用いてOutlookのメール情報を取得する関数を作成します。 まずはエージェントとGraph APIを連携するために必要な検索パラメータのDTOクラスを作成します。今回は簡易的なものとして、送り先と時刻でチャット検索できるように構築します。
public class MailSearchDto
{
-----------------省略---------------
public string? From { get; set; }
public DateTime? AfterDate { get; set; }
public DateTime? BeforeDate { get; set; }
-----------------省略---------------
}
次に、Graph APIを用いてメールを検索する実行関数を作成します。
今回は、Graph APIを実行する際はあらかじめトークンが取得できている前提で定義していきます。WebアプリならFrontEndから、ローカルアプリ等であればDefaultCredentialから取得できると思います。
using Microsoft.Graph;
using Microsoft.Kiota.Abstractions.Authentication;
public async Task<string> GetMailData(Models.MailSearchDto request, string incomingToken)
{
var filters = new List<string>();
-----------------省略---------------
if (!string.IsNullOrEmpty(request.From))
{
filters.Add($"from/emailAddress/address eq '{request.From}'");
}
if (request.AfterDate.HasValue)
{
filters.Add($"receivedDateTime ge {request.AfterDate.Value.ToUniversalTime():o}");
}
if (request.BeforeDate.HasValue)
{
filters.Add($"receivedDateTime le {request.BeforeDate.Value.ToUniversalTime():o}");
}
CustomTokenProvider provider = new CustomTokenProvider();
provider.token = incomingToken;
var authenticationProvider = new BaseBearerTokenAuthenticationProvider(provider);
var graphClient = new GraphServiceClient(authenticationProvider);
var filterQuery = filters.Any() ? string.Join(" and ", filters) : "";
var result =(filterQuery =="")? await graphClient.Me.Messages.GetAsync() : await graphClient.Me.Messages.GetAsync((request) =>
{
request.QueryParameters.Filter = filterQuery;
});
var sb = new StringBuilder();
foreach (var msg in result.Value)
{
sb.AppendLine($"From: {msg.From?.EmailAddress?.Address}");
sb.AppendLine($"Subject: {msg.Subject}");
sb.AppendLine($"Received: {msg.ReceivedDateTime}");
sb.AppendLine();
}
return sb.ToString();
}
public class CustomTokenProvider : IAccessTokenProvider
{
public string token { get; set; }
public AllowedHostsValidator AllowedHostsValidator => throw new NotImplementedException();
public Task GetAuthorizationTokenAsync(Uri uri, Dictionary<string, object>? additionalAuthenticationContext = null, CancellationToken cancellationToken = default)
{
return Task.FromResult(token);
}
}
次にエージェントを呼び出す関数を定義します。
FunctionToolDefinition getMailDataTool = new(
name: "getMailData",
description: "検索したい情報からメール情報を取得します。",
parameters: BinaryData.FromObjectAsJson(
new
{
Type = "object",
Properties = new
{
-----------------省略---------------
From = new
{
Type = "string",
Description = "差出人のメールアドレス"
},
AfterDate = new
{
Type = "string",
Description = "指定日以降のメール"
},
BeforeDate = new
{
Type = "string",
Description = "指定日以前のメール"
}
-----------------省略---------------
}
},
new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }
)
);
また、C#ではエージェントが適切に関数を実行するためにヘルパー関数を定義する必要があります。
なお、プロパティ名の大文字・小文字の区別には注意が必要です(例: ‘From’ や ‘from’ など)。Microsoft Graph APIおよびAzure AI Agent SDK間で命名規則の違いがあるため、明示的なマッピングが必要になる場合があります。
async Task GetResolvedToolOutput(RequiredToolCall toolCall,string incomingToken)
{
if (toolCall is RequiredFunctionToolCall functionToolCall)
{
using JsonDocument argumentsJson = JsonDocument.Parse(functionToolCall.Arguments);
if (functionToolCall.Name == getMailDataTool.Name)
{
MailSearchDto mailSearchDto = new MailSearchDto();
-----------------省略---------------
if (argumentsJson.RootElement.TryGetProperty("from", out var fromProp))
{
mailSearchDto.From = fromProp.GetString();
}
if (argumentsJson.RootElement.TryGetProperty("afterDate", out var afterDateProp))
{
if (DateTime.TryParse(afterDateProp.GetString(), out var afterDate))
{
mailSearchDto.AfterDate = afterDate;
}
}
if (argumentsJson.RootElement.TryGetProperty("beforeDate", out var beforeDateProp))
{
if (DateTime.TryParse(beforeDateProp.GetString(), out var beforeDate))
{
mailSearchDto.BeforeDate = beforeDate;
}
}
return new ToolOutput(toolCall.Id, await GetMailData(mailSearchDto, incomingToken));
}
}
return null;
}
3. Azure AI Agent のエージェント作成
次にAzureAIAgentのクライアント初期化からエージェント作成を行います。using Azure.Identity;
using Azure.AI.Projects;
var connectionString = Environment.GetEnvironmentVariable("PROJECT_CONNECTION_STRING");
var credential = new DefaultAzureCredential();
var projectClient = AIProjectClient.FromConnectionString(credential, connectionString);
※接続文字列はAzureポータルから取得し、環境変数に設定してください。
Response agentResponse = await projectClient.CreateAgentAsync(
model: "gpt-4o",
name: "SDK Test Agent - Functions",
instructions: "あなたはメールを検索するエージェントです。指示された内容で検索を行い、簡潔に回答をまとめてください。",
tools: new List { getMailDataTool }
);
Agent agent = agentResponse.Value;
エージェント作成時には、先ほど定義したメール取得用のFunctionToolDefinitionをtoolsとして設定します。
4. スレッドの作成
Response threadResponse = await projectClient.CreateThreadAsync();
AgentThread thread = threadResponse.Value;
threadID = thread.Id;
Response messageResponse = await projectClient.CreateMessageAsync(
thread.Id,
MessageRole.User,
userMessage);
ThreadMessage message = messageResponse.Value;
スレッド作成から、ユーザーメッセージ作成までは基本的な形と変わりません。
※userMessageには任意の質問するチャット内容を入れてください。5. メール取得クエリの実行
Response runResponse = await client.CreateRunAsync(thread, agent);
// この部分は、ツール実行とポーリング処理のループです。
// 必要に応じてエージェントからのアクションを処理します。
do
{
await Task.Delay(TimeSpan.FromMilliseconds(500));
runResponse = await projectClient.GetRunAsync(thread.Id, runResponse.Value.Id);
if (runResponse.Value.Status == RunStatus.RequiresAction
&& runResponse.Value.RequiredAction is SubmitToolOutputsAction submitToolOutputsAction)
{
List toolOutputs = new();
// ツールの実行が要求された場合、各ツール呼び出し(toolCall)に対して対応する出力を取得します。
// ここでは、事前に定義したGetResolvedToolOutput関数を使って、Graph APIによるメール検索を実行します。
foreach (RequiredToolCall toolCall in submitToolOutputsAction.ToolCalls)
{
toolOutputs.Add(await GetResolvedToolOutput(toolCall, token));
}
runResponse = await projectClient.SubmitToolOutputsToRunAsync(runResponse.Value, toolOutputs);
}
}
while (runResponse.Value.Status == RunStatus.Queued
|| runResponse.Value.Status == RunStatus.InProgress);
// 最新のメッセージを取得
Response<PageableList> messagesResponse = await client.GetMessagesAsync(thread.Id);
IReadOnlyList messages = messagesResponse.Value.Data;
// エージェントの応答メッセージ(Role: agent)の中で最も新しいものを取得します。
ThreadMessage? lastAssistantMessage = messages
.OrderByDescending(m => m.CreatedAt)
.FirstOrDefault(m => m.Role == MessageRole.Agent);
if (lastAssistantMessage != null && lastAssistantMessage.ContentItems.FirstOrDefault() is MessageTextContent textContent)
{
Console.WriteLine(textContent.Text);
}
C#では先ほど作成したヘルパー関数をエージェント実行中に呼び出すよう設定をする必要があります。
ツールの実行状態および、エージェントの実行状態を見て適切なエラー処理やレスポンスの設定を行ってください。
6. 動作例
今回は動作確認の例としてReact+TypeScriptでトークンを取得し、上記内容をバックエンドでAPI通信を通じて送受信処理を実行します。
MSALを使ってサインインし、トークンを取得して実行します。
// src/authConfig.ts
export const msalConfig = {
auth: {
clientId: "YOUR_CLIENT_ID",
authority: "https://login.microsoftonline.com/YOUR_TENANT_ID",
redirectUri: "http://localhost:3000",
},
};
export const loginRequest = {
scopes: ["User.Read", "Mail.Read"],
};
Graph API呼び出しの例
import { useMsal } from "@azure/msal-react";
---省略---
const { instance, accounts } = useMsal();
const response = await instance.acquireTokenSilent({
...loginRequest,
account: accounts[0],
});
const data = await getInboxMails(response.accessToken);
---省略---
// 指定されたアクセストークンを使って、バックエンド経由でメール検索エージェントにリクエストを送信します。
// `content` にはユーザーの検索メッセージ(例: "5月以降の〇〇さんからのメールを教えて")を渡します。
export async function getInboxMails(accessToken: string) {
const response = await fetch(
"/agent/send",
{
method: "POST",
headers: {
Authorization: `Bearer ${accessToken}`,
},
body: JSON.stringify({ message: content })
}
);
return response.json();
}
7. おわりに
本記事では、Azure OpenAIのFunction Calling機能を使い、AIエージェントがC#経由でGraph APIを呼び出し、Outlookメールを動的に取得する方法を紹介しました。
このアプローチにより、業務に最適化された独自のAIアシスタントを構築することが可能になります。
Graph APIを使えば、メールだけでなく予定表、連絡先、ユーザー情報などへのアクセスも可能です。
AIとAPIの橋渡しをすることで、実用的かつ拡張性の高いAIエージェントが生まれます。
次は、メール要約、重要度判定、Teams連携など、用途に応じて機能を拡張してみてください。
以上、最後までご愛読いただき
ありがとうございました。
お問い合わせは、
以下のフォームへご連絡ください。





