Azure İşlevleri hosted skills reference

Bu makale, Azure İşlevleri barındırılan beceriler için yapılandırma referansını sağlar. Çalışma zamanına genel bir bakış ve ne zaman kullanılacağına dair rehberlik için Azure İşlevleri hosted skills'e bakınız.

Important

Azure İşlevleri hosted skills şu anda önizleme aşamasında. Özellikler, yapılandırma adları ve desteklenen bağlayıcılar genel kullanılabilirlik öncesinde değişebilir.

Ajan dosya referansı

Bir ajan dosyası (.agent.md) ajanı yapılandırmak için YAML ön madde kullanır ve ardından markdown talimatları gelir.

Ön madde alanları

Bir ajanı yapılandırmak için şu ön bilgi alanlarını kullanın:

Alan	Zorunlu	Description
`name`	Yes	Temsilcinin görünen adı.
`description`	Yes	Aracının ne yaptığına ve ne zaman kullanılması gerektiğine dair kısa açıklama.
`trigger`	Evet (etkinleştirilmedikçe `builtin_endpoints` )	Aracının nasıl çağrılacağını tanımlar. Aracı dosyası başına yalnızca bir tetikleyiciye izin verilir.
`builtin_endpoints`	No	Yerleşik hata ayıklama ve oluşturma uç noktalarını etkinleştirir. Tüm yerleşik uç noktaları etkinleştirmek için `true` kullanın veya `debug_chat_ui`, `chat_api` ve `mcp` öğelerini ayrı ayrı yapılandırın. `debug_chat_ui: true` ayrıca dahili kullanıcı arayüzü bu API'leri çağırdığı için destek `chat` ve `chatstream`uç nokta rotalarını da etkinleştiriyor.
`input_schema`	No	HTTP ile tetiklenen aracılar için HTTP istek gövdelerini doğrulamak için kullanılan JSON Şeması.
`logger`	No	Aracı için çalışma zamanı günlüğünün etkinleştirilip etkinleştirilmediğini denetler. Varsayılan değer `true`’dır.
`mcp`	No	`mcp.json` konumundan keşfedilen MCP sunucularına erişimi denetler. `false` Bu aracı için MCP sunucularını devre dışı bırakmak veya belirli sunucuları kaldırmak için kullanın`exclude`.
`metadata`	No	Kendi kuruluşunuz veya araçlarınız için özel meta veriler.
`model`	No	veya uygulama ayarlarında yapılandırılan `agents.config.yaml` varsayılan modeli geçersiz kılar.
`response_example`	No	HTTP ile tetiklenen aracılardan gelen yapılandırılmış yanıtlara yol göstermek için kullanılan örnek yanıt şekli.
`response_schema`	No	HTTP ile tetiklenen aracılar tarafından döndürülen yapılandırılmış yanıtları doğrulamak için kullanılan JSON Şeması.
`skills`	No	Keşfedilen becerilere erişimi kontrol eder. Bu ajan için becerileri devre dışı bırakmak üzere `false` kullanın veya belirli becerileri kaldırmak için `exclude` kullanın.
`substitute_variables`	No	Ön madde ve talimatlara ortam değişkeni yerine koyma uygulanıp uygulanmadığını kontrol eder. Varsayılan değer `true`’dır.
`system_tools`	No	Bir ajanın sandbox tabanlı çalıştırma gibi yapılandırılmış sistem araçlarından vazgeçmesine olanak tanır.
`timeout`	No	Varsayılan yürütme zaman aşımını saniyeler içinde geçersiz kılar.
`tools`	No	Keşfedilen özel Python araçlarına erişimi kontrol eder. Bu ajan için özel araçları devre dışı bırakmak üzere `false` kullanın veya belirli araçları kaldırmak için `exclude` kullanın.
`workflows`	No	Deneysel dinamik iş akışlarını mümkün kılar, iş akışı güvenli araçları filtreler ve iş akışı alt ajanlarına erişim sağlar. Daha fazla bilgi için bkz. Azure İşlevleri hosted skills'te Dynamic Workflows.

Tetikleyici yapılandırması

Her ajan dosyası, ön maddedeki trigger nesnede tanımlanan bir tetikleyiciyi destekler.

Alan	Zorunlu	Description
`type`	Yes	Tetik bağlama türü. İzin verilen değerler için desteklenen türler tablosuna bakınız.
`args`	Türüne bağlıdır	Ajanı hangi olayın başlatacağını ayarlayan tetikleyiciye özgü ayarlar.

Desteklenen tetikleyici türleri

