Azure İşlevleri’da Python için aracı bağlamaları

Python fonksiyon uygulamaları için ajan bağlamaları, mevcut fonksiyonlara ajanik davranışlar eklemenize olanak tanır. Fonksiyon çalıştığında, uzantı Markdown yönergelerinden bir Agent oluşturur ve bunu işleyicinize türlü parametre olarak enjekte eder. Kodunuz, ajanı ne zaman ve nasıl çağıracağınızı deterministik uygulama mantığınızla birlikte belirler.

Important

Python fonksiyon uygulamaları için ajan bağlamaları şu anda önizleme aşamasında. Özellikler, paket isimleri ve yapılandırma genel erişilebilirlikten önce değişebilir.

Ajan bağlamalarını, Azure İşlevleri barındırılan beceriler ve Model Context Protocol (MCP) araçları gibi diğer yapay zeka ile ilgili özelliklerle karşılaştırmak için Azure İşlevleri için AI entegrasyon seçeneklerine bakınız.

Ajan bağlama, bir Python fonksiyonuna tam oluşturulmuş Agent bir nesne sağlayan uzantıya ait bir giriş bağlamasıdır. Uzantı, ajan talimatlarını bir .agent.md dosyadan ham metin olarak okur. Uygulama kodunuz istemci ve sağlayıcıya özgü araç yapılandırmasını korurken, fonksiyon uygulaması projesi dosya tabanlı ajan becerilerini ve uzak MCP sunucularını keşfedebilir.

Ajan bağlama mimarisi, farklı SDK'lardan ajan nesnelerini sağlayıcıya özgü uzantı paketleri aracılığıyla destekler. Microsoft Agent Framework, mevcut önizlemede desteklenen tek ajan SDK'dır. Kullanmak için paketi azurefunctions-agents-extensions-agent-framework yükleyin.

Ajan bağlayıcıları ne zaman kullanılır

Bir Azure Fonksiyonu iş akışının bir kısmı için ajanik gerekçeye ihtiyaç duyduğunda ajan bağlarını kullanın, ancak uygulamanız tetikleyici, doğrulama, dallanma, hata işleme ve yanıt üzerinde kontrol sahibi olmalıdır. Yaygın senaryolar şunlardır:

  • Bir HTTP isteği değerlendirin. Bir siparişi deterministik kodla doğrulayın, bir ajandan yerine getirme riskini değerlendirmesini istein ve sonucu HTTP yanıtını oluşturmak için kullanın.
  • Etkinlikleri zenginleştirin veya sınıflandırın. Bir kuyruk mesajı, Event Grid olayı veya başka bir tetikleyici yükü alın ve fonksiyonunuz sonucu yazmadan önce veriyi sınıflandırmak, özetlemek veya zenginleştirmek için bir ajan kullanın.
  • Dayanıklı bir iş akışına mantık ekleyin. Replay-safe context.call_agent() API üzerinden bir Dayanıklı İşlevler orkestratöründen bir ajan çağırın, ardından sonucu sonraki düzenleme adımlarında kullanın.

Ajan bağlamaları, fonksiyonun deterministik kodu koordinatör olarak kalması gerektiğinde iyi bir uyumdur. Ajan sınırlı bir akıl yürütme görevi yapar ve kontrolü yöneticiye veya orkestrasyona geri verir.

Neden ajan bağlayıcıları kullanılır?

