Aracınızı Agent Uygulaması olarak yayımla

Not

Bu makalede eski yayımlama deneyimi açıklanmaktadır. Yeni aracı yayımlama modeli için bkz. Aracı uygulamalarından yeni aracı uç noktasına geçiş ve yayımlama deneyimi.

Yayımlama, bir aracıyı Foundry projenizdeki bir geliştirme varlığından dış tüketicilerin kararlı bir uç nokta üzerinden çağırabileceği yönetilen bir Azure kaynağına taşır. Bunu, aracınızın "projemde çalışıyor" aşamasından "başkalarının kullanabileceği duruma geldiği" adıma taşıyan bir süreç olarak düşünün.

Bu makalede bir aracıyı yayımlama, kimlik doğrulamasını ve izinlerini yapılandırma, Yanıtlar API protokolünü kullanarak Aracı Uygulamanızı çağırma ve yeni aracı sürümlerini kullanıma sunarken Aracı Uygulamanızı güncelleştirme işlemleri gösterilir. Yayımladıktan sonra, Yanıtlar veya Etkinlik protokollerini kullanarak Aracı Uygulamanızı çağırabilirsiniz.

Yayımlama nedir?

Geliştirme sırasında, bir Foundry projesi içinde aracınızı derleyip test edebilirsiniz. Proje size ve ekip arkadaşlarınıza paylaşılan bir çalışma alanı verir, ancak proje erişimi olan herkes tüm aracılarla etkileşime girip aynı konuşma bağlamını ve izinlerini paylaştığından geniş bir dağıtım için tasarlanmamıştır. Yayımlama, bir aracıyı paylaşılan geliştirme alanının dışına ve üretime hazır bir Azure kaynağına taşıyan adımdır.

Aracı sürümünü yayımladığınızda, Foundry aracı sürümünüzü kendi çağırma URL'si, kimlik doğrulama ilkesi, benzersiz Entra aracısı kimliği ve benzersiz Entra aracısı şemasıyla sarmalayan bir Aracı Uygulaması kaynağı oluşturur. Dağıtım, uygulamanın alt kaynağı olarak da oluşturulur, yayınlanmakta olan belirli aracı sürümünü referans alır ve başlatma/durdurma yaşam döngüsünün yönetimini destekler.

Not

Foundry Aracı Uygulamaları Microsoft Entra aracı kayıt defterine kaydedilmez.

Neden yayımlansın?

Yayımlama, proje düzeyinde geliştirmenin sağlamadığı özellikler sunar:

Dış paylaşım — Ekip arkadaşlarınıza veya müşterilerinize Foundry projenize erişim vermeden erişim izni verin.
Kararlı uç nokta — Uygulama URL'si, yeni aracı sürümlerini kullanıma sunmanıza rağmen aynı kalır.
Ayrı ajan kimliği — Yayımlanan ajan, projenin paylaşılan kimliğinden ve şemasından ayrı olarak kendi Entra ajan kimliğini ve Entra ajan şeması alır.
Bağımsız RBAC ve yetkilendirme — Aracı Uygulaması, kendi RBAC kapsamına sahip, ayrı bir Azure kaynağıdır. Kimlerin bunu çağırabileceğini denetlemek için Foundry Kullanıcısı gibi rolleri doğrudan Aracı Uygulama kaynağına atayabilirsiniz.

Önemli

Foundry RBAC rolleri yakın zamanda yeniden adlandırıldı. Foundry User, Foundry Owner, Foundry Hesabı Sahibi ve Foundry Project Manager daha önce Azure Yapay Zeka Kullanıcısı, Azure Yapay Zeka Sahibi, Azure Yapay Zeka Hesabı Sahibi ve Azure Yapay Zeka Project Yöneticisi olarak adlandırıldı. Yeniden adlandırma kullanıma sunulmaya devam ederken bazı yerlerde önceki adları görmeye devam edebilirsiniz. Rol kimlikleri ve temel izinler yeniden adlandırma ile değiştirilmez.
Azure İlkesi Entegrasyonu — Azure Resource Manager (ARM) kaynağı olarak uygulama, Azure İlkesi tarafından yönetilebilir.
Microsoft 365 Copilot ve Teams ile Entegrasyon — Agent Uygulamanızı Microsoft 365 Copilot ve Teams gibi kanallara dağıtın.

Yayımladığınızda ne değişir?

