Öğretici: LangGraph veya Foundry Agent Service (Python) ile Azure App Service'te aracı web uygulaması oluşturma

Bu öğreticide, mevcut bir veri temelli FastAPI CRUD uygulamasına aracılık özelliğinin nasıl ekleneceği gösterilmektedir. Bunu iki farklı yaklaşım kullanarak yapar: LangGraph ve Foundry Agent Service.

Web uygulamanızın alışveriş, otel rezervasyonu veya veri yönetimi gibi kullanışlı özellikleri zaten varsa, bu işlevleri bir eklentide (LangGraph için) veya openAPI uç noktası olarak (Foundry Agent Service için) sarmalayarak web uygulamanıza aracı işlevselliği eklemek oldukça kolaydır. Bu öğreticide basit bir to-do listesi uygulamasıyla başlayacaksınız. Sonunda, App Service uygulamasında bir aracıyla görev oluşturabilecek, güncelleştirebilecek ve yönetebileceksiniz.

LangGraph

Foundry Agent Hizmeti

Hem LangGraph hem de Foundry Agent Service, yapay zeka destekli özelliklerle aracı web uygulamaları oluşturmanıza olanak tanır. LangGraph, Microsoft Agent Framework'e benzer ve bir SDK'dır. Aşağıdaki tabloda dikkat edilmesi gereken bazı noktalar ve dengeler gösterilmektedir:

Değerlendirme	LangGraph veya Microsoft Agent Framework	Döküm Acentası Hizmeti
Performance	Hızlı (yerel olarak çalışır)	Daha yavaş (yönetilen, uzak hizmet)
Gelişme	Tam kod, maksimum denetim	Düşük kod, hızlı tümleştirme
Testing	Kodda manuel/birim testleri	Hızlı test için yerleşik oyun alanı
Ölçeklenebilirlik	Uygulama ile yönetilen	Azure tarafından yönetilen, otomatik ölçeklendirilen
Güvenlik korumaları	Özel uygulama gerekiyor	Yerleşik içerik güvenliği ve moderasyonu
Kimlik	Özel uygulama gerekiyor	Yerleşik ajan kimliği ve kimlik doğrulaması
Enterprise	Özel tümleştirme gerekiyor	Dahili Microsoft 365/Teams dağıtımı ve Microsoft 365 entegre araç çağrıları.

Bu eğitimde şunları öğreniyorsunuz:

• Mevcut uygulama işlevselliğini LangGraph eklentisine dönüştürün.
• Eklentiyi bir LangGraph aracısına ekleyin ve bir web uygulamasında kullanın.
• Mevcut uygulama işlevselliğini Foundry Agent Service için OpenAPI uç noktasına dönüştürün.
• Web uygulamasında bir Foundry aracısını çağırma.
• Yönetilen kimlik bağlantısı için gerekli izinleri atayın.

Önkoşullar

• Etkin aboneliği olan bir Azure hesabı - Ücretsiz bir hesap oluşturun.
• GitHub Codespaces kullanmak için GitHub hesabı - GitHub Codespaces hakkında daha fazla bilgi edinin.

Codespaces ile örneği açma

Başlamanın en kolay yolu, gerekli tüm araçların önceden yüklenmiş olduğu eksiksiz bir geliştirme ortamı sağlayan GitHub Codespaces'ı kullanmaktır.

1. konumundaki GitHub deposuna https://github.com/Azure-Samples/app-service-agentic-langgraph-foundry-pythongidin.

2. Kod düğmesini seçin, Codespaces sekmesini ve ardından Main üzerinde kod alanı oluştur'u seçin.

3. Codespace'ınızın başlatılması için birkaç dakika bekleyin. Hazır olduğunuzda, tarayıcınızda tam olarak yapılandırılmış bir geliştirme ortamı görürsünüz.

4. Uygulamayı yerel olarak çalıştırın:

   python3 -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn src.app:app --host 0.0.0.0 --port 3000
   

5. Uygulamanızın 3000 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin ve birkaç görev ekleyin.

   Aracılar tam olarak yapılandırılmadıkları için henüz çalışmıyor. Bunları daha sonra yapılandıracaksınız.

Aracı kodunu gözden geçirme

Her iki yaklaşım da, aracının uygulama başlangıcında başlatıldığı ve POST istekleriyle kullanıcı iletilerine yanıt verdiği aynı uygulama desenini kullanır.

