Microsoft Agent 365 SDK ile aracıları test etme

Yayınlamadan önce, aracınızı Agents Playground kullanarak yerel olarak test edin. Bu rehber, geliştirme ortamınızın kurulumu, kimlik doğrulama yapılandırması ve aracınızın işlevselliğinin Agents Playground test aracı kullanılarak doğrulanmasını kapsar.

Aracınız yerel olarak çalışmaya başladıktan sonra, Teams, Word ve Outlook gibi Microsoft 365 uygulamalarında test etmek için Agent 365 Geliştirme Yaşam Döngüsü'nü izleyin.

Ön koşullar

Aracınızı test etmeye başlamadan önce aşağıdaki ön koşulların yüklü olduğundan emin olun:

Genel ön koşullar

Programlama dili ön koşulları

Aracı test ortamını yapılandırın

Bu bölümde ortam değişkenlerinin nasıl ayarlanacağı, geliştirme ortamınızın kimlik doğrulamasının nasıl yapılacağı ve Agent 365 tabanlı aracınızın test için nasıl hazırlanacağı açıklanmaktadır.

Aracı test ortamınızı aşağıdaki adımları sırasıyla izleyerek kurun:

  1. Ortamınızı yapılandırın - Ortam yapılandırma dosyanızı oluşturun veya güncelleyin.

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

  3. Kimlik doğrulamasını yapılandırın - Aracıik kimlik doğrulamayı kurun.

  4. Ortam değişkenleri referansı - 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, Agents Playground'da aracınızı test etmeye hazırsınız.

1. Adım: Ortamınızı yapılandırma

Yapılandırma dosyanızı oluşturun:

cp .env.template .env

Not

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

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

Yerel test için OpenAI veya Azure OpenAI ayarlarını yapılandırın. Ön koşullarda belirtilen API anahtarlarınızı, hizmet uç noktalarınızı ve model parametrelerini yapılandırma dosyanıza ekleyin.

.env dosyanıza 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 Açıklama Gerekli Ö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 a1b2c3d4e5f6...
AZURE_OPENAI_ENDPOINT Azure OpenAI hizmet uç noktası URL'si Azure OpenAI için https://your-resource.openai.azure.com/
AZURE_OPENAI_DEPLOYMENT Azure OpenAI'deki dağıtım adı Azure OpenAI için gpt-4
AZURE_OPENAI_API_VERSION Azure OpenAI için API sürümü Azure OpenAI için 2024-02-15-preview

Adım 3: Aracınız için kimlik doğrulamasını yapılandırın

Aracınız için aşağıdaki kimlik doğrulama yöntemlerinden birini seçin:

Aracısal kimlik doğrulaması

Çalışma dizininizdeki a365.generated.config.json dosyasını açarak aracı blueprint kimlik bilgilerinizi alın. Aşağıdaki değerleri kopyalayın:

Value Açıklama
agentBlueprintId Aracınızın istemci kimliği
agentBlueprintClientSecret Aracınızın istemci gizli anahtarı
tenantId Microsoft Entra kiracısı kimliğiniz

Aracınızda agentik kimlik doğrulamayı yapılandırmak için bu değerleri kullanın:

Aşağıdaki ayarları, yer tutucu değerleri kendi kimlik bilgilerinizle değiştirerek .env dosyanıza ekleyin:

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 Açıklama Gerekli Örnek
USE_AGENTIC_AUTH Aracısal kimlik doğrulama modunu etkinleştir Evet true
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTID Aracı blueprint istemci kimliği a365.generated.config.json'den Evet 11112222-bbbb-3333-cccc-4444dddd5555
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__CLIENTSECRET Aracı blueprint gizli anahtar a365.generated.config.json'den Evet abc~123...
CONNECTIONS__SERVICE_CONNECTION__SETTINGS__TENANTID Microsoft Entra kiracısı kimliğiniz a365.generated.config.json'den Evet 22223333-cccc-4444-dddd-5555eeee6666

OBO kimlik doğrulaması

On-Behalf-Of (OBO) kimlik doğrulamasını kullanarak, aracınız bir aracı kullanıcı kimliğine ihtiyaç duymadan delege edilmiş kullanıcı izinleriyle MCP sunucu araçlarına erişebilir. Bu akışta, aracı kullanıcının delege edilmiş belirteçını alır ve bunu, kullanıcı adına işlemler yapmak üzere değiştirir.