En önemli değişiklik kimliktir. Yayımlanmamış bir ajan, projenin paylaşılan ajan kimliğini kullanır. Aracı yayımlandıktan sonra kendi ayrılmış aracı kimliğini alır. Aracı kimliği kimlik doğrulaması kullanan tüm araçlar projenin paylaşılan kimliğinden aracı uygulamasının benzersiz aracı kimliğine geçer.

Neleri izlemeli?

Kimlik değiştiğinden izinler otomatik olarak aktarılamaz. Bir aracı yayımladığınızda, aracının erişmesi gereken tüm kaynaklar için yeni aracı kimliğine RBAC izinlerini yeniden atamanız gerekir. Bu adımı atlarsanız, geliştirme sırasında çalışan araç çağrıları, aracı yayımlandıktan sonra yetkilendirme hatalarıyla başarısız olur.

Önkoşullar

En az bir ajan sürümü oluşturulmuş bir Dökümhane projesi
Aracıları yayımlamak için Foundry kaynak kapsamında Foundry Project Manager rolü
Yanıtlar API protokolünü kullanarak yayımlanmış bir ajanla sohbet etmek için Agent Application kapsamındaki Foundry User rolü (veya Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action iznine sahip özel bir rol)

Not

Foundry Agent Consumer rolü, ajan uç noktalarıyla etkileşim kurmak için tasarlanmıştır ve Ajan Uygulamalarını çalıştırma erişimi sağlamaz. Aracı Uygulamaları farklı bir izin yolu (Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action) kullanır. Dökümhane Kullanıcısı rolünü veya bu izni içeren özel bir rolü kullanın.

İzin yapılandırması için Azure rol tabanlı erişim denetimi (RBAC) hakkında bilgi
Foundry'deki Aracı kimliği kavramlarına aşinalık
Geliştirme ortamınızı hazırlama başlığı altında açıklandığı gibi gerekli dil çalışma zamanlarını, genel araçları ve Visual Studio Code uzantılarını yükleyin.

Önemli

Bu makaledeki kod, şu anda önizleme aşamasında olan paketleri kullanır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve üretim iş yükleri için önerilmez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Uygun Kullanım Koşulları.

Aracı Uygulamalarını ve dağıtımlarını anlama

Yayımlamadan önce projeler, aracı sürümleri, uygulamalar ve dağıtımlar arasındaki ilişkiyi anlamak önemlidir.

Foundry projelerinin aracı sürümlerini, uygulamalarını ve dağıtımlarını nasıl düzenlediğini gösteren, idare ve RBAC rollerini vurgulayan diyagram.

Dökümhane projesi aracılar, dosyalar ve dizinler gibi ilgili kaynakları gruplandıran bir iş kuruluşu kavramıdır. Aracı, yönergeleri, modeli ve araçlarıyla tanımlanan, birleştirilebilir birimi temsil eder. Aracı sürümü, bir aracının belirli bir sabit anlık görüntüsünü yakalar. Aracınızda her değişiklik yaptığınızda (istemi güncelleştirme veya araç ekleme gibi) yeni bir aracı sürümü oluşturulur. Her aracı sürümü, proje erişimi olan geliştiricilerin oluşturabileceği, çalıştırabildiği ve test edebildiği Foundry projesi altında kullanıma sunulur.

Bir Aracı Uygulaması bir veya daha fazla aracıyı hizmet olarak projelendirebilir; bağımsız olarak ele alınabilir, yönetilebilir ve yaşam döngüsü ve içerik yönetimi özellikleriyle donatılmıştır. Tüketiciler için kimlik doğrulaması, kimlik ve kararlı bir giriş noktası oluşturan dayanıklı bir arabirim sağlar. Dağıtım, yeni aracı sürümlerine başvurmak için başlatılabilir, durdurulabilir ve güncelleştirilebilen bir uygulama içindeki aracı sürümünün çalışan bir örneğidir.

Yönlendirme ve sürüm yönetimi

Her Aracı Uygulaması, belirli aracı dağıtımlarına yönlendirme tablosu işlevi görür. Aracı Uygulaması şu anda bir etkin dağıtımı destekleyerek uygulamanın uç noktası tarafından alınan trafiğin 100% bu dağıtıma yönlendirmektedir. Mevcut bir uygulamaya yeni bir aracı sürümü yayımladığınızda, uygulamanın uç noktası tarafından alınan trafiğin 100% yeni aracı sürümüne başvuran dağıtıma yönlendirilir.