LangGraph

LangGraphTaskAgent, src/agents/langgraph_task_agent.py içindeki yapıcıda başlatılır. Başlatma kodu aşağıdakileri yapar:

• Ortam değişkenlerini kullanarak AzureChatOpenAI istemcisini yapılandırılır.
• Önceden oluşturulmuş, bellek ve görev yönetimi için bir CRUD araç setiyle donatılmış ReAct aracını oluşturur (bkz. LangGraph başlangıç kılavuzu).

# Initialize Azure OpenAI client
credential = DefaultAzureCredential()
azure_ad_token_provider = get_bearer_token_provider(
    credential, "https://cognitiveservices.azure.com/.default"
)

self.llm = AzureChatOpenAI(
    azure_endpoint=endpoint,
    azure_deployment=deployment_name,
    azure_ad_token_provider=azure_ad_token_provider,
    api_version="2024-10-21"
)

# Define tools
tools = [
    self._create_task_tool(),
    self._get_tasks_tool(),
    self._get_task_tool(),
    self._update_task_tool(),
    self._delete_task_tool()
]

# Create the agent
self.agent = create_react_agent(self.llm, tools, checkpointer=self.memory)
print("LangGraph Task Agent initialized successfully")

Kullanıcı iletileri işlenirken, kullanıcının iletisi ve konuşma sürekliliği için iş parçacığı kimliği ile ainvoke() kullanılarak aracı çağrılır.

result = await self.agent.ainvoke(
    {"messages": [("user", message)]},
    config=config
)

Foundry Agent Hizmeti

FoundryTaskAgent, src/agents/foundry_task_agent.py oluşturucusunda başlatılır. Başlatma kodu aşağıdakileri yapar:

• Azure kimlik bilgilerini kullanarak bir AIProjectClient oluşturur.
• Proje istemcisinden bir OpenAI istemcisi alır.
• Foundry'den aracıyı ismiyle alır.
• Oturum için yeni bir konuşma oluşturur.

# Create the project client using Azure credentials
self.project_client = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential()
)

# Get the OpenAI client for conversation operations
self.openai_client = self.project_client.get_openai_client()

# Find the existing agent by name
self.agent = self.project_client.agents.get(agent_name)

if not self.agent:
    print(f"Agent with name '{agent_name}' not found in project.")
    return
            
# Create a conversation for this session
conversation = self.openai_client.conversations.create()
self.conversation_id = conversation.id
print("Foundry agent initialized successfully")

Aracıyı genellikle Foundry portalında oluşturacağınız için bu başlatma kodu aracı için herhangi bir işlev tanımlamaz. Örnek senaryonun bir parçası olarak, App Service uygulamasını Foundry Agent Service'te (Python) araç olarak ekleme bölümünde gösterilen OpenAPI desenini de izler ve CRUD işlevselliğini OpenAPI uç noktası olarak kullanılabilir hale getirir. Bu, onu daha sonra aracıya çağrılabilir bir araç olarak eklemenizi sağlar.

OpenAPI kodu src/routes/api.py içinde tanımlanır. Örneğin, "GET /tasks" yoluoperation_id gerektirdiği şekilde özel bir parametre tanımlar ve description aracının API'yi nasıl çağıracaklarını belirlemesine yardımcı olur:

@router.get(
    "/tasks",
    response_model=List[TaskItem],
    operation_id="getAllTasks",
    description="Retrieve all tasks in the task list."
)
async def get_all_tasks():
    """Get all tasks"""
    try:
        tasks = await task_service.get_all_tasks()
        return tasks
    except Exception as e:
        print(f"Error getting tasks: {e}")
        import traceback
        traceback.print_exc()
        raise HTTPException(status_code=500, detail=f"Failed to get tasks: {str(e)}")

Kullanıcı iletileri işlenirken, kullanıcının iletisi konuşmaya eklenir ve aracı referansı ile responses.create() çağrılarak aracı başlatılır.

# Add user message to the conversation
self.openai_client.conversations.items.create(
    conversation_id=self.conversation_id,
    items=[{"type": "message", "role": "user", "content": message}],
)

# Create response using the agent
response = self.openai_client.responses.create(
    conversation=self.conversation_id,
    extra_body={"agent": {"name": self.agent.name, "type": "agent_reference"}},
    input="",
)

Örnek uygulamayı dağıtma