OBO doğrulama, aşağıdaki koşulların geçerli olduğu üretim senaryoları için uygundur:

  • Aracınızın bir temsilci kullanıcı kimliği yoktur.
  • Kullanıcıya özgü izinlere sahip kaynaklara erişilmesi gerekir.
  • Aracının kimlik doğrulaması yapılmış kullanıcı adına işlem gerçekleştirmesi gerekmektedir.

OBO akışının nasıl çalıştığıyla ilgili detaylar için Kimlik doğrulama akışları bölümüne bakın. Tam bir uygulama örneği için, OBO yetkilendirme örneğini Microsoft 365 Aracıları SDK'sı'nda inceleyiniz.

Taşıyıcı belirteç kimlik doğrulaması

Üretim ortamı kimlik doğrulaması yapılandırılmamışsa, aracınızı test etmek için bearer belirteç ile kimlik doğrulama kullanın. Bu yöntem, devredilmiş erişim belirteçı almak için etkileşimli tarayıcı kimlik doğrulamasını kullanır. Bu belirteç sayesinde, aracınız MCP Server araçlarını kullanıcı izinlerinizle çağırabilir. Bu yaklaşım, bir aracı kullanıcısının üretimde kaynaklara nasıl eriştiğini, gerçek bir aracı örneği gerektirmeden simüle eder.

Gerekli MCP sunucu izinlerini uygulamanıza eklemek için öncelikle a365 develop add-permissions'i kullanın:

a365 develop add-permissions

Ardından, a365 develop get-token kullanarak taşıyıcı belirteçları alın ve yapılandırın:

a365 develop get-token

get-token komutu otomatik olarak:

  • Tüm yapılandırılmış MCP sunucularını keşfetmek için ToolingManifest.json dosyasını okur.
  • Her hedef için bir belirteç edinir – sunucuya özel MCP sunucuları, kendi uygulama ID’lerine yönelik bir belirteç alır; paylaşılan ATG sunucuları ise paylaşılan Agent Tools Gateway uygulama ID’sine (ea9ffc3e-8a23-4a7d-836d-234d7c7565c1) yönelik bir belirteç alır.
  • Token'ları proje yapılandırma dosyalarınıza yazar:
    • Her sunucu için belirteç: BEARER_TOKEN_<SERVER_NAME> (örneğin, BEARER_TOKEN_MCP_MAILTOOLS)
    • Paylaşılan ATG belirteç: BEARER_TOKEN

get-token'i çalıştırmadan önce, proje yapılandırma dosyanıza yer tutucu girişler ekleyin:

  • .NET: Properties/launchSettings.json içindeki her profilde environmentVariables'e "BEARER_TOKEN": "" ve/veya "BEARER_TOKEN_<SERVER_NAME>": "" ekleyin. Komut yalnızca bu anahtarların zaten tanımlı olduğu profilleri günceller.
  • Python/Node.js: .env dosyasını, BEARER_TOKEN= ve/veya BEARER_TOKEN_<SERVER_NAME>= içerecek şekilde çalıştırmadan önce oluşturun. Dosya eksikse, komut kaydetmeyi atlar ve yönerge gösterir.

Not

Eğer a365 develop get-token --app-id <id>'i a365.config.json dosyası olmadan çalıştırırsanız, belirteçler otomatik olarak kaydedilmez. Bunları Properties/launchSettings.json dosyanıza (.NET için) veya .env dosyanıza (Python/Node.js için) manuel olarak kopyalayıp yapıştırın.

Taşıyıcı belirteçleri yaklaşık bir saat sonra geçerliliğini yitirir. Süresi dolmuş belirteçları yenilemek için a365 develop get-token kullanın.

Adım 4: Ortam değişkenlerine referans

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

Kimlik doğrulama değişkenleri

Aracısal kimlik doğrulamanın doğru çalışması için gereken kimlik doğrulama işleyici ayarlarını yapılandırın.