Aracı Uygulaması'nın trafiği belirli bir aracı sürümünü çalıştıran bir dağıtıma yönlendirmesinin, kararlı bir giriş noktasını ve trafik akışını gösteren diyagramı.

Protokol

Aracı Uygulaması kaynağı, birden çok protokol ve kimlik doğrulama seçeneğine sahip kararlı bir uç noktayı kullanıma sunar.

Not

Şu anda bir Aracı Uygulaması için aynı anda yalnızca bir protokol (Yanıtlar veya Etkinlik Protokolü) etkinleştirilebilir.

Yanıtlar protokolü

Döküm aracıları varsayılan olarak, aracılarla etkileşime yönelik Yanıtlar temelinde OpenAI uyumlu bir protokolü kullanıma sunar.

Uygulamalar için bu uç nokta şu konumda kullanıma sunulur:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/openai

Uygulamalar aracılığıyla kullanıma sunulan OpenAI uyumlu API, kullanıcıların konuşmalarının özel kalmasını sağlamak için değiştirildi. Bu kısıtlama geçicidir ve son kullanıcı yalıtımını desteklediğimizde kaldırılacaktır. Sonuç olarak API, proje uç noktası tarafından sunulan OpenAI API'sinden daha sınırlıdır. Özellikle:

Yalnızca durum bilgisi olmayan Yanıtlar API'si (POST /responses) desteklenir.
Diğer API'ler, /conversations, /files, /vector_stores ve /containers erişilemez.

Bu sınırlama, istemcinin çok aşamalı konuşmalar için konuşma geçmişini depolaması gerektiği anlamına gelir.

Etkinlik Protokolü

Döküm temsilcileri, Azure Bot Hizmeti tarafından kullanılan Activity Protocol'ü de gösterebilir.

Uygulamalar için bu uç nokta şu konumda kullanıma sunulmuştur:

https://{accountName}.services.ai.azure.com/api/projects/{projectName}/applications/{applicationName}/protocols/activityprotocol

Kimlik doğrulama

Uygulamada gelen son kullanıcı kimlik doğrulamasını yapılandırabilirsiniz. Aşağıdaki seçenekler kullanılabilir:

Varsayılan (RBAC): Çağıranın Aracı Uygulaması kaynağında Foundry User rolüne (veya izni olan /applications/invoke/action özel bir role) sahip olması gerekir. Aracı uygulamanızı Yanıtlar API'sini kullanarak çağırmak istiyorsanız bu seçeneği belirleyin. Foundry RBAC rolleri hakkında daha fazla bilgi için bkz. Microsoft Foundry için Role tabanlı erişim denetimi.
Channels (Azure Bot Hizmeti): M365/Teams'de veya A365'e otomatik pilot olarak yayımladığınızda, kanallar kullanılan kimlik doğrulamasıdır. Bu, M365/Teams yayımlama akışı aracılığıyla kullanıcı arabiriminde otomatik olarak seçilir.

Api anahtarı kimlik doğrulaması Aracı Uygulamalarını çağırmak için desteklenmez. Arayanları yetkilendirmek için Microsoft Entra ID (Azure RBAC) kullanın.

Aracı yayımlama

REST API

Aracı sürümünü yayımlamak için aracı sürümünüze başvuran bir uygulama ve dağıtım oluşturmanız gerekir.

Önemli

Aracı Uygulamaları Azure kaynaklardır. Yönetim uç noktasını çağırırken aboneliğiniz ve hesabınız için kullanılabilen en son API sürümünü kullanın.

Başlamadan önce

Oturum açın ve Azure Resource Manager erişim belirteci alın:

az login
az account get-access-token --resource https://management.azure.com

Aşağıdaki isteklerde accessToken değerini Authorization: Bearer <token> başlık olarak kullanın.

Yalnızca belirteç değerini yakalamak istiyorsanız (örneğin, bir betikte kullanmak için) şunu kullanın:

az account get-access-token --resource https://management.azure.com --query accessToken -o tsv

İstek URL'si için ihtiyacınız olan değerleri toplayın.
- subscription_id: Foundry kaynağınızı içeren aboneliği kullanın. Azure portalında (Ubscriptions) veya az account show --query id -o tsv çalıştırarak bulabilirsiniz.
- resource_group: Dökümhane kaynağınızı içeren kaynak grubu. Azure portalındaki Dökümhane kaynağı Overview sayfasında bulabilirsiniz.
- account_name: Dökümhane kaynağınızın adı (Azure kaynak adı).
- project_name: Foundry projesinin adı.
- application_name ve deployment_name: Oluşturmak istediğiniz Aracı Uygulaması ve dağıtımı için adları seçin.
Bir api-version seçin.

