Kodlama aracıları ve betiklerle azd ai kullanın

Important

Bu makalede önizleme olarak işaretlenmiş öğeler şu anda önizleme aşamasındadır. Bu önizleme, hizmet düzeyi sözleşmesi olmadan sağlanır ve Microsoft üretim iş yükleri için bunu önermez. Bazı özellikler desteklenmeyebilir veya kısıtlı özelliklere sahip olabilir. Daha fazla bilgi için bkz. Microsoft Azure Önizlemeleri için Ek Kullanım Koşulları.

azd ai öğesini, insanların terminalde elde ettiğiyle aynı davranış biçimiyle kodlama aracıları ve betiklerde kullanın. Bağımsız bağlam ayarlar, istemleri devre dışı bırakır, JSON çıktısını ayrıştırır ve güvenilir otomasyon için doğrudan ajan uç noktalarını çağırırsınız.

Prerequisites

Microsoft Döküm Becerisi ile başlayın

Kodlama ajanları, azd ai kodlama kurallarını zaten bildiklerinde en verimli şekilde çalışır. Microsoft Foundry Skill, bir kodlama aracısına şu bilgiyi kazandırır: doğru azd ai komutlarını ve Foundry bağlantılarını üretir ve bu makaledeki uygulamaları uygular -- proje bağlamını ayarlama, --no-prompt geçirme ve yapılandırılmış sonuçlar için --output json isteme. Önce kodlama ajanınızı yeteneğe yönlendirin, ardından bu makalenin geri kalanındaki örüntüleri kullanarak ürettiklerini gözden geçirin ve güçlendirin.

Proje bağlamını bir kez ayarlama

, connection, toolboxveya skillgibi routineher kaynak komutunun hedeflenmesi için bir Foundry proje uç noktası gerekir. Otomasyonda bu uç noktayı oturum, CI işi veya kodlama aracısı çağrısı başına bir kez ayarlayın ve ardından çalıştırmanın geri kalanında kullanın.

İki desen vardır.

azd ai project set ile bir kez sabitleyin

Ortam değişkenini dışarı aktarmadan bağlamın kabuklar arasında kalıcı olmasını istiyorsanız, bunu genel yapılandırmada ayarlayın:

azd ai project set https://my-project.services.ai.azure.com/api/projects/my-project --no-prompt
azd ai project show

azd ai project set <endpoint> URL'yi zaten biliyorsanız tamamen etkileşimli değildir. azd ai project show etkin uç noktayı çözümleyen kaynağı onaylar. Konağın hangi durumda olduğundan emin değilseniz oturumun en üstünde kullanın.

Ortam değişkeni ayarlama

FOUNDRY_PROJECT_ENDPOINT öğesini betiğinizin veya kodlama aracınızın çalıştığı ortamda ayarlayın. Her azd ai komut, proje içi azd ortamı ve genel yapılandırmadan sonra bunu otomatik olarak kullanır.

export FOUNDRY_PROJECT_ENDPOINT="https://my-project.services.ai.azure.com/api/projects/my-project"
azd ai connection list --output json

Gizli bilgiler ve yapılandırmalar genellikle zaten ortam değişkenleri olarak geldiğinden ve işler arasında temizlenecek global bir durum da bulunmadığından, bu yaklaşım CI için çok uygundur.

CLI'nın öncelik sırası dahil olmak üzere uç noktayı nasıl çözümlediğinin tam açıklaması için bkz. Azd proje bağlamını ayarlama.

İstemleri devre dışı bırakma

Her azd ai komutu, --no-prompt kabul eder. Bunu ayarladığınızda, komut etkileşimli girişi engellemek yerine hızlı başarısız olur. Eksik bir gerekli argüman veya normalde bir tuşa basılmasını bekletecek olan bir delete onayı, yapılandırılmış çıktı ile anında hataya dönüşür.

--no-prompt değerini her zaman CI'da ve kodlama aracısı çağrılarında ayarlayın.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --no-prompt

Tip

--no-prompt ayrıca "delete onay istemini atla" anlamına da gelir; bu nedenle yalnızca bu istemi bastırmak için --force kullanmanız gerekmez.

JSON çıktısı alma

