Microsoft Foundry azd Uzantısı 1.0: Ajanı Koddan Yayına

Azure Developer CLI (azd) için Microsoft Foundry uzantı paketi (microsoft.foundry) 1.0 sürümüne ulaştı, genel kullanıma açıldı. azd zaten Azure kaynaklarını sağlıyor, uygulama kodunu dağıtıyordu; Foundry uzantısı bunun üzerine ajan kurulumunu ve yerel test adımlarını ekliyor. Ajan tanımı ile dağıtım yapılandırması böylece kodun yanında, azure.yaml içinde duruyor, aynı dosya hem yerel geliştirmede hem CI/CD hattında kullanılıyor.

Geliştirme akışında ne değişiyor?

Değişen üç şey var:

• Ajan değişiklikleri ile dağıtım değişiklikleri aynı pull request içinde birlikte incelenebiliyor.
• Prompt, araç veya kod üzerinde çalışırken yerel istek ve yanıtlar Agent Inspector üzerinden incelenebiliyor.
• Yerelde kullanılan dağıtım yapılandırması CI/CD tarafında da aynen yeniden kullanılıyor.

Foundry tarafında hosted agent, kendi ajan kodunuzu yönetilen bir bilgi işlem ortamında çalıştıran yapı. Framework ve orkestrasyon mantığı sizin tercihiniz, çalışma zamanını Foundry yönetiyor.

Ön koşullar ve kurulum

Kaynakta sıralanan gereksinimler şöyle:

• Azure Developer CLI 1.37.0 veya üzeri; mevcut kurulum için azd update.
• Güncel bir uv sürümü; bağımsız kurulumlarda uv self update.
• Örnek proje Python 3.13 veya üzerini kullanıyor.
• Bir Azure aboneliği, Foundry izinleri ve seçtiğiniz bölgede model kotası.

Oluşturulan kaynaklar ve model kullanımı Azure tarafında ücretlendirmeye tabi. Oturum açıp paketi kurmak için:

azd auth login
azd ext install microsoft.foundry

Azure CLI (az) ile zaten oturum açtıysanız azd ile de aynı hesabı ve kiracıyı kullanın. Örnekteki DefaultAzureCredential, yerel model çağrıları için bu oturumu kullanabiliyor.

Hosted agent oluşturma ve çalıştırma

1. Projeyi başlatın

Boş bir dizinde temel Python Agent Framework örneğini başlatın. Kurulum sırasında yeni ya da mevcut bir Foundry projesi seçiyorsunuz. Mevcut bir model dağıtımını yeniden kullanmak isterseniz komuta --model-deployment <existing-deployment-name> ekleyin:

azd ai agent init \
--template https://github.com/microsoft-foundry/foundry-samples/blob/main/samples/python/hosted-agents/agent-framework/responses/01-basic/azure.yaml \
--deploy-mode code \
--src.

--src. projeyi bulunduğunuz dizinde başlatır.

2. azure.yaml dosyasını gözden geçirin

azure.yaml, ajanı ve ihtiyaç duyduğu Azure kaynaklarını tanımlar. Dosyayı kodla birlikte tuttuğunuzda dağıtım değişiklikleri de aynı inceleme sürecinden geçer. Ekip arkadaşları ve CI/CD aynı tanımı yeniden kullanır; hedef abonelik, bölge ve kaynak ayarlarını ise her azd ortamı kendisi sağlar. Örnek yapılandırmadan alınan şu parçada model dağıtımı, ajan kaynağı ve çalışma zamanı, bilgi işlem ayrımı ve Foundry projesine bağımlılık görünüyor:

services:
ai-project:
host: azure.ai.project
deployments:
- name: gpt-5.4-mini
model:
format: OpenAI
name: gpt-5.4-mini
version: '2026-03-17'
sku:
name: GlobalStandard
capacity: 10
agent-framework-agent-basic-responses:
host: azure.ai.agent
project: src/agent-framework-agent-basic-responses
codeConfiguration:
runtime: python_3_13
entryPoint: main.py
uses:
- ai-project
container:
resources:
cpu: '0.5'
memory: 1Gi

Başlangıçta altyapı dosyası yazmanız gerekmiyor. Sağlama sürecini özelleştirmek isterseniz düzenlenebilir Bicep veya Terraform dosyalarını dışarı çıkarıp kodla birlikte commit edebilir, azd provision kullanmaya devam edebilirsiniz.

3. Kaynakları sağlayın

azd provision, tanımlanan kaynakları oluşturur, yeniden kullanılan bir projede eksik model dağıtımlarını da ekler. Model yapılandırma adımlarını izleyip Global Standard ya da Data Zone Standard gibi uygun bir çevrim içi dağıtım türü seçin. Seçenekler ve kota aboneliğe ve bölgeye göre değişiyor, karar öncesi dağıtım türlerini karşılaştırmak faydalı.

azd provision

4. Yerelde test edin

azd ai agent run

Bu komut bağımlılıkları kurar ve yerel ajan için Agent Inspector’ı açar. Model çağrıları yine Azure üzerindeki dağıtımınıza gider. Komutu çalışır bırakıp proje dizininde ikinci bir terminalden ajanı çağırabilirsiniz:

azd ai agent invoke --local "Write a haiku about deploying cloud applications."

5. Foundry’ye dağıtın

azd deploy