Aşağıdaki tablo desteklenen trigger.type değerleri, gerekli argsdeğerleri ve tam tür referansına bağlantıları listeler:

`trigger.type`	Gerekli `args`	Referans
`http_trigger`	`route`	HTTP tetikleyicisi
`timer_trigger`	`schedule`	Zamanlayıcı tetikleyicisi
`queue_trigger`	`queue_name`, `connection`	Kuyruk tetikleyicisi
`blob_trigger`	`path`, `connection`	Blob tetikleyicisi
`event_grid_trigger`	(yok)	Event Grid tetikleyicisi
`event_hub_message_trigger`	`event_hub_name`, `connection`	Event Hub tetikleyicisi
`service_bus_queue_trigger`	`queue_name`, `connection`	Service Bus kuyruk tetikleyicisi
`service_bus_topic_trigger`	`topic_name`, `subscription_name`, `connection`	Service Bus konu tetikleyicisi
`cosmos_db_trigger`	`connection`, `database_name`, `container_name`	Cosmos DB tetikleyicisi
`cosmos_db_trigger_v3`	`database_name`, `collection_name`, `connection_string_setting`	Cosmos DB tetikleyici v3
`sql_trigger`	`table_name`, `connection_string_setting`	SQL tetikleyicisi
`mysql_trigger`	`table_name`, `connection_string_setting`	MySQL tetikleyicisi
`kafka_trigger`	`topic`, `broker_list`	Kafka tetikleyicisi
`dapr_binding_trigger`	`binding_name`	Dapr bağlama tetikleyicisi
`dapr_service_invocation_trigger`	`method_name`	Dapr service invocation trigger
`dapr_topic_trigger`	`pub_sub_name`, `topic`	Dapr konu tetikleyicisi
`generic_trigger`	`type` (ciltleme tipi adı)	Genel tetikleyici
`connector_trigger`	Connector Namespace'te yapılandırıldı.	Konnektör tetikleyicisi

Tetikleyici örnekler

Aşağıdaki örnekler yaygın tetik konfigürasyonlarını gösterir:

Zamanlayıcı tetikleyici ( her gün saat 15:00 UTC'de çalışıyor)

trigger:
  type: timer_trigger
  args:
    schedule: "0 0 15 * * *"

HTTP tetikleyicisi

trigger:
  type: http_trigger
  args:
    route: summarize
    auth_level: FUNCTION

Kuyruk tetikleyicisi

trigger:
  type: queue_trigger
  args:
    queue_name: work-items
    connection: AzureWebJobsStorage

Blob tetikleyicisi

trigger:
  type: blob_trigger
  args:
    path: uploads/{name}
    connection: AzureWebJobsStorage

Uygulama genelinde yapılandırma (agents.config.yaml)

Tüm aracıların devralabileceği uygulama genelinde çalışma zamanı varsayılanları için agents.config.yaml kullanın. Çalışma zamanı bu dosya olmadan da bir uygulama yükleyebilir. Model dağıtımı, zaman aşımı veya korumalı alan yürütme uç noktası gibi paylaşılan ayarlara ihtiyaç duyduğunuzda ekleyin.

Bu dosya, uygulama düzeyinde bir giriştir. Çalışma zamanı ayrıca mcp.json'den MCP sunucularını, skills/'den becerileri ve tools/'den özel Python araçlarını bulur. Bu özellikler aracılarda varsayılan olarak etkinleştirilir. Aracı ön öğesi çalışma zamanı varsayılanlarını geçersiz kılabilir veya devralınan MCP sunucularını, becerilerini ve araçlarını filtreleyebilir.

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

model: $FOUNDRY_MODEL
timeout: 900

Tek tek aracılar, desteklenen çalışma zamanı ayarlarını kendi ön maddelerinde geçersiz kılabilir.

Yapılandırma alanları

agents.config.yaml içinde bu üst düzey alanları kullanın:

Alan	Zorunlu	Description
`model`	No	Kendi başlık bölümünde `model` belirtmeyen aracılar tarafından kullanılan varsayılan model veya model dağıtımı.
`timeout`	No	Varsayılan çalıştırma zaman aşımı, saniye cinsinden. Çalışma zamanı varsayılanı 900 saniyedir.
`system_tools.dynamic_sessions_code_interpreter.endpoint`	Yalıtılmış yürütme kullanılırken	Korumalı alan araçları tarafından kullanılan Azure Container Apps dinamik oturum havuzu için yönetim uç noktası.
`system_tools.dynamic_sessions_code_interpreter.client_id`	No	Oturum havuzunu çağırmak için kullanılan yönetilen kimliğe ait istemci kimliği.
`tools.exclude`	No	`tools/` klasöründe bulunan özel Python araçları için genel dışlama listesi.

Çözüm sırası

Çalışma zamanı, değerleri önce ajan ön bilgisinden, ardından agents.config.yaml, sonra uygulama ayarlarından ve çalışma zamanı varsayılanlarından çözümler. agents.config.yaml içindeki dize değerleri, örneğin $AZURE_OPENAI_DEPLOYMENT veya $ACA_SESSION_POOL_ENDPOINT gibi uygulama ayarlarına başvurabilir.

Model, zaman aşımı ve sistem aracı varsayılanlarını agents.config.yaml içinde tutun. Bağlayıcı ad alanlarından gelen MCP sunucu uç noktaları da dahil olmak üzere uzak MCP sunucu tanımlarını mcp.json içinde tutun.

Değişken değiştirme

Çalışma zamanı, uygulama ayarlarını ve ortam değişkenlerini ajan ön bilgisindeki, ajan yönerge gövdelerindeki, agents.config.yaml ve mcp.json içindeki dize değerlerine yerleştirebilir.

Yerine koymelemeler için veya %SETTING_NAME%veya $SETTING_NAME . Çalışma zamanı bu iki formatı aynı şekilde yönetiyor. Değişken adları bir harf veya alt çizgiyle başlamalıdır ve harf, sayı ve alt çizgi içerebilir.

model: $FOUNDRY_MODEL
system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: %ACA_SESSION_POOL_ENDPOINT%

Email the summary to $TO_EMAIL.

{
  "servers": {
    "office365": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL"
    }
  }
}