Birçok üretim iş akışı, deterministik olması gereken adımları model akıl yürütmesinden faydalanan adımlarla birleştirir. Ajan bağlamaları, bu hibrit iş akışları için aşağıdaki avantajları sağlar:

  • Mevcut fonksiyonlara ajanik davranış ekleyin. HTTP-, zamanlayıcı-, kuyruk-, Event Grid-, Service Bus- ve diğer tetiklenen fonksiyonlardan ajan akıl yürütmeyi kullanın.
  • Ajan çağrısını kod içinde güvenle denetleyin. Ajanı ne zaman çağıracağınıza karar verin, yanıtını inceleyin ve fonksiyon çıktısını belirleyin. Bu uzantı, başarı, başarısızlık veya iptalden sonra çağrıya ait kaynakları kapatır.
  • Ajan kurulum kodunu azaltın. Yapılandırılmış Agent öğesini, her çağrı için oluşturup bağlamak yerine türlenmiş bir işleyici parametresi olarak alın.
  • Komutları çalışma zamanı yapılandırmasından ayırın. Doğal dil komutlarını bir .agent.md dosyada depolayın ve istemci ile sağlayıcıya özgü araçları açıkça Python'da yapılandırın.
  • Paylaşılan ajan yeteneklerini kullanın. Uzantı, uygulama kökünden dosya tabanlı ajan becerilerini ve HTTP tabanlı MCP sunucularını keşfeder ve bunları her ajan bağlamasına sunar.
  • Dayanıklı orkestrasyonlardan temsilcileri çağırın. Uzantı, ajan işini gizli bir etkinlik içinde yürütür; böylece orkestrasyonun yeniden oynatılması deterministik kalır.
  • Yerel olarak tanıdık araçlarla hata ayıkla. Uygulamayı diğer Python fonksiyon uygulamaları gibi yerel olarak çalıştırın ve hata ayıklayın. Kesinti noktaları belirleyip hem deterministik fonksiyon mantığını hem de ajanı çağıran kodu adım adım atabilirsiniz.

Bir ajan bağlaması nasıl çalışır

AgentFunctionApp, azure.functions.FunctionApp öğesini genişletir, bu nedenle FunctionApp ile aynı yeteneklere sahiptir. markdown_agent dekoratörü bir fonksiyona ajan girişi ekler.

Her ajan bağlaması için, uzantı aşağıdaki işlemleri gerçekleştirir:

  1. İstenen .agent.md dosyasını, işlev uygulamasının kök dizininden veya agents/ dizininden bulur.
  2. Dosyanın tamamını ham UTF-8 komutları olarak yükler.
  3. Komutları, yapılandırılmış istemci fabrikası, açıkça yapılandırılan sağlayıcı araçları ve keşfedilen ajan becerileri ile MCP sunucularıyla birleştirir.
  4. Yeni bir Agent oluşturur ve çağrıya ait kaynakları açar.
  5. Agent öğesini işleyici parametresine enjekte eder.
  6. Yürütme sona erdiğinde çağrının sahip olduğu kaynakları kapatır.

Bu uzantı, sağlayıcı keşfi ve derlenmiş bağlama tanımlarını önbellekleyebilir. Canlı çağrı kaynaklarını fonksiyon çağrıları arasında önbellek veya yeniden kullanmaz.

Bir ajan bağlaması tanımlayın

Aşağıdaki örnek, HTTP tarafından tetiklenen bir işleve Agent eklemek için şu anda desteklenen Microsoft Agent Framework sağlayıcısını kullanır. Fonksiyon görevi kodda oluşturur, ajanı çağırır ve ajan yanıtını döndürür:

import azure.functions as func
from agent_framework import Agent
from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.function_name(name="ProcessOrder")
@app.route(route="orders/{orderId}", methods=["POST"])
@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    task = (
        "Validate the order and return fulfillment guidance for "
        f"{req.route_params['orderId']}."
    )
    response = await order_agent.run(task)
    return func.HttpResponse(response.text)

Değer, arg_name enjekte edilen handler parametresiyle eşleşmelidir. Aynı işlevin içine birden fazla ajan enjekte etmek için markdown_agent dekoratörlerini üst üste kullanın ve her ajan bağlaması için benzersiz bir arg_name ile işleyici parametresi kullanın. Değer, agent_name talimatlar dosyasını tanımlar. Bu örnekte, order-fulfillment aşağıdaki konumlardan tam olarak birine çözümlenmelidir:

<app_root>/order-fulfillment.agent.md
<app_root>/agents/order-fulfillment.agent.md

Her iki dosya da varsa, tanım belirsizdir ve uygulama başlatma başarısız olur. Ajan isimleri mutlak yollar, yol ayırıcıları veya geçiş bileşenleri içeremez. Uygulama kökü dışında çözümlenen dosyalara izin verilmez.

Ajan istemcisi ve araçları yapılandırmak