Çoğu azd ai komutu, --output json desteği sunar; buna connection, toolbox, skill ve routine kaynak komutları ile azd ai agent show dahildir. İnsanların okuyabildiği metin çıktısını kazımak yerine, sonucu jq, ConvertFrom-Json veya dilinizin JSON ayrıştırıcısıyla güvenilir bir şekilde ayrıştırmak için bunu kullanın. azd ai agent invoke komutu, değiştirilmemiş sunucu yanıtı için --output raw kullanır.

# List connections, extract names with jq
azd ai connection list --output json | jq -r '.[].name'

# Show a single resource as JSON
azd ai routine show daily-digest --output json | jq '.trigger'

# PowerShell example
$conn = azd ai connection show my-search --output json | ConvertFrom-Json
Write-Host $conn.target

Metin çıktısı insanlar içindir ve sürümler arasında değişebilir. JSON şekli kararlı sözleşmedir.

Kaynakları idempotent olarak oluşturun

create bir upsert değil. Belirtilen kaynak zaten mevcutsa, yeniden çalıştırma başarısız olur. Bu varsayılan, bir çağıranın başka bir çağıranın durumunun üzerine sessizce yazmasını engellediği için paylaşılan, proje kapsamındaki kaynaklar için uygundur.

Önceki durumdan bağımsız olarak başarılı olması gereken otomasyon için connection komutları, mevcut kaynağın yerine geçmek üzere --force seçeneğini kabul eder.

azd ai connection create my-search \
  --kind cognitive-search \
  --target https://my-search.search.windows.net \
  --auth-type api-key \
  --key "$KEY" \
  --force --no-prompt

Warning

--force Bağlantıyı (ARM PUT) değiştirir, birleştirmez. Paylaşılan kaynaklarda bunu dikkatli kullanın çünkü aynı kaynakta başka bir çağıranın yaptığı değişiklikler kaybolabilir.

Yalnızca birkaç alanı değiştirmeniz gerekiyorsa ve diğer her şeyi korumak istiyorsanız kullanın update. Veya tool, tag, metadata ve key gibi koleksiyona özel alt komutları kullanın.

Dosyadan araç kutusu oluşturma

Yerleşik araçları, bağlantıları ve becerileri paketleyen çok girişli bir araç kutusu için tam tanımı bir YAML dosyasına yerleştirin ve --from-file öğesini azd ai toolbox create öğesine geçirin. Dosya, karşılık gelen AgentSchema şeklini kullanır.

azd ai toolbox create research --from-file ./resources/research-toolbox.yaml --no-prompt

--from-file çağrı zamanında okunan tek seferlik giriştir. CLI dosyayı izlemez veya yeniden okumaz, bu nedenle yaml'de gelecekteki düzenlemelerin siz komutu yeniden çalıştırana kadar hiçbir etkisi olmaz. Açıkça belirtilmiş bayraklarla (--kind, --target, --auth-type ve karşılık gelen kimlik bilgisi bayrakları) bağlantılar oluşturun, ardından araç kutusu dosyasından bunlara adlarıyla başvurun.

Azd projesi olmadan dağıtılan aracıyı çağırma

Bir kodlama aracısının veya betiğin, çalışma dizininin dışında yaşayan dağıtılmış bir aracıyı çağırması gerektiğinde, bunu doğrudan hedeflemek için kullanın --agent-endpoint . Bu yaklaşım, hem azure.yaml öğesini hem de etkin azd ortamını atlar. URL tek başına yeterlidir.

azd ai agent invoke \
  --agent-endpoint https://my-project.services.ai.azure.com/api/projects/my-project/agents/release-summarizer/versions/3 \
  "Summarize today's release notes." \
  --no-prompt

Bir deponun CI işlem hattının farklı bir depoya ait bir ajanı çağırması gerektiğinde veya bir MCP sunucusu birkaç ajanın önünde yer alıp yalnızca bunların uç nokta URL'lerini bildiğinde bu şekli kullanın. Tüm seçenekler için bkz. Barındırılan invokearacı çağırma.

Gizli bilgileri yerel çalıştırmaya aktarma

Aracıyı gizli değerlerle yerel olarak başlatmak için bunları azd ortam değişkenleri olarak ayarlayın ve env içindeki azure.ai.agent hizmetiniz için kullanılan azure.yaml eşlemesinden bunlara başvurun. Değerler, Git tarafından varsayılan olarak yok sayılan .azure/<env>/.env içinde bulunur.