Yerine geçme kuralları:

Nesneler veya listeler içinde iç içe yerleştirilmiş dizileri içeren dize değerleri için geçerlidir. Nesne anahtarları için geçerli değil.
Aracı yönergesi gövdelerindeki çitle çevrili kod blokları ikame edilmez; bu nedenle örneklerde $VALUE veya %VALUE% metni olduğu gibi yer alabilir.
Yerine getirilen içerikte kelimesi kelimesi kelimesine yer tutucular için kullanılır$$SETTING_NAME.%%SETTING_NAME%%
Eksik değişkenler değişmeden bırakılır. Boş değerler boş dizelere çözümlenir.
Yerine geçme tek bir geçiştir. ${SETTING_NAME} sözdizimi desteklenmiyor.
Bir ajan yerine geçmeyi devre dışı bırakmak için, ajan dosyasında ayarlayın substitute_variables: false . Bu ayar, agents.config.yaml veya mcp.json içindeki değiştirme özelliğini devre dışı bırakmaz.

MCP sunucu yapılandırması (mcp.json)

Bir uygulama uzak MCP sunucuları kullandığında işlev uygulaması projesinin köküne ekleyin mcp.json . Çalışma zamanı, uzak HTTP veya akış destekli HTTP MCP sunucularını bu dosyadan keşfeder ve aracıya özel filtrelere bağlı olarak bu sunucuların araçlarını aracıların kullanımına sunar.

Sunucu giriş alanları

Her servers girdide şu alanları kullanın:

Alan	Zorunlu	Description
`type`	Yes	`http` veya `streamable-http` kullanın. Çalışma zamanı yerel `stdio` MCP sunucularını desteklemiyor.
`url`	Yes	Uzak MCP sunucu uç noktası. Ortam değişkeni değişimi desteklenir.
`headers`	No	Genel bir uzak MCP sunucusu için statik başlıklar. `mcp.json` içinde statik gizli bilgileri depolamayın.
`auth.scope`	Microsoft Entra kimlik doğrulaması kullanılırken	MCP sunucusuna yapılan çağrıların kimliğini doğrulamak için kullanılan Microsoft Entra belirteç kapsamı.
`auth.client_id`	No	Bu MCP sunucusuyla kimlik doğrulaması yaparken kullanılacak yönetilen kimliğin istemci kimliği. İşlev uygulamasının sistem tarafından atanan yönetilen kimliğini Azure kullanmak için bu alanı atla.

Kimlik Doğrulaması

Aracı bir bağlayıcı ad alanından yönetilen bir MCP sunucusu kullandığında Azure API Hub kapsamını kullanın. Kullanıcı gizli bilgilerini mcp.json içinde depolamayın.

{
  "servers": {
    "office365-outlook": {
      "type": "http",
      "url": "$O365_MCP_SERVER_URL",
      "auth": {
        "scope": "https://apihub.azure.com/.default",
        "client_id": "$O365_MCP_CLIENT_ID"
      }
    }
  }
}