1. Aracı uygulaması oluşturun.

Aracı Uygulamalar için tam özellik başvurusu ve altyapı-kod olarak (Bicep) örneği için Microsoft.CognitiveServices/accounts/projects/applications adresindeki Azure Resource Manager şablon başvurusuna bakın.

Gerekli alan: agentName alanını, yayımlamak istediğiniz aracının adı olarak ayarlayın.

Aşağıdaki örnekte yalnızca gerekli en düşük alanlar gösterilmektedir. Varsayılan olarak authorizationPolicyDefault (Azure RBAC) olarak ayarlanır ve trafficRoutingPolicy tüm trafiği ilk dağıtıma yönlendirir.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "agents": [{"agentName": "Publishing Agent"}]
  }
}

2. Aracı dağıtımı oluşturun.

Aracı dağıtımları için tam özellik referansı ve altyapı-kod (Bicep) örneği için Microsoft.CognitiveServices/accounts/projects/applications/agentDeployments adresindeki Azure Resource Manager şablon referansına bakın.

Gerekli alanlar:

deploymentType: Dağıtım modu. Managed öğesini istem temsilcileri için kullanın. Barındırılan aracılar için Hosted kullanın.
agents: Dağıtılacak aracı adı ve sürümü.
protocols: Dağıtımın ortaya çıkardığı protokol. Yanıtlar için protocol öğesini Responses olarak ve version öğesini 1.0 olarak ayarlayın.

Yalnızca barındırılanlar için ek gereksinim alanları:

minReplicas: En az çoğaltma sayısını ayarlar
maxReplicas: En fazla çoğaltma sayısını ayarlar

Yönlendirme ajanları

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "1"
        }
    ]
  }
}

Barındırılan aracılar

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json
{
  "properties": {
    "displayName": "Test Hosted Deployment",
    "deploymentType": "Hosted",
    "minReplicas": 1,
    "maxReplicas": 1,
    "protocols": [
        {
            "protocol": "Responses",
            "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "ContainerAgent",
            "agentVersion": "1"
        }
    ]
  }
}

3. Dağıtımın çalıştığını doğrulama

Prompt agent dağıtımları genellikle otomatik olarak çalışmaya başlar. Barındırılan aracı dağıtımları yayımlanan aracı sürümünün durumunu devralır. Sürüm durdurulursa, dağıtım da durdurulur.

Geçerli durumu denetlemek için dağıtım kaynağını alın ve state özelliğini inceleyin.

GET https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}

Durdurulmuş dağıtımı başlatmak için aşağıdaki çağrıyı kullanın:

POST https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}/start?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

Yayımlamanın başarılı olduğunu doğrulama

Uç noktayı tüketicilerle paylaşmadan önce ajanınızın başarıyla yayımlandığını doğrulayın. Yayımladıktan sonra şunları doğrulayın:

Aracı Uygulama kaynağı mevcut.
Dağıtım devam ediyor.
Uygulama uç noktasını çağırabilirsiniz.

Uç noktayı çağırarak hızlı doğrulama

Aşağıdaki komutları çalıştırmak için Azure CLI gerekir.

Arayan kullanıcı için bir erişim belirteci alın.

az account get-access-token --resource https://ai.azure.com

Aracı Uygulaması uç noktasını (Yanıtlar protokolü) çağırın.

curl -X POST \
  "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai/responses?api-version=2025-11-15-preview" \
  -H "Authorization: Bearer <access-token>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Say hello"}'

403 Forbidden alırsanız, arayan kişinin Agent Application kaynağında Foundry User rolüne sahip olduğunu doğrulayın.

Yayımlanmış aracı uygulamasını güncelleştirme

Aracınızın yeni bir sürümünü dağıtmanız gerektiğinde, yeni aracı sürümüne başvurmak için mevcut uygulamayı ve dağıtımı güncelleştirin.

Dökümhane portalı

Aracı Oluşturucusu'nda, yayımlamak istediğiniz belirli aracı sürümüne gidin.
Güncelleştirmeleri Yayımla'yı seçin.
Güncelleştirmeyi onaylayın. Aracı Uygulaması otomatik olarak 100% trafiği yeni aracı sürümüne yönlendirir.

