Aracılığıyla paylaş

Microsoft Agent 365 SDK'sını kullanarak aracıları test edin

Önemli

Microsoft Agent 365'e erken erişim elde etmek için Frontier önizleme programının bir parçası olmanız gerekir. Frontier sizi Doğrudan Microsoft'un en son yapay zeka yenilikleri ile bağlar. Sınır önizlemeleri, müşteri sözleşmelerinizin mevcut önizleme koşullarına tabidir. Bu özellikler hala geliştirme aşamasında olduğundan, bunların kullanılabilirliği ve özellikleri zaman içinde değişebilir.

Aracınızı Aracılar Deneme Alanı'nda yerel olarak test etme Bu kılavuz, Aracılar Oyun Alanı test aracısıyla geliştirme ortamınızı ayarlamayı, kimlik doğrulamasını yapılandırmayı ve aracınızın işlevselliğini doğrulamayı kapsar.

Aracınız yerel olarak çalıştıktan sonra, Teams gibi Microsoft 365 uygulamalarında test etmek için dağıtabilir ve yayımlayabilirsiniz.

Önkoşullar

Başlamadan önce, aşağıdaki ön koşulların hazır olduğundan emin olun:

Yaygın önkoşullar

Dile özgü önkoşullar

  • Python 3.11+: python.org veya Microsoft Store'dan indirin
  • uv paket yöneticisi: kullanarak uv yükleme pip install uv
  • Yüklemeyi doğrulayın

Aracı test ortamını yapılandırma

Bu bölüm ortam değişkenlerini ayarlamayı, geliştirme ortamınızın kimliğini doğrulamayı ve Test için Agent 365 destekli aracınızı hazırlamayı kapsar.

Aracı test ortamınızı ayarlamak sıralı bir iş akışını izler:

  1. Ortamınızı yapılandırma - Ortam yapılandırma dosyanızı oluşturma veya güncelleştirme

  2. LLM yapılandırması - API anahtarlarını alma ve OpenAI veya Azure OpenAI ayarlarını yapılandırma

  3. Kimlik doğrulamayı yapılandırma - Aracı kimlik doğrulamayı ayarlama

  4. Ortam değişkenleri başvurusu - Gerekli ortam değişkenlerini yapılandırın:

    1. Kimlik doğrulama değişkenleri
    2. MCP uç nokta yapılandırması
    3. Gözlemlenebilirlik değişkenleri
    4. Aracı uygulama sunucusu yapılandırması

Bu adımları tamamladıktan sonra aracınızı Agents Playground'da test etmeye başlayabilirsiniz.

5. Adım: ortamınızı yapılandırma

Yapılandırma dosyanızı ayarlayın:

cp .env.template .env

Not

Gerekli alanları gösteren yapılandırma şablonlarını bulmak için Microsoft Agent 365 SDK örneklerine bakın.

2. Adım: LLM yapılandırması

Yerel test için OpenAI veya Azure OpenAI ayarlarını yapılandırın. Önkoşullardan elde edilen API anahtarlarınızı ve hizmet uç noktalarınızı tüm model parametreleriyle birlikte yapılandırma dosyanıza ekleyin.

Dosyanıza .env ekleyin:

# Replace with your actual OpenAI API key
OPENAI_API_KEY=

# Azure OpenAI Configuration
AZURE_OPENAI_API_KEY=
AZURE_OPENAI_ENDPOINT=
AZURE_OPENAI_DEPLOYMENT=
AZURE_OPENAI_API_VERSION=

Python LLM ortam değişkenleri

Değişken Description Zorunlu Örnek
OPENAI_API_KEY OpenAI hizmeti için API anahtarı OpenAI için sk-proj-...
AZURE_OPENAI_API_KEY Azure OpenAI hizmeti için API anahtarı Azure OpenAI için: testini çalıştırın a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI hizmet uç noktası URL'si Azure OpenAI için: testini çalıştırın https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Azure OpenAI'de dağıtım adı Azure OpenAI için: testini çalıştırın gpt-4
AZURE_OPENAI_API_VERSION Azure OpenAI için API sürümü Azure OpenAI için: testini çalıştırın 2024-02-15-preview

3. Adım: Aracı kimliği kimlik doğrulaması için kimlik doğrulama değerlerini yapılandırma

Aracı şema kimlik bilgilerinizi almak için A365 CLI a365 config display komutunu kullanın.