Bu auth.client_id ayar, MCP sunucusuyla hangi yönetilen kimliğin kimlik doğrulaması yapacağını belirler. Bunu, kullanıcı tarafından atanan yönetilen kimliğin istemci kimliğine ayarlayın. Azure'da işlev uygulamasının sistem tarafından atanan yönetilen kimliğini kullanmak için bunu atlayın. Seçili kimliğin veya yerel olarak çalıştırdığınızda yerel geliştirici kimliğinizin MCP sunucusunu çağırmasına izin verilmelidir.

Azure bağlayıcıları

Bağlayıcılar, aracıların özel API istemci kodu olmadan dış hizmetlerle çalışmasını sağlar. Örneğin, Microsoft 365 Outlook bağlayıcısı e-posta gönderebilir, Teams bağlayıcısı iletilerle çalışabilir ve diğer bağlayıcılar Salesforce, SAP veya SQL gibi sistemlerde eylemleri çağırabilir. Bağlayıcı Ad Alanı, bu tümleştirmeleri uygulamanız için kullanılabilir hale getiren bağlantıları, tetikleyicileri ve MCP sunucularını barındırıyor.

Barındırılan bir beceri uygulamasında bağlayıcı yeteneklerini kullanmak için önce bir Bağlayıcı Isim Alanı kaynağı oluşturun, hizmete bir bağlantı oluşturun ve bu bağlantıyı yetkileyin. Sonra görevin bağlantıyı nasıl kullandığını seçin:

Bağlayıcı, bağlı bir hizmette yeni bir e-posta, Teams iletisi veya takvim olayı gibi bir şey olduğunda aracıları başlatır. Birini kullanmak için, Bağlayıcı Ad Alanı'nda yetkili bağlantıyı kullanan bir tetikleyici oluşturun ve aracıyı bu bağlayıcı tetikleyici tanımındaki tetikleyici adı ve bağımsız değişkenleriyle yapılandırın.
Bağlayıcı MCP araçları , aracıların e-posta gönderme veya kaydı güncelleştirme gibi hizmet eylemlerini çağırmasına olanak sağlar. Bunları kullanmak için, Bağlayıcı Ad Alanı'nda yetkili bağlantıyı kullanan bir MCP sunucusu oluşturun ve ardından MCP sunucu uç noktasını öğesine mcp.jsonekleyin.

Daha fazla bilgi için Azure İşlevleri'da bağlayıcıları kullanma konusuna bakın.

Yetenekler

Yeniden kullanılabilir prompt varlıklarını skills/ altında depolayın. Gerektiğinde etki alanına özgü yönergeleri kullanılabilir hale getirirken temel aracı yönergelerini küçük tutmaya yardımcı olur. Çalışma zamanı Agent Skills biçimini kullanır.

Yetenek formatı

Çalışma zamanı, işlev uygulaması projesinin kök dizinindeki skills/ öğesini tarar ve SKILL.md içeren klasörleri özyinelemeli olarak keşfeder.

skills/
  incident-response/
    SKILL.md
    triage-checklist.md
    escalation-policy.md

Dosya, SKILL.md YAML ön maddesini ve ardından markdown talimatlarını içerir.

---
name: incident-response
description: Triage production incidents, summarize impact, and recommend next steps. Use when the task mentions incidents, outages, alerts, or severity levels.
---

Follow the incident response checklist in [triage-checklist.md](triage-checklist.md).

Yazarlık kuralları

Ajan dosyalarınızı ve diğer proje kaynaklarınızı oluştururken şu yönergelere uyun:

Her beceri klasörü bir SKILL.md dosya içermelidir.
name ve description alanları gereklidir.
Yetenek isimleri için küçük harfler, rakamlar ve tek tire kullanın. Boşluk, alt çizgi, büyük harf, baştaki kısa çizgi, sondaki kısa çizgi veya yinelenen kısa çizgi kullanmayın.
Beceri adları uygulama genelinde benzersiz olmalıdır.
Açıklama hem becerinin ne yaptığını hem de aracının ne zaman kullanması gerektiğini açıklamalıdır. Çalışma zamanı, aracı becerinin tamamını ne zaman yükleyeceğine karar verebilsin diye önce beceri adlarını ve açıklamalarını yükler.
Beceriler, aynı beceri klasörüne birden çok markdown dosyası içerebilir. SKILL.md içinden yardımcı markdown dosyalarına göreli bağlantılar kullanarak referans verin.
Azure İşlevleri barındırılan yetenekler yalnızca markdown dosyalarını beceri içeriği olarak destekler. Bir yetenek çalıştırılabilir davranışa ihtiyaç duyuyorsa, o kodu özel bir Python aracı olarak paketleyin ve beceri talimatlarından araçla araca referans verin.