Kararlı uç nokta URL'si değişmeden kalır ve aşağı akış tüketicilerinin güncelleştirme tarafından kesintiye uğramamasını sağlar.

REST API

Aracı adınız aynı kalırsa ve yalnızca yeni bir aracı sürümü dağıtmak istiyorsanız, dağıtımı yeni bir aracı sürümüne başvuracak şekilde güncelleştirin.

PUT https://management.azure.com/subscriptions/{{subscription_id}}/resourceGroups/{{resource_group}}/providers/Microsoft.CognitiveServices/accounts/{{account_name}}/projects/{{project_name}}/applications/{{application_name}}/agentdeployments/{{deployment_name}}?api-version={{api_version}}
Authorization: Bearer {{token}}
Content-Type: application/json

{
  "properties":{
    "description": "This is a managed deployment",
     "displayName": "Test Managed Deployment",
    "deploymentType": "Managed",
    "protocols": [
        {
          "protocol": "Responses",
          "version": "1.0"
        }
    ],
    "agents": [
        {
            "agentName": "Publishing Agent",
            "agentVersion": "<updated-agent-version>"
        }
    ]
  }
}

Farklı bir adla bir aracıyı dağıtmak için şunları gerçekleştirmeniz gerekir:

Aracı Uygulamasını yeni aracı adını kabul edecek şekilde güncelleyin.
Yeni ajan sürümünü referans almak için bir dağıtım oluşturun veya güncelleyin.
Yeni bir dağıtım oluşturduysanız, 100% trafik yeni dağıtıma gidecek şekilde Aracı Uygulamasının trafik yönlendirme ilkesini güncelleştirin.

Kullanıcılara yayımlanmış aracı çağırma erişimi verme

Aracıyı yayımladıktan sonra, arayanların Agent Application kaynağında Microsoft.CognitiveServices/accounts/AIServices/applications/invoke/action rolüne (veya iznini içeren özel bir role) sahip olması gerekir. Bu rol atamasının kapsamı tek bir Aracı Uygulaması olarak belirlenmiştir, böylece kullanıcılara Foundry projenizin tamamına veya diğer aracılara erişim vermeden tek bir yayımlanmış aracıya erişim verebilirsiniz.

Not

Foundry Agent Consumer rolü, aracı uç noktalarıyla doğrudan etkileşim için tasarlanmıştır ve Agent Applications'a erişim sağlamaz. Foundry User veya Ajan Uygulaması erişimi için gerekli izne sahip özel bir rol kullanın.

Önemli

Aracı Uygulaması RBAC, Entra aracı kimliği aracılığıyla değil Azure Resource Manager aracılığıyla yönetilir. Yayımlanan ajan tarafından alınan Entra ajan kimliği, ajanın araçlara ve kaynaklara kendi giden çağrıları için kullanılır. Yayımlanan aracıyı kimin çağırabileceğini kontrol etmek için, Azure portalı, Azure CLI veya REST API kullanarak Aracı Uygulaması ARM kaynağında Azure RBAC rolleri atayın.

Azure RBAC hakkında daha fazla bilgi için bkz. Microsoft Foundry için Rol tabanlı erişim kontrolü

Aracı Uygulamanızı çağırma

Not

Aracı uygulamaları şu anda bir kerede bir protokolü destekler, ancak bu değiştirilebilir. Dökümhane kullanıcı arabiriminde bir Aracı Uygulaması oluşturduğunuzda, varsayılan olarak Yanıtlar API protokolü kullanılır. Daha sonra Microsoft 365 veya Teams'de yayımlarsanız yayımlama akışı Etkinlik Protokolü'ne yapılandırılır.

Yayımladıktan sonra, Yanıtlar API'si protokolünü veya etkinlik protokolünü kullanarak aracınızı uç noktası üzerinden çağırırsınız. Etkinlik protokolü, aracınız Microsoft 365 ve Teams'de yayımlandığında kullanılır.

Agent Uygulamanızı Microsoft 365 Copilot ve Teams'de kullanmak için Agentleri Microsoft 365 Copilot ve Microsoft Teams'e Yayınlayın bölümüne bakın.

Temsilcinizi bir otopilot olarak yayımlamak için bkz. Agent 365’te bir temsilciyi otopilot olarak yayımlama

Yanıtlar API protokolünü kullanarak çağırma