.env dosyanıza 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 Açıklama Gerekli
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 blueprint bağlantı adı Evet
CONNECTIONSMAP_0_SERVICEURL Bağlantı eşleştirme için servis URL deseni Evet
CONNECTIONSMAP_0_CONNECTION Eşleştirme için bağlantı adı Evet

Taşıyıcı belirteç değişkenleri (sadece yerel geliştirme)

Değişken Açıklama Gerekli
BEARER_TOKEN Paylaşılan ATG MCP sunucuları için taşıyıcı belirteç. a365 develop get-token komutu bu belirteçi otomatik olarak yazar. Paylaşılan ATG yerel dev için
BEARER_TOKEN_<SERVER_NAME> Sunucu başına taşıyıcı belirteç. SDK, ismi ToolingManifest.json'den mcpServerName'i büyük harfe çevirerek türetir (örneğin, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS). a365 develop get-token komutu bu belirteçi otomatik olarak yazar. Sunucuya özel yerel geliştirme için
SKIP_TOOLING_ON_ERRORS MCP araçları yüklenemezse çıplak LLM'e geri dönmek için true olarak ayarlayın. Yalnızca ASPNETCORE_ENVIRONMENT veya ENVIRONMENTDevelopment olduğunda geçerlidir. Hayır

Önemli

Taşıyıcı belirteç yalnızca yerel geliştirme için kullanılır. BEARER_TOKEN veya BEARER_TOKEN_<SERVER_NAME>'yi üretim dağıtımlarında asla ayarlamayın.

MCP uç nokta yapılandırması

Aracınızın bağlanacağı Agent 365 platform uç noktasını belirtin. Aracınız için araç sunucularını tanımlayan araç manifestosunu oluşturduğunuzda, MCP platformunun uç noktasını belirtin. Bu uç nokta, MCP araç sunucularının Microsoft 365 entegrasyon yetenekleri için bağlanacağı ortamı (preprod, test veya üretim) belirler.

.env dosyanıza ekleyin:

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

Dikkat: Eğer MCP_PLATFORM_ENDPOINT belirtmezseniz, uygulama üretim uç noktasını kullanır.

Not

Eğer CLI üzerinden mock tooling sunucusunu kullanıyorsanız, uç noktayı http://localhost:<port> kullandığınız port numarasıyla ayarlayın. Varsayılan bağlantı noktası 5309'dür.

Gözlemlenebilirlik değişkenleri

Aracınız için kayıt tutma ve dağıtılmış izlemeyi etkinleştirmek amacıyla bu gerekli değişkenleri yapılandırın. Ortam değişkenleri, yapılandırma seçenekleri ve kod örneklerinin tam listesi için Aracı gözlemlenebilirliği bölümüne göz atın.

Not

Gözlemlenebilirlik yapılandırması tüm dillerde aynıdır. Diğer ayrıntılar için Yapılandırma'ya bakın.

Değişken Açıklama Varsayılan Örnek
ENABLE_A365_OBSERVABILITY_EXPORTER İzleri gözlemlenebilirlik hizmetine dışa aktarın. false seçeneği kullanıldığında, span'leri bunun yerine konsola aktarın. false true
A365_OBSERVABILITY_LOG_LEVEL Gözlemlenebilirlik SDK'sı için dahili log seviyesi Test sırasında dışa aktarma sorunlarının hata ayıklanmasında faydalı. none info, warn, error, debug

Aracı uygulama sunucusu yapılandırması

Aracı uygulama sunucunuzun çalıştığı portu yapılandırın. Bu ayar isteğe bağlıdır ve Python ve JavaScript aracılarına uygulanır.

.env dosyanıza ekleyin:

# Server Configuration
PORT=3978
Değişken Açıklama Zorunlu Varsayılan Örnek
PORT Aracı sunucusunun çalıştığı port numarası Hayır 3978 3978

Bağımlılıkları yükleyin ve aracı uygulama sunucusunu başlatın

Ortamınızı yapılandırdıktan sonra, gerekli bağımlılıkları yükleyin ve aracı uygulama sunucunuzu yerelde test için başlatın.

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

uv pip install -e .