a365 config display -g

Bu komut aracı şema yapılandırmanızı görüntüler. Aşağıdaki değerleri ayarlayın:

Değer Description
agentBlueprintId Aracınızın istemci kimliği
agentBlueprintClientSecret Temsilcinizin gizli anahtarı
tenantId Microsoft Entra ID kiracı kimliğiniz.

Aracınızda aracı kimlik doğrulamasını yapılandırmak için şu değerleri kullanın:

Aşağıdaki ayarları dosyanıza .env ekleyin ve yer tutucu değerlerini gerçek kimlik bilgilerinizle değiştirin:

USE_AGENTIC_AUTH=true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID=<agentBlueprintId>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET=<agentBlueprintClientSecret>
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID=<your-tenant-id>
Değişken Description Zorunlu Örnek
USE_AGENTIC_AUTH Aracılı kimlik doğrulama modunu etkinleştirme Evet true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Aracı şema istemci kimliği a365 config display -g Evet 12345678-1234-1234-1234-123456789abc
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Aracı şema istemci gizli dizisi a365 config display -g Evet abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra kiracı kimliği a365 config display -g Evet adfa4542-3e1e-46f5-9c70-3df0b15b3f6c

Not

.NET için, içinde ayarlandığından launchSettings.json da emin olun USE_AGENTIC_AUTH=true (bkz. 4. Adım: Ortam değişkenleri başvurusu)

Adım 2: Ortam değişkenleri

Aşağıdaki gerekli ortam değişkenlerini yapılandırarak ortam kurulumunuzu tamamlayın:

Kimlik doğrulama değişkenleri

Aracılı kimlik doğrulamasının düzgün çalışması için gereken kimlik doğrulama işleyicisi ayarlarını yapılandırın.

Dosyanıza .env ekleyin:

# Agentic Authentication Settings
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE=AgenticUserAuthorization
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES=https://graph.microsoft.com/.default
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME=service_connection

# Connection Mapping
CONNECTIONSMAP_0_SERVICEURL=*
CONNECTIONSMAP_0_CONNECTION=SERVICE_CONNECTION
Değişken Description Zorunlu
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__TYPE Kimlik doğrulama işleyici türü Evet
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__SCOPES Microsoft Graph için kimlik doğrulama kapsamları Evet
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALTERNATEBLUEPRINTCONNECTIONNAME Alternatif şema bağlantı adı Evet
CONNECTIONSMAP_0_SERVICEURL Bağlantı eşlemesi için hizmet URL'si deseni Evet
CONNECTIONSMAP_0_CONNECTION Eşleme için bağlantı adı Evet

Uç nokta yapılandırmasını doğrulama

Aracınızın hangi Aracı 365 platform uç noktasına bağlanması gerektiğini belirtmek için MCP (Model Bağlam Protokolü) uç noktası yapılandırması gereklidir. Aracınız için araç sunucularını tanımlayan araç bildirimini oluştururken, MCP platform uç noktasını belirtmeniz gerekir. Bu uç nokta, MCP araç sunucularının Microsoft 365 tümleştirme özellikleri için hangi ortama (ön üretim, test veya üretim) bağlandığını belirler.

Dosyanıza .env ekleyin:

# MCP Server Configuration
MCP_PLATFORM_ENDPOINT=<MCP endpoint>
Değişken Description Zorunlu Varsayılan Örnek
MCP_PLATFORM_ENDPOINT MCP platform uç noktası URL'si (ön üretim, test veya üretim) Hayır Üretim uç noktası

Önemli: Belirtilmezse MCP_PLATFORM_ENDPOINT , varsayılan olarak üretim uç noktası olur.

Gözlemlenebilirlik değişkenleri

Aracınız için günlüğe kaydetmeyi ve dağıtılmış izlemeyi etkinleştirmek için bu gerekli değişkenleri yapılandırın. Gözlemlenebilirlik özellikleri ve en iyi yöntemler hakkında daha fazla bilgi edinin

Not

Gözlemlenebilirlik yapılandırması tüm dillerde aynıdır.