Yanıtlar API'sini kullanarak Aracı Uygulamanızı çağırmak için şunları yapmanız gerekir:

Aracı Uygulaması kapsamındaki Dökümhane Kullanıcı rolü
openai ve azure-identity paketleri, "Geliştirme ortamınızı hazırlama" bölümünde açıklandığı şekilde yüklendi ve kimlik doğrulaması yapıldı.

OpenAI istemcisini Aracı Uygulamaları uç noktasıyla kullanma

from openai import OpenAI 
from azure.identity import DefaultAzureCredential, get_bearer_token_provider 

# Replace placeholders with your resource, project, and app names
BASE_URL = "https://<foundry-resource-name>.services.ai.azure.com/api/projects/<project-name>/applications/<app-name>/protocols/openai"

# Create OpenAI client authenticated with Azure credentials
openai = OpenAI(
    api_key=get_bearer_token_provider(DefaultAzureCredential(), "https://ai.azure.com/.default"),
    base_url=BASE_URL,
    default_query={"api-version": "2025-11-15-preview"}
)

# Send a request to the published agent
response = openai.responses.create( 
  input="Write a haiku", 
) 
print(f"Response output: {response.output_text}")

Bu yaklaşım, Azure kimlik bilgilerini kullanarak kimlik doğrulaması yapar ve çağıranın Aracı Uygulaması kaynağında Foundry User rolüne sahip olmasını gerektirir.

Güvenlik ve gizlilikle ilgili dikkat edilmesi gerekenler

En az ayrıcalık kullanın. Kullanıcılara ihtiyaç duydukları en düşük rolü verin (örneğin, yayımlama izinlerini çağırma izinlerinden ayırın).
Yalnızca bir aracıyı paylaşmanız gerektiğinde proje erişimini paylaşmaktan kaçının. Uygulama kaynağında Aracı Uygulaması uç noktasını ve RBAC'yi kullanın.
Erişim belirteçlerini kaynak koduna, betiklere veya istemci uygulamalarına eklemeyin. Uygulamanız için uygun Microsoft Entra kimlik doğrulama akışlarını kullanın.
Yayımladığınızda kimlik değişikliklerini planlayın. Aracı kimliği ile kimliği doğrulanmış araç çağrıları, proje kimliği yerine, yayımlandıktan sonra uygulama kimliğini kullanır.
Çok aşamalı deneyimlere ihtiyacınız varsa konuşma geçmişini istemcinizde depolayın. Aracı Uygulamaları şu anda API'leri kısıtlar ve yanıtları depolamaz.

Sınırlama

Agent Uygulamaları olarak yayımlanan aracıların sınırlamaları şunlardır:

Sınırlama	Açıklama
Yalnızca Durum Bilgisi Olmayan Yanıtlar API'si	Yalnızca stateless (durum bilgisi taşımayan) Yanıtlar API'si desteklenmektedir. Diğer API'ler, `/conversations`, `/files`, `/vector_stores` ve `/containers` erişilemez.
Kullanıcı arabirimi veya CLI yönetimi yok	Gelişmiş yönetim işlemleri için ayrılmış kullanıcı arabirimi/CLI yoktur. Dökümhane portalı yayımlama akışında bulunmayan yönetim işlemleri için REST API'sini kullanın.

Sorun giderme

Sorunu	Olası neden	Çözünürlük
Yayımlama Aracısı devre dışı bırakıldı	Foundry kaynak kapsamında Foundry Proje Yöneticisi rolü eksik	Foundry Proje Yöneticisi rolünü yalnızca proje kapsamında değil, Foundry kaynağı (hesap) kapsamında atayın.
`403 Forbidden` uç noktayı çağırırken	Çağıranın Aracı Uygulama kaynağında çalıştırma izinleri yok.	Aracı Uygulama kaynağında çağırana Foundry User rolünü atayın. Bkz: Kullanıcılara yayımlanmış aracı çağırmak için erişim verme.
`401 Unauthorized` uç noktayı çağırırken	Erişim belirteci eksik, süresi dolmuş veya yanlış kaynak için	yeniden kimlik doğrulaması yapın ve `https://ai.azure.com` için bir belirteç isteyin.
Araç çağrıları yayımlandıktan sonra başarısız oluyor.	Aracı Uygulama kimliği, proje kimliğiyle aynı erişime sahip değil	Erişmesi gereken alt akış Azure kaynakları için gerekli RBAC rollerini yayınlanmış aracı kimliğine yeniden atayın.
Çok aşamalı konuşmalar beklendiği gibi çalışmıyor	Aracı Uygulamaları sizin için konuşma durumunu depolamaz	Konuşma geçmişini istemcinizde depolayın ve isteğinizin bir parçası olarak bağlamı gönderin.