Bu komut, pyproject.toml dosyasında tanımlanan paket bağımlılıklarını okur ve bunları PyPI üzerinden yükler. Bir aracı uygulamasını sıfırdan oluştururken, bağımlılıklarınızı tanımlamak için bir pyproject.toml dosyası oluşturun. örnekleri deposundaki örnek aracılar bu paketleri zaten tanımlamıştır. İhtiyaç duydukça bunları ekleyebilir veya güncelleyebilirsiniz.

Aracı uygulama sunucusunu başlatın

python <main.py>

<main.py> öğesini, 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.py veya main.py).

Alternatif olarak uv kullanın:

uv run python <main.py>

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

Aracıyı Agents Playground'da test edin

Agents Playground, tam bir kiracı kurulumu gerektirmeden Microsoft 365 ortamını simüle eden bir yerel test aracıdır. 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. Test with Agents Playground.

Agents Playground'u aracı tabanlı kimlik doğrulama için yapılandırın

Not

Bu yapılandırma yalnızca aracı tabanlı kimlik doğrulama kullanılırken gereklidir. Taşıyıcı belirteç kimlik doğrulaması kullanıyorsanız, bu bölümü atlayıp doğrudan Temel test bölümüne geçebilirsiniz.

Aracısal kimlik doğrulamasını kullandığınızda, Agents Playground YAML dosyasını aracınızın bilgileriyle yapılandırın:

  1. Yapılandırma dosyasını ayarlayın: Agents Playground'u çalıştırdığınız klasörde .m365agentsplayground.yml dosyasını oluşturun veya güncelleyin. Detaylı kurulum talimatları için Teams bağlamını özelleştir bölümüne bakınız.

  2. Bot yapılandırmasını güncelleyin: .m365agentsplayground.yml dosyanıza aşağıdaki bot bilgilerini ekleyin ve yer tutucu değerleri kendi aracı kimlik bilgilerinizle değiştirin:

    bot:
  id: <your-agent-email>@<your-tenant>.onmicrosoft.com
  name: <Your Agent Name>
  role: agenticUser
  agenticUserId: <your-agentic-user-id>
  agenticAppId: <your-agentic-app-id>
    Özellik Açıklama Gerekli
    id Aracı kullanıcınızın e-posta adresi aşağıdaki formatta olmalıdır: agentusername@tenant.onmicrosoft.com Evet
    name Aracı kullanıcınız için gösterim adı Evet
    role Aracı kimlik doğrulaması için agenticUser olarak ayarlanmalıdır Evet
    agenticUserId Aracı kullanıcının Nesne Kimliği. Bu değeri Microsoft Entra yönetim merkezinde, aracı kullanıcının profil sayfasında bulabilirsiniz. Evet
    agenticAppId Temsilci kullanıcısının Temsilci Kimliği. Bu değeri Microsoft Entra yönetim merkezinde, aracı kullanıcının profil sayfasında bulabilirsiniz. Evet

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

agentsplayground

Bu komut, Agents Playground arayüzünü bir web tarayıcısında açar. Araç, aracınıza mesaj gönderebileceğiniz bir sohbet arayüzü gösterir.

Temel test

Öncelikle aracınızın doğru şekilde yapılandırıldığını doğrulayın. Aracınıza mesaj gönderin:

What can you do?

Aracı, aracınızın sistem istem'i ve yeteneklerine göre yapılandırılmış talimatlarla yanıt verir. Bu yanıt aşağıdakileri doğrular:

  • Aracınız sorunsuz çalışıyor.
  • Aracı mesajları işleyebilir ve yanıt verebilir.
  • Agent Playground ile aracınız arasındaki iletişim çalışıyor.

Araç çağrısı testleri

MCP araç sunucularınızı toolingManifest.json yapılandırdıktan sonra (kurulum talimatları için Araçlar bölümüne göz atın), aşağıdaki örnekleri kullanarak araç çağrılarını test edin:

Öncelikle hangi araçların mevcut olduğunu doğrulayın.

List all tools I have access to

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

E-posta araçları

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

Beklenen yanıt: Aracı, Mail MCP sunucusunu kullanarak bir e-posta gönderir ve mesajın gönderildiğini doğrular.

Takvim araçları

List my calendar events for today