Değişken Description Varsayılan Örnek
ENABLE_A365_OBSERVABILITY Gözlemlenebilirliği etkinleştirme/devre dışı bırakma false true
ENABLE_A365_OBSERVABILITY_EXPORTER İzlemeleri gözlemlenebilirlik hizmetine aktarma false true
OBSERVABILITY_SERVICE_NAME İzleme için hizmet adı Temsilci adı my-agent-service
OBSERVABILITY_SERVICE_NAMESPACE Service Bus Ad Alanı agent365-samples my-company-agents

Aracı uygulama sunucusu yapılandırması

Aracı uygulama sunucunuzun çalıştığı bağlantı noktasını yapılandırın. Bu isteğe bağlıdır ve Python ve JavaScript aracıları için geçerlidir.

Dosyanıza .env ekleyin:

# Server Configuration
PORT=3978
Değişken Description Zorunlu Varsayılan Örnek
PORT Aracı sunucusunun çalıştığı bağlantı noktası numarası Hayır 3978 3978

Bağımlılıkları yükleme ve aracı uygulama sunucusunu başlatma

Ortamınız yapılandırıldıktan sonra gerekli bağımlılıkları yüklemeniz ve test için aracı uygulama sunucunuzu yerel olarak başlatmanız gerekir.

Bağımlılıkları yükleyin:

uv pip install -e .

Bu komut içinde pyproject.toml tanımlanan paket bağımlılıklarını okur ve PyPI'dan yükler. Sıfırdan bir aracı uygulaması oluştururken bağımlılıklarınızı tanımlamak için bir pyproject.toml dosya oluşturmanız gerekir. Örnek deposundaki örnek aracılarda bu paketler zaten tanımlanmıştır. Satırları gerektiği şekilde güncelleştirebilir, ekleyebilir veya silebilirsiniz.

Aracı uygulama sunucusunu başlatma

python <main.py>

değerini <main.py> aracı uygulamanızın giriş noktasını içeren ana Python dosyanızın adıyla değiştirin (örneğin, start_with_generic_host.py, app.pyveya main.py).

Veya uv kullanarak:

uv run python <main.py>

Aracı sunucunuz artık çalışıyor olmalı ve Agents Playground veya Microsoft 365 uygulamalarından istek almaya hazır olmalıdır.

Agents Playground'da test aracısı

Agents Playground, tam kiracı kurulumu gerektirmeden Microsoft 365 ortamının benzetimini yapabilen yerel bir test aracıdır. Bu, aracınızın mantığını ve araç çağrılarını doğrulamanın en hızlı yoludur. Daha fazla bilgi için bkz . Agents Playground ile test.