Kaynakları temizleme

Artık yayımlanmış bir uç noktaya ihtiyacınız yoksa Aracı Uygulaması Azure kaynağını (ve dağıtımlarını) silin. Uygulamanın silinmesi, Foundry projesindeki aracı sürümlerinizi silmez.

Referans: Aracı Uygulaması ve dağıtım özellikleri

REST API istekleri oluştururken veya yanıtlarda döndürülen alanları anlamanız gerektiğinde aşağıdaki tabloları kullanın.

Aracı Uygulaması özellikleri

Adı	Açıklama	Değer	İstek gövdesinde belirtilebilir mi?
`displayName`	Temsilci uygulamasının görünen adı	Dize	✅
`baseUrl`	Aracı uygulamasının ayrılmış uç noktası	Dize	❌ (sadece okunabilir)
`agents`	Uygulama tarafından erişime açılan ajanlar.	nesne dizisi	✅
`agentIdentityBlueprint`	Aracı uygulamasıyla ilişkili aracı kimliği şeması.	Nesne	❌ (sadece okunabilir)
`defaultInstanceIdentity`	Temsilci uygulamasıyla ilişkili aracı kimliği	Nesne	❌ (sadece okunabilir)
`authorizationPolicy`	Kullanıcıların uygulamada nasıl kimlik doğrulaması yapmasına izin verildiğini tanımlar. Belirtilmezse, bu alan varsayılan olarak ayarlanır	Nesne	✅
`trafficRoutingPolicy`	Aracının trafiği hangi dağıtıma gönderdiğini tanımlar. Şu anda tüm trafik yalnızca bir dağıtıma yönlendirilebilir.	Nesne	✅
`provisioningState`	İşlem çağrıldığında aracı uygulamasının durumunu alır.	Dize	❌ (sadece okunabilir)
`isEnabled`	Aracı uygulamasının etkin mi yoksa devre dışı mı olduğunu belirtir.	Boolean	✅

Dağıtım özellikleri

Adı	Açıklama	Değer	İstek gövdesinde belirtilebilir mi?
`displayName`	Dağıtımın görünen adı.	Dize	✅
`deploymentId`	Belirli bir kaynak tanımlayıcısıyla dağıtımın her ayrı yaşam süresi için sistem tarafından oluşturulan benzersiz tanımlayıcı.	Dize	❌ (sadece okunabilir)
`state`	Dağıtımın durumu.	enum (`Starting`, `Running`, `Stopping`, , `Failed`, `Deleting`, `Deleted`) `Updating`	❌ (salt okunur) durumu denetlemek için başlat/durdur gibi açık API'ler var
`protocols`	Dağıtım tarafından desteklenen protokoller	nesne dizisi	✅
`agents`	Belirli bir dağıtıma bağlı aracı sürümü.	nesne dizisi	✅
`provisioningState`	İşlem çağrıldığında dağıtımın durumunu alır.	enum (`Succeeded`, `Failed`, `Canceled`, `Creating`, `Updating`, `Deleting`)	❌ (sadece okunabilir)
`deploymentType`	Dağıtıma bağlı ajan türü	Numaralandırma (`Hosted` veya `Managed`)	✅
`minReplicas`	Her zaman çalışan minimum kopya sayısı.	Tamsayı	✅ (yalnızca dağıtımTürü: `Hosted`)
`maxReplicas`	Çalıştırılabilen en fazla kopya sayısı.	Tamsayı	✅ (yalnızca dağıtımTürü: `Hosted`)

SSS

Yayımlanmış aracılar için konuşmalar neden kalıcı değildir (diğer bir deyişle neden yalnızca durum bilgisi taşımayan yanıtlar desteklenir)?

Bugün, geçici bir sınırlama olarak, yayımlanan aracıların yalnızca durum bilgisi olmayan Yanıtlar API'si etkileşimlerini (yani sürekli konuşmaları desteklemediği) desteklediği vardır. Bunu düzeltmek için çalışma zaten devam ediyor.