Ajan başına filtreleme becerileri

Aracılar, bulunan tüm becerileri varsayılan olarak devralır. Belirli bir aracı bunları kullanmaması gerektiğinde aracı dosyasındaki becerileri devre dışı bırakın veya hariç tutun:

skills: false

skills:
  exclude:
    - incident-response

Yalıtılmış yürütme

Kod yürütme veya tarayıcı otomasyonu için çalışma zamanı Azure Container Apps dinamik oturumları kullanabilir. Dinamik oturumlar, oturum havuzlarından yalıtılmış ortamlar sağlar. Çalışma zamanı, aracılara bir aracı sağlamak için execute_python kullanır.

Konfigürasyon

agents.config.yaml içinde korumalı alan yürütmesini yapılandırın:

system_tools:
  dynamic_sessions_code_interpreter:
    endpoint: $ACA_SESSION_POOL_ENDPOINT

Requirements

Oturum havuzu, --container-type PythonLTS ile oluşturulan havuz gibi bir Python kod yorumlayıcısı oturum havuzu olmalıdır.
endpoint değeri, oturum havuzu yönetim uç noktasıdır.
Azure'da, fonksiyon uygulaması tarafından kullanılan yönetilen kimlik oturum havuzunda kod çalıştırmak için gereken rol atamalarına sahip olmalıdır. Azure Container Apps kod yorumlayıcı oturumları, oturum havuzundaki Azure ContainerApps Session Executor ve Contributor rollerini gerektirir.
Yerel olarak çalışırken, geliştirici kimliğinizin oturum havuzuna aynı gerekli erişime sahip olması gerekir.
Korumalı alan yürütmesi için kullanıcı tarafından atanan bir yönetilen kimlik kullanmak üzere, system_tools.dynamic_sessions_code_interpreter.client_id değerini gerekli rol atamalarına sahip kimliğin istemci kimliği olarak ayarlayın. Bu ayar yapılmamışsa, çalışma zamanı önce AZURE_CLIENT_ID, ardından varsayılan kimlik bilgisi zincirini kullanır.

Korumalı alan aracı Python’u yalıtılmış bir oturumda çalıştırır. Değişkenler, importlar ve dosyalar aynı aracı oturumu boyunca araç çağrıları arasında varlığını sürdürebilir. Bir agent oturum kimliği mevcut olmadığında, çalışma zamanı yeni bir korumalı alan oturumu kullanır; böylece birbiriyle ilişkili olmayan yürütmeler durumu paylaşmaz.

Ajan başına devre dışı bırakma

Aracılar, global olarak yapılandırıldığında yalıtılmış yürütmeyi devralır. Belirli bir ajan için çalıştırmayı devre dışı bırakabilir, ajan dosyasında ' ayarını dynamic_sessions_code_interpreterfalse ayarla.

system_tools:
  dynamic_sessions_code_interpreter: false

Özel Python araçları

Uygulamaya özgü mantığa ihtiyacınız olduğunda, çalışma zamanının yerleşik yetenekleri kapsamadığı özel Python araçlarını kullanın. Özel araçlar, fonksiyon uygulaması sürecinde çalışır, sandbox oturumunda değil.

Araç Keşfi

İşlev uygulaması proje kökündeki tools/ klasöre araç dosyaları ekleyin:

tools/
  submit_ticket.py
  lookup_customer.py

Çalışma zamanı, .py içinde dosya adları tools/ ile başlamayan _ dosyalarını bulur. Çalışma zamanı, her dosyadan ilk desteklenen aracı kaydeder. Bulmanın öngörülebilir olmasını sağlamak için dosya başına bir araç kullanın.

Araçları tanımlama

Bir aracı, çalışma zamanı paketindeki @tool ile bir işlevi süsleyerek tanımlayın:

from azure_functions_agents import tool


@tool(name="submit_ticket", description="Create a support ticket with a title and summary.")
async def submit_ticket(title: str, summary: str) -> str:
    return f"Created ticket for {title}: {summary}"

Daha zengin parametre açıklamaları ve doğrulama için araç şeması olarak bir Pydantic modeli kullanın:

from pydantic import BaseModel, Field
from azure_functions_agents import tool


class LookupCustomerParams(BaseModel):
    customer_id: str = Field(description="Customer identifier from the CRM system.")