Beklenen yanıt: Aracı, bugünkü takvim etkinliklerinizi alır ve gösterir.

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 bölümlerde görebilirsiniz:

  • Sohbet penceresi - aracı yanıtını ve araç çağrılarını görün.
  • Log paneli - araç parametreleri ve yanıtlar dahil olmak üzere ayrıntılı etkinlik bilgilerini görüntüleyin.

Bildirim aktiviteleriyle test

Yerel geliştirme sırasında, Agents Playground'daki yerleşik bildirim tetikleyicilerini kullanarak bildirim senaryolarını test edin.

Mock an Activity menüsünün açıldığı Agents Playground arayüzünü gösteren ekran görüntüsü; Send email ve Mention in Word gibi Trigger Notification Activity seçeneklerini gösteriyor.

Bildirim aktivitelerini test etmeden önce, aşağıdakileri mutlaka yapın:

E-posta bildirimleri test etme

E-posta bildirimlerinin işlenmesini test etmek:

  1. Aracınızı ve Agents Playground başlatın.
  2. Agents Playground'da, Mock an Activity>Trigger Notification Activity sayfasına gidin.
  3. E-posta gönder'i seçin.
  4. Payload penceresinde, gönderenin adı ve e-posta gövdesi içeriği gibi sahte e-posta ayrıntılarını ihtiyaca göre güncelleyin.
  5. Etkinliği gönder seçeneğini seçin.
  6. Sonucu hem sohbet konuşmasında hem de log panelinde görüntüleyin.

Aracı, simüle edilmiş bir e-posta bildirimi alır ve bunu bildirim işleme mantığınıza göre işler. E-posta bildirimi yükü yapısı hakkında detaylar için E-posta bildirimi yükü bölümüne bakınız.

Test Kelimesi bahsi bildirimleri

Word belge bahsi bildirimlerini test etmek için:

  1. Aracınızı ve Agents Playground başlatın.
  2. Agents Playground'da, Mock an Activity>Trigger Notification Activity sayfasına gidin.
  3. Word'de Bahset seçeneğini seçin.
  4. Payload penceresinde, belge kimliği ve yorum metni gibi örnek yorum ayrıntılarını gerektiği şekilde güncelleyin.
  5. Etkinliği gönder seçeneğini seçin.
  6. Sonucu hem sohbet konuşmasında hem de log panelinde görüntüleyin.

Aracı, simüle edilmiş bir Word bahsetme bildirimi alır ve sizin bildirim işleme mantığınıza göre yanıt verir. Word yorum bildirimi yükü yapısı hakkında detaylar için Belge yorum bildirimi yükü kısmına bakınız.

Aracı kurulum ve kaldırma olaylarını test edin

Agents Playground, aracınıza bağlandığında, otomatik olarak InstallationUpdate etkinliğini add eylemiyle gönderir. Kurulum işleyicisi uygularsanız, bağlantı kurulduktan hemen sonra aracınızın hoş geldin mesajı sohbette görünür.

Kurulum etkinliği işlemesini doğrulamak için:

  1. Aracı sunucunuzu başlatın.
  2. Agents Playground'u açın. Agents Playground, aracınıza bağlanır ve kurulum etkinliğini otomatik olarak tetikler.
  3. Karşılama mesajının konuşmada göründüğünü doğrulayın.

Kurulum olayı otomatik olarak tetiklendikten sonra, aracınızın karşılama mesajı 'Beni işe aldığınız için teşekkürler! Profesyonel yolculuğunuzda size yardımcı olmayı dört gözle bekliyorum!' konuşma penceresinde ve günlük panelinde görüntülenmiş şekilde Agents Playground arayüzünü gösteren ekran görüntüsü.

İşleyicinin uygulanmasıyla ilgili ayrıntılar için, Aracı kurulum ve kaldırma olaylarını yönet bölümüne bakın.

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

Yerel geliştirme sırasında gözlemlenebilirlik kayıtlarını görüntülemek için, aracınıza gözlemlenebilirlik kodunu ekleyin (kod örnekleri için Observability bölümüne bakınız) ve ortam değişkenlerini Observability variables bölümünde açıklandığı şekilde yapılandırın. Adım adım doğrulama talimatları ve beklenen log çıktısı için Yerel doğrulama. bölümüne bakınız. Yapılandırma tamamlandığında, konsolda gerçek zamanlı izler görünür ve şunları gösterir:

  • Aracı çağrısı izleri
  • Araç yürütme ayrıntıları
  • LLM çıkarım çağrıları
  • Giriş ve çıkış mesajları
  • Belirteç kullanımı
  • Yanıt süreleri
  • Hata bilgisi