azd env set OPENAI_KEY "$AZURE_OPENAI_KEY"

# azure.yaml
services:
  my-agent:
    host: azure.ai.agent
    env:
      OPENAI_KEY: ${OPENAI_KEY}

Yerel bir .env dosyasında saklanmaması gereken gizli bilgiler için, bunları bir Foundry proje bağlantısında depolayın ve ${{connections.<name>.credentials.<field>}} yer tutucusunu kullanarak bunlara başvurun. Tam yerel çalıştırma yüzeyi için bkz. Barındırılan aracıyı yerel olarak çalıştırma.

Kısa bir kurulum betiği oluşturun

Bu bash betiği yukarıdaki desenleri birleştirir. Proje bağlamını sabitler, bir bağlantı ve bir araç kutusunu idempotent şekilde oluşturur, bir aracı araç kutusuna bağlar ve sonucu JSON ayrıştırarak doğrular.

#!/usr/bin/env bash
set -euo pipefail

azd ai project set "$FOUNDRY_PROJECT_ENDPOINT" --no-prompt

# A 'remote-tool' connection holds the URL and credentials for the MCP server.
azd ai connection create tavily \
  --kind remote-tool \
  --target https://mcp.tavily.com/mcp \
  --auth-type custom-keys \
  --custom-key "x-api-key=$TAVILY_KEY" \
  --force --no-prompt

# Create the toolbox with the connection wired in, in a single shot
cat > research-toolbox.yaml <<'EOF'
description: Research tools
connections:
  - name: tavily
EOF

azd ai toolbox create research --from-file ./research-toolbox.yaml --no-prompt

echo "Toolbox state:"
azd ai toolbox connection list research --output json | jq .

set -euo pipefail, adımlardan herhangi biri hata verirse betiğin hemen durmasını sağlar. --no-prompt ile birleştirildiğinde bu, CI kontrolleri için uygun deterministik bir çıkış kodu sağlar.

Uç nokta çözümlemesini gözden geçirme

Kodlama aracıları, bir komutun hedeflediği Foundry projelerini bu öncelik sırasına göre tahmin edebilir. Değer veren ilk kaynak kazanır; sonraki kaynaklara başvurulmuyor.

  1. --project-endpoint (veya -p) bayrağı (her zaman kazanır).
  2. Bir azd projesinde: etkin azd env değeri.
  3. Genel yapılandırma (tarafından azd ai project setayarlanır).
  4. FOUNDRY_PROJECT_ENDPOINT ortam değişkeni.
  5. azd ai project set komutunu çalıştırma veya --project-endpoint iletme yönünde yapılandırılmış bir öneri içeren hata oluştu.

Tek başına bağlamın proje içi çalışmayla nasıl etkileşim kurduğu da dahil olmak üzere tam açıklama için bkz. Azd proje bağlamını ayarlama.

Kodlama aracısı ipuçlarını uygulayın

  • Her zaman --no-prompt öğesini iletin ve bunu destekleyen komutlarda --output json seçeneğini ekleyin. Birlikte, size tahmin edilebilir bir çıkış kodu ve ayrıştırılabilir bir sonuç verir.
  • Ana bilgisayarın hangi durumda bulunduğundan emin değilseniz, oturumun başında çözümlenmiş bağlamı azd ai project show ile doğrulayın. Bu, ucuz ve salt okunur bir çağrıdır.
  • Hata durumunda, sonraki adımlara karar vermek için hata çıkışındaki yapılandırılmış öneriyi ayrıştırma seçeneğini tercih edin. Örneğin, "No Foundry project endpoint resolved" hatası, yeniden denemeden önce azd ai project set komutunu çalıştırmanız veya FOUNDRY_PROJECT_ENDPOINT ayarını yapmanız gerektiği anlamına gelir.
  • Yalnızca bir sorunu tanılarken kullanın --debug . Ayrıştırılması zor olan ve hiçbir zaman programlı arabirim olarak tasarlanmamış ayrıntılı, çok satırlı bir çıkış üretir.
  • create"Zaten var" hatalarını kurtarılabilir olarak değerlendirin. Kaynak sizin değiştirip yerine koyacağınız bir kaynaksa --force ile yeniden çalıştırın; yalnızca bir kısmını değiştirmeniz gerekiyorsa update ve koleksiyon alt komutlarına geçin.

İlgili içerik

  • Last updated on