Örnek depo, yönetilen kimlikli bir App Service uygulaması oluşturan ve örnek uygulamanızı dağıtan bir Azure Geliştirici CLI (AZD) şablonu içerir.

1. Terminalde Azure Geliştirici CLI'sini kullanarak Azure'da oturum açın:

   azd auth login
   

   Kimlik doğrulama işlemini tamamlamak için yönergeleri izleyin.

2. Azure App Service uygulamasını AZD şablonuyla dağıtın:

   azd up
   

3. İstendiğinde aşağıdaki yanıtları verin:

   Question	Cevap
   Yeni bir ortam adı girin:	Benzersiz bir ad yazın.
   Kullanılacak azure aboneliğini seçin:	Aboneliği seçin.
   Kullanılacak kaynak grubunu seçin:	Yeni kaynak grubu oluştur'u seçin.
   Kaynak grubunun oluşturulacağı konumu seçin:	İsveç Orta seçin.
   Yeni kaynak grubu için bir ad girin:	Enter yazın.

4. AZD çıkışında uygulamanızın URL'sini bulun ve tarayıcıda bu URL'ye gidin. URL, AZD çıkışında şöyle görünür:

    Deploying services (azd deploy)
   
      (✓) Done: Deploying service web
      - Endpoint: <URL>
    

5. Belirtilen yolda otomatik olarak oluşturulan OpenAPI şemasını açın. Bu şemaya daha sonra ihtiyacınız olacak.

   Artık sistem tarafından atanan yönetilen kimliğe sahip bir App Service uygulamanız var.

Microsoft Foundry kaynağını oluşturma ve yapılandırma

LangGraph

1. Dökümhane portalında, en üstteki Yeni Dökümhane radyo düğmesinin etkin olarak ayarlandığından emin olun ve bir proje oluşturun.

2. Seçtiğiniz bir modeli dağıtın (bkz. Microsoft Foundry Hızlı Başlangıcı: Kaynak oluşturma).

3. Model oyun alanının en üstünden model adını kopyalayın.

4. Azure OpenAI uç noktasını almanın en kolay yolu hala klasik portaldandır. Yeni Dökümhane radyo düğmesini, ardından Azure OpenAI'yi seçin ve daha sonra kullanmak üzere Azure OpenAI uç noktası URL'sini kopyalayın.

   

Foundry Agent Hizmeti

1. Dökümhane portalında, en üstteki Yeni Dökümhane radyo düğmesinin etkin olarak ayarlandığından emin olun ve bir proje oluşturun.

2. Giriş sayfasında, daha sonra kullanmak için Project uç noktasını kopyalayın.

3. Başlangıç oluştur>Aracı oluştur'yu seçin ve istemi izleyin.

4. Yeni aracının oyun alanında, web uygulamanızı çağırmak için Araçlar>Ekle>Özel>OpenAPI aracı>Oluştur seçeneklerini sırasıyla seçerek bir OpenAPI aracı oluşturun. Kurulum bölmesinde, OpenAPI belirtim aracıyla bir eylem ekleyin. Dağıtılan web uygulamasından ve anonim kimlik doğrulamasından edindiğiniz OpenAPI şemasını kullanın. Ayrıntılı adımlar için bkz. OpenAPI belirtim aracını kullanma.

   Uygulama kodunuz, aracının ihtiyaç duyduğu sunucunun url ve operationId öğelerini içerecek şekilde zaten yapılandırılmıştır. Daha fazla bilgi için bkz. OpenAPI Belirtimine Bağlanma.

5. Kaydet'i seçtiğinizden emin olun.

6. Oyun alanında dene'yi seçin ve Foundry aracınızı "Tüm görevleri göster" ve "Lütfen bir görev ekleyin" gibi istemlerle test edin.

   Geçerli bir yanıt alırsanız aracı, dağıtılan web uygulamanızda OpenAPI uç noktasına araç çağrıları yapıyordur.

Gerekli izinleri atayın

LangGraph

1. Yeni Foundry portalının üst menüsünden İşlet'i ve ardından Yönetim'i seçin. Foundry projenizin satırında iki bağlantı görmeniz gerekir. Ad sütunundaki kaynak Foundry projesi kaynağı, Üst kaynak sütunundaki kaynak ise Foundry kaynağıdır.

   

2. Ana kaynakta Döküm Kaynağı'nı ve ardından Azure portalında bu kaynağı yönetin seçin. Azure portalından, dağıtılan web uygulamasına kaynak için rol tabanlı erişim atayabilirsiniz.