Bu günlükler, sorunları hata ayıklamanıza, aracı davranışını anlamanıza ve performansı optimize etmenize yardımcı olur. Yayınlamadan önce, tüm gerekli özniteliklerin mevcut olduğundan emin olmak için Mağaza yayınlama için doğrulama aracı'nı kullanın.

Sonraki adımlar

Aracınızı yerel olarak test ettikten sonra, Azure'a dağıtın ve Microsoft 365'e yayınlayın.

Aracınızı Teams, Word ve Outlook gibi Microsoft 365 uygulamalarında test etmek için Agent 365 Geliştirme Yaşam Döngüsü bölümüne bakınız.

Sorun giderme

Bu bölüm, aracınızı yerel olarak test ederken karşılaşabileceğiniz yaygın sorunlara çözümler sunar.

İpucu

Agent 365 Sorun Giderme Kılavuzu, Agent 365 geliştirme yaşam döngüsünün her bir bölümü için yüksek düzeyde sorun giderme önerileri, en iyi uygulamalar ve ilgili sorun giderme içeriklerine bağlantılar içerir.

Bağlantı ve ortam sorunları

Bu sorunlar, ağ bağlantısı, port çakışmaları ve aracınızın düzgün iletişim kurmasını engelleyen ortam yapılandırma sorunlarıyla ilgilidir.

Agents Playground bağlantı sorunları

Sorun: Agents Playground, aracınıza bağlanamıyor.

Çözümler:

  • Aracı sunucunuzun çalıştığını doğrulayın.
  • Aracınız ile Agents Playground arasındaki port numaralarının aynı olduğundan emin olun.
  • Yerel bağlantıları engelleyen güvenlik duvarı kuralları olmadığını kontrol edin.
  • Hem aracıyı hem de Agents Playground'u yeniden başlatmayı deneyin.

Agents Playground'un eski sürümü

Belirti: Agents Playground'da beklenmedik hatalar veya eksik özellikler.

Çözüm: Agent Playground'u kaldırın ve yeniden kurun.

winget uninstall agentsplayground
winget install agentsplayground

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

Belirti: Portun zaten kullanıldığını gösteren hata.

Çözüm:

  • Aracınızın başka örneklerini durdurun.
  • Yapılandırmanızda portu değiştirin.
  • Portu kullanan işlemleri sonlandırın.
# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort <port>).OwningProcess | Stop-Process

DeveloperMCPServer eklenemiyor

Belirti: Visual Studio Code'da DeveloperMCPServer eklemeye çalışırken hata.

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

Kimlik doğrulaması ve belirteç sorunları

Bu sorunlar, aracınız Microsoft 365 hizmetleriyle düzgün şekilde kimlik doğrulaması yapamadığında veya kimlik bilgilerinin süresi dolduğunda ya da hatalı yapılandırıldığında ortaya çıkar.

Belirtiler:

  • 401 Yetkisiz hatalar
  • "Taşıyıcı belirteç süresi doldu" mesajları
  • Aracısal kimlik doğrulama başarısız

Temel Neden:

  • Belirteçler yaklaşık bir saat sonra sona erer
  • Yanlış kimlik doğrulama yapılandırması
  • Eksik veya geçersiz kimlik bilgileri

Çözümler:

  • Taşıyıcı belirteç süresinin dolması durumunda

    Belirteçinizi yenileyin ve ortam değişkenlerinizi güncelleyin.

    # Get a new token
a365 develop get-token

# Update your .env file with the new token

  • Sunucu başına taşıyıcı belirteç hataları için

    Yapılandırma dosyanızda her sunucu için yer tutucu girişler olduğundan emin olun (BEARER_TOKEN_<SERVER_NAME>), ardından bunları doldurmak için a365 develop get-token komutunu tekrar çalıştırın. SDK, ToolingManifest.json içindeki mcpServerName kısmını büyük harfe çevirip, tireleri alt çizgiyle değiştirerek değişken adını türetir (örneğin, mcp_MailTools → BEARER_TOKEN_MCP_MAILTOOLS).

  • Aracı tabanlı kimlik doğrulama hataları (Python)

    .env dosyanızı kontrol edin:

    # Should be (with underscore):
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=SERVICE_CONNECTION

