エージェント365の設定方法

Agent 365 CLI では、テナントとその他の詳細を把握して、エージェント ブループリントなどの必要なエージェント リソースを作成する必要があります。 CLIはこの情報を作業ディレクトリ内の中央設定ファイル「 a365.config.json 」に保存します。 CLIのすべてのコマンドはこの設定ファイルを使用します。

[前提条件]

開始する前に、次の前提条件を満たしていることを確認してください。

• Agent 365 CLI - Agent 365 CLI インストールを参照してください。

必要なアクセス許可:

• 次のいずれかのロールを持つ有効なMicrosoft Entra テナント ユーザー。
  • グローバル管理者
  • エージェントID管理者
  • エージェントIDデベロッパー

Agent 365のCLIを設定してください

a365 config initコマンドは、すべてのAgent 365 CLIコマンドで使用される中央設定ファイルa365.config.jsonをワーキングディレクトリに作成します。 CLI は、Azure CLI統合とスマートな既定値を備えた対話型ウィザードを提供し、手動入力を最小限に抑えます。

構成の初期化

インタラクティブ設定ウィザードを開始するには a365 config init コマンド を実行してください:

a365 config init

ウィザードでは、Azure CLI統合とスマートな既定値を使用して、手動入力を最小限に抑えます。 次の指示が表示されます

ウィザードでは、関連するリソース名 (エージェント ID、ブループリント、エージェント ユーザー) が自動的に生成され、プロジェクトの種類が検証されます。 保存する前に、必要に応じて外部リソース (Teams のプレゼンス ファイルやOneDrive ファイルなど) のカスタム ブループリントアクセス許可を構成し、生成された名前をカスタマイズできます。

設定ファイル構造について詳しくはこちら

カスタム ブループリントのアクセス許可

エージェントが既定のセット (Microsoft Graph、Messaging Bot API、Observability API、Power Platform) を超えるリソースにアクセスする必要がある場合は、customBlueprintPermissions の a365.config.json フィールドでそれらを宣言します。

{
  "customBlueprintPermissions": [
    {
      "resourceAppId": "00000003-0000-0000-c000-000000000000",
      "resourceName": "Microsoft Graph",
      "scopes": ["Mail.Read", "Mail.Send"]
    },
    {
      "resourceAppId": "<your-api-app-id>",
      "resourceName": "My Custom API",
      "scopes": ["MyApi.ReadWrite"]
    }
  ]
}

a365.config.jsonにカスタム アクセス許可を追加した後、ブループリントに適用します。

a365 setup permissions custom

または、完全なセットアップに含めます。

a365 setup all

エージェント365の設定ファイルを検証する

Agent 365は開発ライフサイクル全体を通じて複数の設定ファイルを使用します:

設定完了後、以下の項目が揃っているか確認してください:

a365.config.json ファイルの作成を確認

a365.config.jsonファイルが存在するかどうかを目で確認してください。 または、この検証を自動化するためにスクリプト内の Test-Path PowerShellコマンドを使うこともできます。

# Check file exists in current working directory
Test-Path a365.config.json
# Should return: True

a365.config.json設定データの検証

a365 config displayコマンドを実行して、現在のAgent 365のCLI設定を確認します。

a365 config display

このコマンドの出力は次のようになります:

{
  "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
  "environment": "prod",
  "aiTeammate": true,
  "clientAppId": "00001111-aaaa-2222-bbbb-3333cccc4444",
  "agentIdentityDisplayName": "your-agent-name Identity",
  "agentBlueprintDisplayName": "your-agent-name Blueprint",
  "agentUserPrincipalName": "youragent@yourtenant.onmicrosoft.com",
  "agentUserDisplayName": "your-agent-name Agent User",
  "managerEmail": "manager@yourtenant.com",
  "agentUserUsageLocation": "usage-location",
  "deploymentProjectPath": "C:\\path\\to\\your\\project",
  "agentDescription": "your-agent-name - Agent 365 Agent"
}

検証チェックリスト

✅ すべてのフィールドは有効な値を持ちます(空文字列やヌルはありません)
✅ tenantId は有効な GUID です
✅ clientAppId 有効なGUID(カスタムクライアントアプリの登録)です。
✅ managerEmail テナントドメインを使います
✅ deploymentProjectPath エージェントコードディレクトリを指し示します
✅ agentUserPrincipalName フォーマットに従います agentname@tenant.com
✅ environment は設定されます(通常 prod)

設定が期待値と一致しない場合は、トラブルシューティングの セクション で詳細な解決策をご覧ください。

a365.generated.config.json ファイルに .gitignore を追加します。 このファイルには生成されたシークレットが含まれており、ソース管理にコミットしないでください。

次のステップ

すべて問題なければ、準備ができています。

--agent-name を使用した構成不要のセットアップ