azd, kaynak kodunuzu uzak derleme için Foundry’ye yükler, yerelde container derlemesine gerek kalmaz. Dağıtım çıktısında playground ve uç nokta bağlantıları yer alır. Dağıtılan ajanı çağırmak için:

azd ai agent invoke "Write a haiku about deploying cloud applications."

Yardımcı komutlar: hosted agent yapılandırma değişikliklerini görmek için azd deploy --preview, günlükleri akıtmak için azd ai agent monitor --follow, kurulum ve izin sorunlarını teşhis etmek için azd ai agent doctor.

Projeyi bir kodlama ajanıyla kurmak

Microsoft Foundry Skill, GitHub Copilot ve Claude Code gibi kodlama ajanlarına proje kurulumu ve yerel test için Foundry’ye özgü iş akışları sağlıyor. Kullandığınız ortama kurup boş bir klasörde şu yönergeyi verebilirsiniz:

Use the Microsoft Foundry Skill to scaffold the basic Python Agent Framework Responses API sample with code deployment. Configure azure.yaml and help me choose the Foundry project, subscription, region, and model deployment. Show me the plan and wait for approval before creating Azure resources. Run and test the agent locally, then stop.

Üretilen projeyi gözden geçirdikten sonra yukarıdaki dağıtım adımlarıyla devam edebilirsiniz.

Kaliteyi ölçmek: Evaluations

Değerlendirme uzantısını kurup dağıtılmış ajan için test verisi ve puanlama ölçütü üretebilirsiniz:

azd ext install azure.ai.evaluations
azd ai eval generate

Ajanın ne yapması gerektiğini tarif edin, ardından Dataset and evaluator ve Turn seçeneklerini belirleyin. Üretilen veri kümesini ve ölçütü inceledikten sonra değerlendirmeyi yapılandırın:

azd ai eval init --name quality

Üretilen veri kümesi ile ölçütü seçip hakem (judge) modelini onaylayın. evals/azure.eval.yaml dosyasını ve azure.yaml içindeki servis referansını gözden geçirin. Değerlendirme varlıklarını kaydedip çalıştırmak için:

azd up
azd ai eval run start --eval quality

Yapılandırmayı ve test varlıklarını kodla birlikte tuttuğunuzda değişiklikleri karşılaştırmak kolaylaşıyor, aynı kontroller CI/CD’de de tekrar kullanılıyor. azd ai agent optimize, yapılandırılmış bir değerlendirmeyi temel çizgi olarak kullanabiliyor; adayları dağıtmadan önce incelemek gerekiyor.

CI/CD ile dağıtımı otomatikleştirmek

azd up projeyi paketler, kaynakları sağlar ve dağıtır. GitHub Actions ya da Azure DevOps hattını yapılandırmadan önce bir kez çalıştırın:

azd up
azd pipeline config

azd pipeline config kimlik doğrulamayı, depo ayarlarını ve incelenip commit edilecek bir iş akışını kurar. Üretilen checkout, oturum açma ve ortam ayarlarını koruyun. Aşağıdaki GitHub Actions parçası yalnızca kurulum ve dağıtım adımlarını gösteriyor, oturum açma adımı dağıtımdan önce gelmeli:

- name: Install azd
uses: Azure/setup-azd@v2
with:
version: 1.37.0
- name: Install Foundry extensions
run: azd ext install microsoft.foundry azure.ai.evaluations
- name: Provision and deploy
run: azd up --no-prompt

Pipeline kimliğine gerekli Azure izinlerini verin, her aşama için ayrı bir azd ortamı kullanın, çalışma zamanı kimlik bilgilerini de pipeline gizli dizilerinde tutun.

CI tarafında değerlendirme çalıştıracaksanız evals/azure.eval.yaml dosyasını ve gizli olmayan gerekli varlıkları commit edin, pipeline’a referans verilen veri kümeleri ve değerlendiricilere erişim tanıyın. Dağıtımdan sonra azd ai eval run start --eval quality --no-prompt komutunu çalıştırın. Eşik tabanlı kalite kapıları ve tam iş akışları için CI/CD rehberine bakabilirsiniz.

Demo ortamını temizlemek

Bu denemeler için yeni bir Foundry projesi oluşturduysanız azd down projenin kaynak grubunu ve içindeki her şeyi siler. Onaylamadan önce silinecekleri mutlaka gözden geçirin:

azd down

Mevcut bir projeyi yeniden kullandıysanız azd down projeyi ve hosted agent dahil kaynaklarını yerinde bırakır. İstemediğiniz kaynakları ayrıca kaldırmak için hızlı başlangıçtaki temizlik yönergelerini izleyin.

Başlangıç ve güncelleme

Uçtan uca anlatım için hosted agent hızlı başlangıcını takip edebilirsiniz. Mevcut bir kurulumu güncellemek içinse azd ext upgrade microsoft.foundry komutu yeterli. Geri bildirim ve istekler Azure Developer CLI deposu üzerinden iletiliyor.

Kaynaklar ve İleri Okuma

• Microsoft Foundry extension for Azure Developer CLI is generally available (John Miller, Microsoft Foundry Blog)
• Hosted agent hızlı başlangıcı (azd)
• Foundry hosted agents kavramları
• Hosted agent izinleri
• CLI ile altyapı dosyalarını özelleştirme
• Azd AI Agent uzantısı ile Foundry ajanlarını Azure’a taşımak
• Foundry Hosted Agents ile Microsoft Agent Framework’ü prod’a taşımak