AgentFunctionApp oluştururken, sıfır bağımsız değişkenli bir client_factory yapılandırın. Fabrika, sağlayıcı paketiyle desteklenen yeni bir istemci gönderiyor. Ayrıca uygulama düzeyinde, Microsoft Agent Framework araç nesnelerini veya Python çağrılabilirlerini tools parametresi aracılığıyla da iletebilirsiniz. Bağlama, farklı davranışlar gerektirdiğinde uygulama düzeyindeki istemci fabrikasını ve araçları geçersiz kılabilir.

Örneğin, aşağıdaki HTTP tarafından tetiklenen işlev, order_agent öğesini yalnızca lookup_inventory için bir araç olarak kullanılabilir hâle getiren bir aracı bağlaması kullanır:

def lookup_inventory(product_id: str) -> str:
    """Return the available inventory for a product."""
    return f"Inventory is available for {product_id}."


@app.markdown_agent(
    arg_name="order_agent",
    agent_name="order-fulfillment",
    tools=[lookup_inventory],
)
async def process_order(
    req: func.HttpRequest,
    order_agent: Agent,
) -> func.HttpResponse:
    response = await order_agent.run(req.get_body().decode())
    return func.HttpResponse(response.text)

Ajan istemcisini ve araçlarını yapılandırırken şu hususları aklınızda bulundurun:

  • Temel ajan uzantısı sağlayıcıdan bağımsızdır. Bir sağlayıcı paketi, belirli bir ajan SDK'sını entegre eder ve desteklenen istemci ile ajan türlerini tanımlar.
  • Şu anda desteklenen Microsoft Agent Framework sağlayıcı paketi, uygulamanız için bir model sağlayıcı seçmez veya yapılandırmaz. İstemci fabrikanız, ajanın hangi desteklenen Microsoft Agent Framework sohbet istemcisi ve modelini kullandığını belirler.
  • Uzantı, .agent.md dosyasının tamamını ajan yönergeleri olarak yapılandırılmış sağlayıcıya iletir. Dosyadan model ayarlarını, araçları, YAML ön maddesini veya diğer çalışma zamanı yapılandırmalarını ayrıştırmaz.

Paylaşılan ajan becerileri ve MCP sunucuları

Uzantı, uygulama kökünden paylaşılan ajan yeteneklerini otomatik olarak keşfeder:

Capability Location Davranış
Temsilci becerileri skills/<skill-name>/SKILL.md veya Skills/<skill-name>/SKILL.md Sağlayıcı paketi, dosya tabanlı ajan becerisini yükler ve doğrular.
Uzak MCP sunucuları mcp.json Uzantı, desteklenen HTTP veya akışlanabilir HTTP sunucularını ve isteğe bağlı araç allowlist'lerini yapılandırıyor.
Sağlayıcı araçları Uygulama veya bağlama yapılandırması Microsoft Agent Framework araç nesneleri veya Python çağrılabilirleri, keşfedilmek yerine açıkça sağlanır.

Paylaşılan ajan yeteneklerini kullanırken şu hususları aklınızda bulundurun:

  • Fonksiyon uygulamasındaki her ajan bağlaması, keşfedilen tüm ajan becerilerini ve MCP sunucularını alır.
  • Dosya tabanlı ajan becerileri, bir ajanın yükleyebileceği yeteneklerdir. Bunlar, ayrı bir yürütme modeli kullanan Azure İşlevleri barındırılan beceriler değildir.
  • Ajan uzantının mevcut önizlemesi, bir uygulama veya bireysel bağlama için bir yetenek alt kümesi seçilmesini desteklemiyor.
  • Ajan becerileri ve MCP araçları ayrıcalıklı işlemler yapabilir. Sadece uygulamadaki her ajanın kullanabileceği yetenekleri yerleştirin ve ajanlar farklı yetenek sınırları gerektirdiğinde ayrı fonksiyon uygulamaları kullanın.

MCP yapılandırması, URL'ler, başlıklar, kimlik doğrulama alanları ve istemci kimlikleri için ortam değişkenlerine referans verebilir. Her çağrı için referanslar, uzantı sunucuya bağlanmadan önce çözülür. Sırları doğrudan kaynak kontrolündeki mcp.json bir dosyada saklamayın.

Yerel süreç ve standart giriş/çıkış (stdio) MCP sunucuları desteklenmiyor. MCP desteği isteğe bağlı bir bağımlılıktır ve normal paket ithalatları yüklenmediğinde güvende kalır.