a365.config.json ファイルを作成しなくても、(AI チームメイトではなく) エージェントをプロビジョニングできます。 CLI は、実行時に必要な値を自動的に解決します。

# Provision an Agent without a config file
a365 setup all --agent-name <your-agent-name>

--agent-nameを指定する場合:

• CLI は、自動検出します。 必要に応じて、 --tenant-id <id> でオーバーライドします。
• CLI は、クライアント アプリを解決するために、テナント内の Agent 365 CLI という名前の Entra アプリ登録を検索 します。 構成に clientAppId を含める必要はありません。
• 配置プロジェクトのパスは、既定で現在のディレクトリに設定されます。 エージェント プロジェクト フォルダーからコマンドを実行します。

構成ファイルなしでプロビジョニングされたリソースをクリーンアップするには:

a365 cleanup --agent-name <your-agent-name>

クリーンアップでは、ブートストラップ セットアップによって書き込まれたグローバルに生成された構成ファイルからリソース ID が読み取られます。そのため、 a365.config.json は必要ありません。

エージェント ID モード

aiTeammate フィールドは、エージェント インスタンスのプロビジョニング方法と実行時に実行される ID を制御します。 エージェントが実行する必要がある内容に基づいて、適切なモードを選択します。

標準モード (aiTeammate: false) - 既定

エージェントがサービスまたはバックエンド統合 (メッセージの処理、イベントへの応答、API の呼び出し) として機能する場合は、インスタンスごとにユーザー ID を必要とせずに、このモードを使用します。 このモードにより、構築できるエージェントの範囲が広がります。エージェント 365 プラットフォームと通信するすべてのサービスは、ユーザーを表していない場合や、ユーザー向けのコラボレーション エクスペリエンスに参加していない場合でも、エージェントとして登録できます。

このモードが既定です。 フラグを指定せずにセットアップを実行するか、明示的に --aiteammate false 渡します。

# Standard setup (default)
a365 setup all

# Equivalent explicit form
a365 setup all --aiteammate false

エージェントは、 --agent-nameを使用した構成不要のプロビジョニングもサポートします。 --agent-name を使用した構成不要のセットアップを参照してください。

AI チームメイト モード (aiTeammate: true)

このモードは、エージェントが人間のユーザーと一緒に一流の参加者として機能する必要がある場合に使用します 。たとえば、会議への参加、ユーザーの代わりにメッセージを送信する、ワークフローでタスクを割り当てるなどです。 このモードでプロビジョニングされたエージェント インスタンスは、専用のユーザー ID を受け取り、プラットフォームが各インスタンスを個別に識別して対話できるようにします。

AI チームメイトのセットアップには、a365.config.jsonで初期化されたa365 config initが必要です。 --aiteammate trueを渡して、このモードを選択します。

a365 setup all --aiteammate true

トラブルシューティング

これらのステップを使って、 a365.config.json とAgent 365 CLIに関する一般的な問題を迅速に診断し解決しましょう。

• 構成ファイルが存在しない
• 構成値が見つからないか無効です
• テナントまたはサブスクリプションが無効です
• カスタム クライアント アプリの検証が失敗する
• 無効なエージェント ユーザー プリンシパル名

構成ファイルが存在しない

症状：CLIコマンドは「Configuration Not found」で失敗するか、Test-Path a365.config.jsonFalse返します。

解決策: 新しい a365.config.json ファイルを作成します。

構成を初期化する手順を完了します。

構成値が見つからないか無効です

症状： 設定ファイルは存在しますが、空欄や検証エラーがあります。

解決策:手順に従って設定データを確認a365.config.jsonしてください。

もしどの項目でも間違っている場合:

• 選択肢1:ウィザードをa365 config initコマンドで再実行してください。
• オプション2: 正しい値を手動で a365.config.json 編集してください。

テナントまたはサブスクリプションが無効です

症状： CLIは認証や認可エラーで失敗します。

Solution:

これらのコマンドを使用して、Azureで再認証し、サインインしたアカウントを確認し、正しいサブスクリプションに切り替えて、Agent 365 CLI 構成を再初期化します。

# Re-authenticate with Azure
az login

# Verify you're logged into the correct account
az account show

# If needed, switch to the correct subscription
az account set --subscription "<subscription-name-or-id>"

# Re-initialize configuration
a365 config init

カスタム クライアント アプリの検証が失敗する

症状： カスタムクライアントアプリIDの検証時に設定ウィザードが失敗します。

解決策:カスタムクライアントアプリの登録を確認し、必要な権限と管理者の同意がすべてあるか確認してください。

無効なエージェント ユーザー プリンシパル名

症状： 構成中にエージェント ユーザー プリンシパル名の検証が失敗する。

ソリューション： UPN が username@domain形式に従っていることを確認します。 たとえば、 demo.agent@contoso.onmicrosoft.com です。 ドメイン サフィックスが見つからないのが最も一般的な原因です。