# Not:
AGENTAPPLICATION__USERAUTHORIZATION__HANDLERS__AGENTIC__SETTINGS__ALT_BLUEPRINT_NAME=ServiceConnection

  • Eksik kimlik bilgileri için

    Testten önce gerekli kimlik bilgilerinin mevcut olduğunu doğrulayın.

    .env veya appsettings.json'nin şunları içerdiğinden emin olun:

    • API anahtarları ve gizli anahtarlar
    • Kiracı kimliği
    • İstemci Kimliği
    • Blueprint Kimliği (aracı kimlik doğrulaması kullanılıyorsa)

    Doğrulama:

    Agents Playground'da basit bir istekle test edin. 401 hatası olmadan bir yanıt almalısınız.

  • Araç ve bildirim sorunları

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

E-posta alınmadı

Belirti: Aracı e-postanın gönderildiğini bildiriyor, ancak e-posta size ulaşmıyor

Çözümler:

  • Gereksiz veya Spam klasörünüzü kontrol edin.
  • E-posta teslimatı birkaç dakika gecikebilir. En fazla beş dakika bekleyin.
  • Alıcı e-posta adresinin doğru olduğunu doğrulayın.
  • E-posta gönderimi sırasında oluşan hatalar için aracı kayıtlarını kontrol edin.

Word yorum yanıtları çalışmıyor

Bilinen sorun: Bildirim servisi şu anda Word'daki yorumlara doğrudan yanıt veremiyor. Bu özellik geliştiriliyor.

Mesajlar aracıya iletilmiyor

Belirti: Aracı uygulamanız, Teams'de aracıya gönderilen mesajları almıyor.

Olası nedenler:

  • Geliştirici Portalı, aracı blueprint'iyle yapılandırılmamış.
  • Azure Web App sorunları (dağıtım hataları, uygulama çalışmaması, yapılandırma hataları).
  • Aracı örneği Teams'te doğru şekilde oluşturulmuyor.

Çözümler:

  • Geliştirici Portalı yapılandırmasını doğrulayın:

    Geliştirici Portalı'nda aracı blueprint yapılandırmasını tamamladığınızdan emin olun. Geliştirici Portalı'nda aracı taslağının nasıl yapılandırılacağını öğrenin.

  • Azure Web Uygulaması'nın durumunu kontrol edin:

    Aracınızı Azure'a dağıtırsanız, Web Uygulaması'nın düzgün çalıştığını kontrol edin.

    1. Azure portalına gidin.
    2. Web Uygulaması kaynağınıza gidin.
    3. Genel Bakış>Durum kısmını kontrol edin ("Çalışıyor" görünmeli).
    4. Çalışma zamanı hataları için İzleme altında Günlük akışı'nı kontrol edin.
    5. Dağıtımın başarılı olup olmadığını doğrulamak için Dağıtım Merkezi günlüklerini inceleyin.
    6. Yapılandırma>Uygulama ayarları sekmesinde tüm gerekli ortam değişkenlerinin bulunduğunu kontrol edin.

  • Aracı örneğinin oluşturulduğunu doğrulayın:

    Microsoft Teams'te aracı örneğini doğru şekilde oluşturduğunuzdan emin olun:

    1. Microsoft Teams açın.
    2. Uygulamalar'a gidin ve aracınızı arayın.
    3. Aracının arama sonuçlarında listelendiğini doğrulayın
    4. Bulunamazsa, Microsoft 365 yönetim merkezi - Aracılar'da yayınlandığını doğrulayın.
    5. Aracınızda Ekle seçeneğini seçerek yeni bir örnek oluşturun.
    6. Detaylı talimatlar için Aracı ekleme bölümüne bakınız.

Gözlemlenebilirlik loglarında sorun giderme

Aracınızın gözlemlenebilirlik logları beklendiği gibi görünmüyorsa, gözlemlenebilirlik rehberindeki Sorun Giderme bölümüne bakınız.

  • Last updated on