@tool(schema=LookupCustomerParams, description="Look up customer details by customer ID.")
async def lookup_customer(params: LookupCustomerParams) -> str:
    return f"Customer details for {params.customer_id}"

Ayrıca dekoratör olmadan düz bir Python işlevi tanımlayabilirsiniz. Çalışma zamanı, dosyada bulduğu ilk düz işlevi sarmalar, araç adı olarak işlev adını ve araç açıklaması olarak docstring'i kullanır.

def summarize_order(order_id: str) -> str:
    """Summarize an order by order ID."""
    return f"Summary for order {order_id}"

Araç adları, açıklamalar, tür ipuçları ve Pydantik alan açıklamaları modelin aracın ne zaman ve nasıl çağrıleceğine karar vermesine yardımcı olur. Azure İşlevleri uygulamasındaki diğer Python kodlarda yaptığınız gibi özel araçlar tarafından kullanılan paket bağımlılıklarını requirements.txt ekleyin.

Ajan başına filtreleme araçları

Aracılar, keşfedilen özel araçları varsayılan olarak devralır. Belirli bir aracı bunları kullanmadığında aracı dosyasındaki özel araçları devre dışı bırakın veya hariç tutun:

tools: false

tools:
  exclude:
    - submit_ticket

Model sağlayıcı yapılandırması

Çalışma zamanı, Azure OpenAI, Azure Yapay Zeka Atölyesi ve OpenAI dahil olmak üzere bu model sağlayıcılarını destekler.

Sağlayıcı seçimi

Bir sohbet istemcisi oluşturmak için çalışma zamanı için en az bir sağlayıcı sinyalini yapılandırmanız gerekir. Sağlayıcıyı açıkça ayarla AZURE_FUNCTIONS_AGENTS_PROVIDER ayarlayabilir veya çalışma zamanının diğer uygulama ayarlarınızdan sağlayıcıyı çıkarmasına izin verebilirsiniz.

Bu sağlayıcı ayarlarını kullanın:

Sağlayıcı	`AZURE_FUNCTIONS_AGENTS_PROVIDER` Değer	Gerekli ayarlar	İsteğe bağlı ayarlar	Model ayarı davranışı
Azure Yapay Zeka Atölyesi	`foundry`	`FOUNDRY_PROJECT_ENDPOINT`	`AZURE_CLIENT_ID` Kullanıcı tarafından atanan yönetilen bir kimlik istediğinizde	`FOUNDRY_MODEL` Foundry projesinin kullanması gereken model dağıtım adını seçin.
Azure OpenAI	`azure_openai`	`AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_DEPLOYMENT`	`AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_API_VERSION`, `AZURE_CLIENT_ID` kullanıcı tarafından atanan yönetilen bir kimlik istediğinizde	Azure OpenAI dağıtım adı olarak ayarlandı`AZURE_OPENAI_DEPLOYMENT`.
OpenAI	`openai`	`OPENAI_API_KEY`	Hiçbiri	`AZURE_FUNCTIONS_AGENTS_MODEL` Agent veya çalışma zamanı yapılandırmasında bir modeli geçirmediğinizde OpenAI model adını ayarlayın.

Ayarlamadığınızda AZURE_FUNCTIONS_AGENTS_PROVIDER, çalışma zamanı sağlayıcıyı şu sırayla otomatik olarak algılar:

AZURE_OPENAI_ENDPOINTAzure OpenAI'yi seçer.
FOUNDRY_PROJECT_ENDPOINTAzure Yapay Zeka Atölyesi'yi seçer.
OPENAI_API_KEY OpenAI'yi seçiyor.

Otomatik algılamaya güvendiğinizde, sağlayıcıyı tanımlayan sağlayıcıya özgü ayarın sağlayıcının gerekli model ayarı ile birlikte olması gerekir. Örneğin, FOUNDRY_PROJECT_ENDPOINT hâlâ gereklidir FOUNDRY_MODELve AZURE_OPENAI_ENDPOINT hâlâ AZURE_OPENAI_DEPLOYMENTgereklidir.

AZURE_FUNCTIONS_AGENTS_MODEL çalışma süresi boyunca bir yedekleme model ayarı. Geçerli değerleri aktif sağlayıcıya bağlıdır:

Azure Yapay Zeka Atölyesi için, Foundry projesinde bulunan bir model dağıtım adı kullanın, örneğin gpt-5.4.
Azure OpenAI için, sadece kasıtlı olarak çalışma zamanı çapında yedek destek istiyorsanız dağıtım adını kullanın. Çoğu uygulamada bunun yerine ayarlayın AZURE_OPENAI_DEPLOYMENT .
OpenAI için, OpenAI API tarafından kabul edilen model adını kullanın, örneğin gpt-4o-mini.