Bu sınırlamanın nedeni, Foundry Aracısı Hizmeti yönetilen konuşma geçmişini desteklese de, aynı proje içindeki konuşmalar arasında son kullanıcı yalıtımını henüz zorunlu kılmamasıdır. Başka bir deyişle, birisi başka bir kullanıcının konuşma kimliğini biliyorsa, kendi konuşma geçmişi olmasa bile bu konuşma geçmişine erişebilir. Bu, tek bir projedeki geliştirme bağlamında kabul edilebilir, ancak müşterilerin kullanıcı başına katı konuşma yalıtımına ihtiyaç duyduğu üretim için kabul edilemez.

Aracı Uygulamaları, kararlı sürümler, yapılandırma ve denetimli erişim ile proje geliştiricilerinden ayrı olarak farklı bir hedef kitleye (örneğin, kuruluşunuzdaki veya müşterilerinizdeki diğer kişilere) işlevsellik sunmak için tasarlanmıştır. Bu hedef göz önüne alındığında, aracı uygulamalarının kullanıcıları doğal olarak uygulamayla etkileşimlerinin özel olmasını ve başkaları tarafından görülemediğini bekler. Üzerinde oluşturduğumuz tek kullanıcılı OpenAI API'leri yerel veri yalıtımı sağlamadığından ve bu yalıtım katmanını kendimiz oluşturmamız gerektiğinden bu şu anda mümkün değildir. Uygulamalar için tam son kullanıcı veri yalıtımını destekleyene kadar yalnızca durum bilgisi olmayan yanıtlar kullanılabilir. Bu sınırlama geçicidir.

Yayınlanmış bir ajanın fiyatlandırma modeli nedir? Maliyet bir tüketim modeline mi bağlı yoksa aracı yayımlandıktan sonra uygulama kaynağında (uç nokta) temel altyapı dağıtıldığından istemci ücrete tabi mi?

Yayımlanan ajanlar bir yayımcı-ödeme modeli kullanır: Yayımcı (Foundry proje sahibi), ajan bir uygulama olarak yayımlandığında dağıtılan temel altyapıya bağlı olarak masraflara katlanır, çağrı başına tüketime bağlı değildir. Yayımlanan uygulamanın son kullanıcıları varsayılan olarak herhangi bir maliyet doğurmasa da, müşteriler kuruluş veya dış kullanıcıları için tüketim tabanlı bir model uygulamak istediklerinde uygulamanın önüne kendi ölçüm veya faturalama katmanlarını yerleştirmeyi tercih edebilir.

Microsoft Foundry'deki yükseltilmiş rol görevleri — yayımlama aracıları için rol gereksinimleri.
Foundry'de ajan kimliği kavramları hakkında bilgi edinin
Barındırılan aracılar hakkında bilgi edinin
Microsoft 365 Copilot ve Microsoft Teams için aracıları nasıl yayımlayacağınızı öğrenin.
Aracı Uygulamalarından yeni aracı modeline geçiş

Sonraki adımlar

Aracıları uygun ölçekte yönetme

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-06-19

Aracınızı Agent Uygulaması olarak yayımla

Yayımlama nedir?

Neden yayımlansın?

Yayımladığınızda ne değişir?

Neleri izlemeli?

Önkoşullar

Aracı Uygulamalarını ve dağıtımlarını anlama

Yönlendirme ve sürüm yönetimi

Protokol

Yanıtlar protokolü

Etkinlik Protokolü

Kimlik doğrulama

Aracı yayımlama

REST API

Başlamadan önce

1. Aracı uygulaması oluşturun.

2. Aracı dağıtımı oluşturun.

Yönlendirme ajanları

Barındırılan aracılar

3. Dağıtımın çalıştığını doğrulama

Yayımlamanın başarılı olduğunu doğrulama

Uç noktayı çağırarak hızlı doğrulama

Yayımlanmış aracı uygulamasını güncelleştirme

Dökümhane portalı

REST API

Kullanıcılara yayımlanmış aracı çağırma erişimi verme

Aracı Uygulamanızı çağırma

Yanıtlar API protokolünü kullanarak çağırma

OpenAI istemcisini Aracı Uygulamaları uç noktasıyla kullanma

Güvenlik ve gizlilikle ilgili dikkat edilmesi gerekenler

Sınırlama

Sorun giderme

Kaynakları temizleme

Referans: Aracı Uygulaması ve dağıtım özellikleri

SSS

İlgili içerik

Sonraki adımlar

Geri Bildirim

Ek kaynaklar