Ajan bağlayıcılarını Dayanıklı İşlevler ile kullanın

Ajan bağlamaları, isteğe bağlı Dayanıklı İşlevler entegrasyonu aracılığıyla hibrit, uzun süreli iş akışlarını destekler. Bir eşzamanlı üreteç orkestratörü context.call_agent() çağırır ve elde edilen görevi döndürür:

from typing import Any

from azurefunctions.agents.extensions.agent_framework import AgentFunctionApp


app = AgentFunctionApp(client_factory=create_chat_client)


@app.orchestration_trigger(context_name="context")
def order_orchestrator(context: Any):
    assessment = yield context.call_agent(
        "order-fulfillment",
        {"order": context.get_input()},
    )
    return assessment

call_agent() Ajanı tanımını çözen ve tüm model, dosya sistemi, kimlik bilgileri, araç ve ağ işlemlerini gerçekleştiren gizli bir faaliyet planlar. Orkestratör yalnızca deterministik, JSON-serileştirilebilir bir şema-v1 isteği oluşturur. Sonuç olarak, orkestrasyon tekrarı belirsiz ajan işlemlerini tekrarlamaz.

Dayanıklı ajan çağrıları, AgentFunctionApp tarafından yapılandırılan sağlayıcıyı ve paylaşılan yetenekleri kullanır. Giriş ve çıkışlar JSON serileştirilebilir olmalıdır.

Dayanıklı İşlevler desteği isteğe bağlıdır. Kullanmayan uygulamalar ise Dayanıklı İşlevler'ı yüklemek veya içe aktarmak zorunda değildir. context.call_agent() ve orchestration_trigger kullanmak için, desteklenen sağlayıcı paketini Durable ek bağımlılığıyla birlikte yükleyin.

Proje dosyaları

Ajan destekli uygulama, ajan uzantısı bağımlılıkları ve bir veya daha fazla komut dosyası içeren standart bir Python v2 fonksiyon uygulamasıdır:

Dosya veya klasör Purpose
function_app.py AgentFunctionApp, standart Functions tetikleyicilerini, ajan bağlamalarını, istemci fabrikalarını ve açıkça yapılandırılmış sağlayıcı araçlarını tanımlar.
host.json Azure İşlevleri ana bilgisayarı yapılandırılır.
requirements.txt Desteklenen bir ajan sağlayıcı paketi ve SDK'ya özgü herhangi bir istemci paketi içerir. Geçerli önizleme için azurefunctions-agents-extensions-agent-framework kullanın. Isteğe bağlı ekstralar Dayanıklı İşlevler ve MCP desteğini sağlar.
*.agent.md veya agents/*.agent.md Bir ajan için ham UTF-8 talimatları içerir. Her referans verilen isim tam olarak tek bir dosyaya dönüşmelidir.
skills/ veya Skills/ (İsteğe bağlı) Tüm ajan bağlamaları tarafından paylaşılan dosya tabanlı ajan becerileri içerir.
mcp.json (İsteğe bağlı) Tüm ajan bağlamaları tarafından paylaşılan uzak HTTP tabanlı MCP sunucularını tanımlar.

Standart Python proje yapısı için Azure İşlevleri Python geliştirici rehberine bakınız.

Doğrulama ve tanılama

Bu uzantı, bağlama derlemesinden önce veya sırasında ajan tanımlarını doğrular, böylece yapılandırma sorunları eyleme alınabilir hatalarla başarısız olur. Doğrulama şunları kapsar:

  • Eksik veya belirsiz .agent.md dosyalar.
  • Eksik veya uyumsuz enjekte edilmiş parametre dahil olmak üzere geçersiz handler imzaları.
  • Desteklenmeyen sağlayıcı seçenekleri veya yetenekleri.
  • Geçersiz yetenek dizinleri ve yanlış oluşturulmuş MCP yapılandırması.
  • Desteklenmeyen MCP taşımaları ve eksik ortam değerleri.
  • Geçersiz Durable yükleri veya JSON olarak serileştirilemeyen değerler.

Mevcutsa uzantı, korelasyon ve tanılamayı desteklemek için Azure Function adını, çağrı kimliğini ve Durable örnek kimliğini sağlayıcı sınırında korur.

  • Last updated on