Model önceliği

Model seçimi bu genel öncelik sırasını takip eder:

Ajan veya çalışma zamanı çağrısı tarafından istenen model.
AZURE_OPENAI_DEPLOYMENT veya FOUNDRY_MODEL gibi sağlayıcıya özgü ayarlar.
Model .AZURE_FUNCTIONS_AGENTS_MODEL
Aktif sağlayıcının yerleşik varsayılan modeli.

Yönetilen kimlik yapılandırması

Çalışma zamanı, Microsoft Entra kimlik doğrulamasını destekleyen Azure kaynaklarına bağlanırken yönetilen kimlikler kullanır. AZURE_CLIENT_ID Uygulamanın varsayılan kimlik seçicisi olarak kullanın veya daha ince kontrol için özel ayarlar kullanın:

Çalışma zamanı özelliği	Kimlik ayarı	Geri Dönüş¹
Azure OpenAI model provider²	`AZURE_CLIENT_ID`	`DefaultAzureCredential`
Azure Yapay Zeka Atölyesi model sağlayıcısı	`AZURE_CLIENT_ID`	`DefaultAzureCredential`
Azure Container Apps dinamik oturumlar korumalı alanı	`system_tools.dynamic_sessions_code_interpreter.client_id`	`AZURE_CLIENT_ID`, sonra `DefaultAzureCredential`
Bağlayıcı ad alanında barındırılan MCP sunucuları	`auth.client_id` içindeki sunucu girdisindeki `mcp.json` değeri	`AZURE_CLIENT_ID`, sonra `DefaultAzureCredential`
Blob destekli oturum^{geçmişi 3}	`AzureWebJobsStorage__clientId`	`AZURE_CLIENT_ID`, sonra `DefaultAzureCredential`

Kimlik ayarı yapılandırmadığınızda, çalışma zamanı DefaultAzureCredential kullanır; bu DefaultAzureCredential sistem tarafından atanan yönetilen kimlik Azure'da ve geliştirici kimliğiniz (Azure CLI veya Visual Studio) yerel olarak çözülür.
Azure OpenAI'de bir API anahtarını yapılandırdığınızda (kullanılarakAZURE_OPENAI_API_KEY), model sağlayıcısı yönetilen bir kimlik yerine anahtarı kullanır. Daha fazla bilgi için Azure OpenAI uzantısı for Azure İşlevleri'a bakınız.
Oturum geçmişi, Azure İşlevleri hostuyla aynı varsayılan host depolama kimliği yapılandırmasını kullanır. Blob destekli geçmiş için kimlik tabanlı depolamayı yapılandırmak üzere AzureWebJobsStorage, AzureWebJobsStorage__blobServiceUri ve AzureWebJobsStorage__clientId kullanın. Çalışma zamanı, oturum geçmişi için aracıya özgü ayrı bir kimlik ayarı kullanmaz. Daha fazla bilgi için, Fonksiyonlar geliştirici rehberindeki bağlantıları tanımla .

Yerleşik uç noktalar

Çalışma zamanı, bir ajan ön maddedeki ayarlar üzerinden onay builtin_endpoints verdiğinde isteğe bağlı yerleşik uç noktaları ortaya çıkarır. Bu uç noktalar geliştirme, test ve tanılama için faydalıdır. Birincil üretim uygulama arayüzü olarak tasarlanmamışlar.

Ajanın ön maddesinde yerleşik uç noktaları etkinleştirin:

builtin_endpoints:
  debug_chat_ui: true
  chat_api: true
  mcp: true

Ayar debug_chat_ui: true ayrıca chat ve chatstream API'lerini etkinleştiriyor çünkü arayüz bunlara bağlı. Programatik sohbet erişimi istediğinizde ayıklama arayüzü olmadan tek başına ayarlanır chat_api: true .

Uç nokta rotaları

<AGENT_NAME> rota segmenti, görüntüleme .agent.md alanından değil, name dosya adından kaynaklanır. Örneğin, main.agent.md kullanır /agents/main/.

Yüzey	Rota	Anahtar gereksinimi
Sohbet Arayüzü	`/agents/<AGENT_NAME>/`	Fonksiyon tuşu (tarayıcıda istenir).
HTTP sohbet API'si	`POST /agents/<AGENT_NAME>/chat`	İşlev tuşu.
Akışlı sohbet API'si	`POST /agents/<AGENT_NAME>/chatstream`	İşlev tuşu.
MCP uç noktası	`/runtime/webhooks/mcp`	`mcp_extension` sistem anahtarı.