Yeni bir terminal açın (Windows'ta PowerShell) ve Agents Playground'ı başlatın:

agentsplayground

Bu, Agents Playground arabirimine sahip bir web tarayıcısı açar. Araç, aracınıza ileti gönderebileceğiniz bir sohbet arabirimi görüntüler.

Temel Testler

Aracınızın düzgün yapılandırıldığını doğrulayarak başlayın. Aracıya bir ileti gönderin:

What can you do?

Aracının, aracınızın sistem istemine ve özelliklerine göre yapılandırıldığı yönergelerle yanıt vermesi gerekir. Bu, şunu onaylar:

  • Aracınız doğru çalışıyor
  • Aracı iletileri işleyebilir ve yanıtlayabilir
  • Agents Playground ile temsilciniz arasındaki iletişim çalışıyor

Test aracı çağrıları

'da toolingManifest.json MCP araç sunucularınızı yapılandırdıktan sonra (bkz . Kurulum yönergeleri için araçlar ), aşağıdaki örneklerle test aracı çağrıları:

İlk olarak, hangi araçların kullanılabilir olduğunu doğrulayın:

List all tools I have access to

Ardından belirli araç çağrılarını test edin:

Posta araçları

Send email to your-email@example.com with subject "Test" and message "Hello from my agent"

Beklenen yanıt: Aracı, Posta MCP sunucusunu kullanarak bir e-posta gönderir ve iletinin gönderildiğini onaylar.

Takvim araçları

List my calendar events for today

Beklenen yanıt: Aracı geçerli güne ilişkin takvim olaylarınızı alır ve görüntüler.

SharePoint araçları

List all SharePoint sites I have access to

Beklenen yanıt: Aracı SharePoint'i sorgular ve erişiminiz olan sitelerin listesini döndürür.

Araç çağrılarını şu şekilde görüntüleyebilirsiniz:

  • Sohbet penceresi - aracının yanıtını ve tüm araç çağrılarını görün
  • Günlük paneli - Araç parametreleri ve yanıtlar dahil ayrıntılı etkinlik bilgilerine bakın

Bildirim etkinlikleriyle test edin

Yerel geliştirme sırasında, Agents Playground'da özel etkinliklerin benzetimini yaparak bildirim senaryolarını test edebilirsiniz. Bu, aracınızı üretime dağıtmadan önce bildirim işlemesini doğrulamanızı sağlar.

Bildirim etkinliklerini test etmeden önce şunların olduğundan emin olun:

Bildirimlerin düzgün çalışması için hem uygun araç yapılandırması hem de bildirim kurulumu gerekir. Özel etkinlik özelliğini kullanarak e-posta bildirimleri veya Word açıklamaları gibi senaryoları test edebilirsiniz.

Özel etkinlikler göndermek için:

  1. Temsilcinizi ve Agents Playground'ı başlatın
  2. Agents Playground'da, Bir Etkinlik>Özel etkinliğiyle alay etme bölümüne gidin
  3. etkinliğinden öğesini conversationId kopyalayın (Agents Playground her yeniden başlatıldığında konuşma kimliği değişir)
  4. Özel etkinlik JSON'unuzu yapıştırın ve alanı kopyaladığınız konuşma kimliğiyle güncelleştirin personal-chat-id . E-posta bildirimi örneğine bakın
  5. Aktivite ekle'yi seçin.
  6. Hem sohbet konuşmasında hem de günlük panelinde sonucu görüntüleme

E-posta ile bildirim

Bu, aracıya gönderilen bir e-postanın simülasyonunu oluşturur. Yer tutucu değerlerini gerçek aracı ayrıntılarınızla değiştirin:

{
  "type": "message",
  "id": "aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb",
  "timestamp": "2025-09-24T17:40:19+00:00",
  "serviceUrl": "http://localhost:56150/_connector",
  "channelId": "agents",
  "name": "emailNotification",
  "from": {
    "id": "manager@contoso.com",
    "name": "Agent Manager",
    "role": "user"
  },
  "recipient": {
    "id": "agent@contoso.com",
    "name": "Agent",
    "agenticUserId": "<your-agentic-user-id>",
    "agenticAppId": "<your-agent-app-id>",
    "tenantId": "<your-tenant-id>"
  },
  "conversation": {
    "conversationType": "personal",
    "tenantId": "aaaabbbb-0000-cccc-1111-dddd2222eeee",
    "id": "personal-chat-id"
  },
  "membersAdded": [],
  "membersRemoved": [],
  "reactionsAdded": [],
  "reactionsRemoved": [],
  "locale": "en-US",
  "attachments": [],
  "entities": [
    {
      "id": "email",
      "type": "productInfo"
    },
    {
      "type": "clientInfo",
      "locale": "en-US",
      "timezone": null
    },
    {
      "type": "emailNotification",
      "id": "bbbbbbbb-1111-2222-3333-cccccccccccc",
      "conversationId": "personal-chat-id",
      "htmlBody": "<body dir=\"ltr\">\n<div class=\"elementToProof\" style=\"font-family: Aptos, Aptos_EmbeddedFont, Aptos_MSFontService, Calibri, Helvetica, sans-serif; font-size: 12pt; color: rgb(0, 0, 0);\">\nYour email message content here</div>\n\n\n</body>"
    }
  ],
  "channelData": {
    "tenant": {
      "id": "aaaabbbb-0000-cccc-1111-dddd2222eeee"
    }
  },
  "listenFor": [],
  "textHighlights": []
}

Gözlemlenebilirlik günlüklerini görüntüleme

Yerel geliştirme sırasında gözlemlenebilirlik günlüklerini görüntülemek için, aracınızı gözlemlenebilirlik koduyla izleyin (bkz . Kod örnekleri için gözlemlenebilirlik ) ve Gözlemlenebilirlik değişkenleri bölümünde açıklandığı gibi ortam değişkenlerini yapılandırın. Yapılandırıldıktan sonra konsolda aşağıdakilerin gösterildiği gerçek zamanlı izlemeler görünür:

  • Aracı çağırma izlemeleri
  • Yürütme ayrıntıları
  • LLM çıkarım çağrıları
  • Giriş ve çıkış iletileri
  • Belirteç kullanımı
  • Yanıt süresi
  • Hata bilgileri

Bu günlükler sorunlarda hata ayıklamanıza, aracı davranışını anlamanıza ve performansı iyileştirmenize yardımcı olur.

Sorun giderme

Bu bölümde, aracınızı yerel olarak test ederken karşılaşabileceğiniz yaygın sorunların çözümleri sağlanır.

Bağlantı ve ortam sorunları

Bu sorunlar, aracınızın düzgün iletişim kurmasını engelleyebilecek ağ bağlantısı, bağlantı noktası çakışmaları ve ortam kurulum sorunlarıyla ilgilidir.

Agents Playground bağlantı sorunları

Belirti: Agents Playground aracınıza bağlanamıyor

Çözüm

  • Aracı sunucunuzun çalıştığını doğrulayın
  • Bağlantı noktası numaralarının aracınızla Agents Playground arasında eşleştiğinden emin olun
  • Blob kapsayıcısına erişimi engelleyen güvenlik duvarı kuralı olmadığından emin olun.
  • Aracıyı ve Agents Playground'ı yeniden başlatmayı deneyin

Eski Agents Playground sürümü

Belirti: Agents Playground'da beklenmeyen hatalar veya eksik özellikler

Çözüm: Agents Playground'ı kaldırın ve yeniden yükleyin:

winget uninstall agentsplayground
winget install agentsplayground

Bağlantı noktası çakışmaları

Belirti: Bağlantı noktasının zaten kullanımda olduğunu belirten hata

Çözüm

  • Aracınızın diğer örneklerini durdurma
  • Yapılandırmanızdaki bağlantı noktasını değiştirme
  • Bağlantı noktasını kullanarak tüm işlemleri sonlandırma:
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServer eklenemez

Belirti: VS Code'da DeveloperMCPServer eklemeye çalışırken hata oluştu

Çözüm: Visual Studio Code'ı kapatıp yeniden açın, ardından sunucuyu yeniden eklemeyi deneyin.

Kimlik doğrulaması sorunları

Bu sorunlar, aracınız Microsoft 365 hizmetlerinde düzgün kimlik doğrulaması gerçekleştiremiyorsa veya kimlik bilgilerinin süresi dolduğunda veya yanlış yapılandırıldığında oluşur.

Taşıyıcı belirtecinin süresi doldu

Belirti: Kimlik doğrulama hataları veya 401 Yetkisiz yanıtlar

Çözüm: Taşıyıcı belirteçlerinin süresi yaklaşık 1 saat sonra dolar. Yeni bir belirteç alın ve yapılandırmanızı güncelleştirin.

Python'da aracı kimlik doğrulaması hataları

Belirti: Aracı örnek belirteci alma hatası

Çözüm: içindeki .envayarını doğrulayınALT_BLUEPRINT_NAME:

# Change from:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

# To:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

Bilinen sorunlar ve bildirimler

Bu sorunlar araç çağrıları, MCP sunucu etkileşimleri ve bildirim teslimi ile ilgili sorunları içerir.

Alınmayan e-postalar

Belirti: Aracı, e-postanın gönderildiğini belirtir, ancak bunu almazsınız

Çözüm

  • E-postanın istenmeyen posta klasörünüzde olup olmadığına bakın.
  • E-posta teslimi birkaç dakika gecikebilir - 5 dakikaya kadar bekleyin
  • E-posta adresinin doğru olduğunu onaylayın.
  • E-posta gönderme sırasında hata olup olmadığını denetlemek için aracı günlüklerini denetleyin

Word açıklama yanıtları çalışmıyor

Bilinen sorun: Bildirim hizmeti şu anda word açıklamalarına doğrudan yanıt veremiyor. Bu işlev geliştiriliyor.

Yardım alma

Bu sorun giderme bölümünde ele alınmayan sorunlarla karşılaşırsanız şu kaynakları inceleyin:

Microsoft Agent 365 SDK depoları

Daha fazla destek

Sonraki adımlar

Aracınızı yerel olarak başarıyla test ettiğinize göre, aracınızı Azure'a dağıtmaya ve Microsoft 365'te yayımlamaya hazırsınız:

  • Aracıları dağıtma ve yayımlama: Aracınızı Azure Web App'e dağıtmayı ve Microsoft Yönetim Merkezi'nde yayımlayarak kuruluşunuzun Microsoft 365'te bulmasını ve kiralamasını sağlamayı öğrenin.
  • Last updated on