3. App Service uygulamasının yönetilen kimliği için aşağıdaki rolü ekleyin:

   Hedef kaynak	Gerekli rol	Için gereklidir
   Döküm	Bilişsel Hizmetler OpenAI Kullanıcısı	Microsoft Agent Framework'teki sohbet tamamlama hizmeti.

   Yönergeler için bkz. Azure portalını kullanarak Azure rolleri atama.

Foundry Agent Hizmeti

1. Yeni Foundry portalının üst menüsünden İşlet'i ve ardından Yönetim'i seçin. Foundry projenizin satırında iki bağlantı görmeniz gerekir. Ad sütunundaki kaynak Foundry projesi kaynağı, Üst kaynak sütunundaki kaynak ise Foundry kaynağıdır.

   

2. Ad sütununda Foundry proje kaynağını seçin ve ardından Azure portalında bu kaynağı yönetin. Azure portalından, dağıtılan web uygulamasına kaynak için rol tabanlı erişim atayabilirsiniz.

3. App Service uygulamasının yönetilen kimliği için aşağıdaki rolü ekleyin:

   Hedef kaynak	Gerekli rol	Için gereklidir
   Dökümhane Projesi	Dökümhane Kullanıcısı	Foundry temsilcisini okuma ve arama.

   Yönergeler için bkz. Azure portalını kullanarak Azure rolleri atama.

Örnek uygulamanızda bağlantı değişkenlerini yapılandırma

1. .env dosyasını açın. Daha önce Foundry portalından kopyaladığınız değerleri kullanarak aşağıdaki değişkenleri yapılandırın:

   LangGraph

   Variable	Description
   AZURE_OPENAI_ENDPOINT	Azure OpenAI uç noktası (klasik Foundry portalından kopyalanır).
   AZURE_OPENAI_DEPLOYMENT_NAME	Dağıtımdaki model adı (yeni Foundry portalındaki model oyun alanından kopyalanır).

   Uyarı

   Öğreticiyi basit tutmak için bu değişkenleri App Service'teki uygulama ayarlarıyla üzerine yazmak yerine .env içinde kullanacaksınız.

   Foundry Agent Hizmeti

   Variable	Description
   AZURE_AI_FOUNDRY_PROJECT_ENDPOINT	Yeni Foundry portalından Microsoft Foundry proje uç noktası.
   AZURE_AI_FOUNDRY_AGENT_NAME	Aracı adı (Dökümhane portalındaki aracı oyun alanından).

   Uyarı

   Öğreticiyi basit tutmak için bu değişkenleri App Service'teki uygulama ayarlarıyla üzerine yazmak yerine .env içinde kullanacaksınız.

2. Azure CLI ile Azure'da oturum açın:

   az login
   

   Bu, örnek koddaki Azure Identity istemci kitaplığının oturum açmış kullanıcı için bir kimlik doğrulama belirteci almasını sağlar. Bu kullanıcı için gerekli rolü daha önce eklediğinizi unutmayın.

3. Uygulamayı yerel olarak çalıştırın:

   npm run build
   npm start
   

4. Uygulamanızın 3000 numaralı bağlantı noktasında çalıştığınıgördüğünüzde Tarayıcıda Aç'ı seçin.

5. Sohbet arabirimini denemek için LangGraph Aracısı bağlantısını ve Foundry Agent bağlantısını seçin. Bir yanıt alırsanız, uygulamanız Microsoft Foundry kaynağına başarıyla bağlanıyordur.

6. GitHub Codespace’inize geri dönün ve uygulama değişikliklerinizi dağıtıma alın.

   azd up
   

7. Dağıtılan uygulamaya yeniden gidin ve sohbet aracılarını test edin.

LangGraph

Foundry Agent Hizmeti

Kaynakları temizle

Uygulamayla işiniz bittiğinde, daha fazla maliyet oluşmasını önlemek için App Service kaynaklarını silebilirsiniz:

azd down --purge

AZD şablonu Microsoft Foundry kaynaklarını içermediğinden, isterseniz bunları el ile silmeniz gerekir.

Daha fazla kaynak

• Yapay zekayı Azure App Service uygulamalarınızla tümleştirme
• Foundry Ajan Hizmeti nedir?
• LangGraph - Hızlı Başlangıç
• Python için Azure AI Projeleri istemci kitaplığı