Anahtarların alınması

Sohbet arayüzünü Azure'da barındırdığınızda, mesaj göndermeden önce bir fonksiyon anahtarı istiyor. Anahtarı HTTP sohbet API'lerini doğrudan çağırırken kullanabilirsiniz.

Uygulamanızın varsayılan fonksiyon anahtarını almak için aşağıdaki az functionapp keys list komutu kullanın:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "functionKeys.default" \
  --output tsv

Bu örnekte, grup ve uygulama isimlerinizle ve <RESOURCE_GROUP> yerine <FUNCTION_APP_NAME> koyun. Başlığa geri dönen anahtarı x-functions-key veya uç noktaya gönderilen HTTP isteğine sorgu code dizisi parametresini ekleyebilirsiniz.

MCP istemcisine bağlanırken, MCP uzantı sistemini aşağıdaki komutla talep edin:

az functionapp keys list \
  --resource-group <RESOURCE_GROUP> \
  --name <FUNCTION_APP_NAME> \
  --query "systemKeys.mcp_extension" \
  --output tsv

MCP uç noktası bu sistem anahtarını gerektirir.

Chat API isteği akışı

Her iki yerleşik sohbet API'si de bir alan içeren JSON gövdesi prompt bekler:

{
  "prompt": "Summarize today's failures."
}

Tek bir JSON yanıtı istediğinizde kullanın POST /agents/<AGENT_NAME>/chat . Yanıt bedeni , session_id, ve responseiçerirtool_calls. Çalışma zamanı, yanıt başlığında x-ms-session-id aynı oturum kimliğini de yankılar.

POST /agents/<AGENT_NAME>/chatstream İstiğiniz zaman kullanın Server-Sent Olayları (SSE). Akış, çözülmüş oturum kimliğini içeren bir session olayla başlar, ardından sıfır veya daha fazla delta, intermediate, tool_start, ve tool_end olaylar gelir ve ya done da errorya da ile sona erer.

Çok turlu bir konuşmaya devam etmek için, sonraki x-ms-session-id veya chat aramalarda istek başlığındaki önceki yanıttan chatstream oturum kimliğini gönderin. Bu başlığı çıkarırsanız, çalışma zamanı otomatik olarak yeni bir oturum oluşturur.

POST /agents/main/chatstream HTTP/1.1
Content-Type: application/json
Accept: text/event-stream
x-ms-session-id: <SESSION_ID_FROM_A_PREVIOUS_RESPONSE>

{"prompt":"Continue the last summary and add blockers."}

Oturumlar ve durum

Çok turlu ajan etkileşimleri oturum geçmişi gerektirir. Çalışma zamanı, ortama göre oturum depolamasını otomatik olarak yönetir:

Ortam	Depolama	Konfigürasyon
Azure	Blob Depolama varsayılan host depolama hesabında (`AzureWebJobsStorage`)	Bağlantı dizisi veya kimlik tabanlı (tercih edilir). Yönetilen kimlik yapılandırması bölümünü inceleyin.
Yerel kalkınma	Yerel ajanların yapılandırma dizininde dosya tabanlı	Konfigürasyon gerekmiyor.

Çalışma zamanı ayrı bir oturum veritabanı gerektirmez. Sandbox tabanlı yürütme ayrıca oturum farkındadır: açık bir oturum kimliği olmadığında, çalışma zamanı taze izole bir sandbox oturumu kullanır, böylece alakasız çağrılar durumu paylaşmaz.

Desteklenen barındırma planları

Azure İşlevleri hosted skills şu Azure İşlevleri hosting planlarını destekler:

Tasarı	Sunucusuz ölçeklendirme	Notlar
Esnek Tüketim	Yes	Sıfıra ölçeklendirme, saniye başına faturalama ve otomatik ölçeklendirme. Çoğu iş yükü için önerilir.
Premium	Yes	Önceden ısıtılmış örnekler, sanal ağ entegrasyonu ve sınırsız yürütme süresi. Tutarlı düşük gecikmeli veya özel ağ gerektiren iş yükleri için kullanın.
Özel (App Service)	No	Manuel veya kural tabanlı ölçeklendirme ile her zaman açık örnekler. App Service planı kapasiteniz varsa kullanın.

Tüm planlar yönetilen kimlik, sanal ağ entegrasyonu ve Application Insights'ı destekler.

Geri Bildirim

Bu sayfayı yararlı buldunuz mu?

Last updated on 2026-08-28