Hızlı başlangıç: Kendi kodunuzu barındırılan bir aracı olarak dağıtma

İlk barındırılan aracınızı dağıtın bölümünde bir örnek dağıttınız. Bu hızlı başlangıçta, kendi Python veya .NET (C#) aracı kodunuzu Döküm Aracı Hizmeti'ne dağıtacaksınız. Kodunuz Microsoft Agent Framework, LangGraph, GitHub Copilot SDK veya OpenAI Aracıları SDK'sı gibi herhangi bir aracı çerçevesini veya modeli doğrudan çağıran düz kodu kullanabilir.

Her kod adımında diliniz ve protokolünüzün sekmeleri vardır. Her adımda C# (Yanıtlar) gibi aynı bileşimi seçin.

GitHub Copilot gibi bir kodlama aracısı kullanıyorsanız, Microsoft Döküm Becerisi hızlı başlangıcı kendi kod tabanınıza uyarlamanıza ve doğru azd dağıtım adımlarını çalıştırmanıza yardımcı olabilir.

Prerequisites

Başlamadan önce şunları yapmanız gerekir:

• bir Azure aboneliği-- ücretsiz bir abonelik oluşturma.

• Mevcut bir Foundry projeniz varsa, proje kapsamında Foundry Project Manager gerekir. Yeni bir Foundry projesi oluşturmanız gerekiyorsa, kaynak grubu kapsamında Owner rolüne sahip olmanız gerekir. Rol matrisinin tamamı için Barındırılan aracı izinleri başvuru belgesine bkz.

• Azure Developer CLI (azd) 1.27.1 veya üzeri.

• Uzantı azd microsoft.foundry :

  azd ext install microsoft.foundry
  

• Kimliği doğrulanmış azd bir oturum:

  azd auth login
  

• Yerel bir dizindeki mevcut ajan kodunuz.

• Python yolu için Python 3.13 veya üzeri.

• C# yolu için .NET 10 SDK veya üzeri.

• (İsteğe bağlı) Visual Studio Code'daki bir örnekten başlamak için Visual Studio Code ve Visual Studio Code için Microsoft Döküm Araç Seti'ni yükleyin.

Proje dizininiz Python için en azından şunları içermelidir:

my-agent/
├── main.py              # Your agent entry point
└── requirements.txt     # Python dependencies

Veya .NET bir web projesi olan C# için:

my-agent/
├── Program.cs           # Your agent entry point
└── my-agent.csproj      # Project file (web SDK)

Çerçevenizi seçin

1. Adım'a eklediğiniz barındırma kitaplığı http sunucusu, sistem durumu denetimleri ve istek ve yanıt şemaları olan protokolü işler. Belirli bir aracı çerçevesine bağlı olmadığından aracı mantığınız Python veya C# dilinde tercih ettiğiniz paketleri kullanabilir.

Çerçeve kullanmak için, paketlerini barındırma kitaplığının yanına ekleyin ve işleyiciden çerçeveyi çağırın. Aşağıdaki tabloda ortak seçenekler ve her birine Python bir örnek listeledik.

Çerçeve	requirements.txt eklenecek paketler	Sample
Düz Python (modeli doğrudan çağır)	azure-ai-projects	hello-world
LangGraph	langgraph, langchain-azure-ai	langgraph-chat
GitHub Copilot SDK'sı	github-copilot-sdk	github-copilot
OpenAI Aracıları SDK'sı	openai-agents	openai-agents-sdk

Her örnekte requirements.txt, paketlerin tam sürümlerini listeler. Kendi örneklerinizi getirin tam kümesi için Python örnekleri klasörüne bakın.

C# için, barındırma paketinin yanındaki proje dosyanıza çerçeve paketleri ekleyin ve içindeki işleyiciden Program.csçerçeveyi çağırın. C# örneklerinin tamamı için C# kendi örneklerini getir klasörüne bakın.

Note

Microsoft Agent Framework kendi paketini kullanan yerleşik bir barındırma tümleştirmesine sahiptir. Microsoft Agent Framework aracısını dağıtmak için bkz. İlk barındırılan aracınızı dağıtma.

Visual Studio Code'daki bir örnekten başlama

Kendi kodunuz yerine bir çalışma çerçevesi şablonundan başlamak için Microsoft Foundry Toolkit for Visual Studio Code örnek galerisini kullanın:

1. Visual Studio Code Etkinlik Çubuğu'nda Döküm Araç Seti simgesini seçin.
2. Geliştirici Araçları>Aracısı Geliştirme Araçları'nın altında Aracı Oluştur'u seçin.
3. Tam denetimle kodda oluştur'un altında Örnek kullan'ı seçin.
4. Örnekten Barındırılan Aracı Oluştur'da, galeriyi daraltmak için filtreleri kullanın:
   • Framework için Agent Framework, Kendi Çerçevenizi Getirin, LangGraph veya Copilot SDK'sını seçin.
   • Protokol Türü için Yanıtlar API'sini veya Çağırmalar API'sini seçin.
5. Bir örnek seçin ve ardından İleri'yi seçin.
6. Bir aracı adı girin, Dökümhane projenizi seçin ve ardından Oluştur'u seçin.

Araç seti, örneği yeni bir çalışma alanına ekler ve tek tıklamayla F5 hata ayıklama deneyimi ayarlar. Bağımlılıkları yüklemek, yerel olarak test etmek ve Visual Studio Code'den dağıtmak için, İlk barındırılan aracınızı dağıtma makalesindeki Visual Studio Code adımlarını izleyin.

Protokolünüzü seçin

Her kod adımında dil ve protokolün her birleşimi için bir sekme vardır. Yanıtlar konuşma geçmişini yönetir ve OpenAI ile uyumludur. Çağırmalar , istek ve yanıt şemaları üzerinde tam denetim sağlar. Her adımda aynı dili ve protokol bileşimini seçin.

İpucu

Hangi protokolü kullanacağınızdan emin değil misiniz? Yanıtlar ile başlayın.

1. Adım: Barındırma kitaplığını ekleme

Protokol kitaplığını projenize ekleyin. Kitaplık, kullandığınız aracı çerçevesinden bağımsız olarak HTTP sunucusunu, sistem durumu denetimlerini ve protokol uyumluluğunu işler. Çerçeve kullanıyorsanız, barındırma kitaplığının yanına paketlerini ekleyin - bkz. Çerçevenizi seçme.

Python (Yanıtlar)

Protokol kitaplığını requirements.txt öğenize ekleyin:

azure-ai-agentserver-responses>=1.0.0b7

Python (Çağırmalar)

Protokol kitaplığını requirements.txt öğenize ekleyin:

azure-ai-agentserver-invocations>=1.0.0b5

C# (Yanıtlar)

bir .NET web projesi oluşturun ve protokol paketini ekleyin:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Responses --prerelease

C# (Çağrılar)

bir .NET web projesi oluşturun ve protokol paketini ekleyin:

dotnet new web --name my-agent
cd my-agent
dotnet add package Azure.AI.AgentServer.Invocations --prerelease

2. Adım: Barındırma sarmalayıcısını ekleme

Barındırma sarmalayıcısı ile aracı giriş noktanızı oluşturun veya güncelleştirin. Aşağıdaki örnekler en basit örüntüyü göstermektedir. İşaretli bloğu mevcut ajan mantığınızla değiştirin.

Python (Yanıtlar)

oluşturun veya güncelleştirin main.py:

import asyncio
from azure.ai.agentserver.responses import (
    CreateResponse,
    ResponseContext,
    ResponsesAgentServerHost,
    TextResponse,
)

app = ResponsesAgentServerHost()


@app.response_handler
async def handler(
    request: CreateResponse,
    context: ResponseContext,
    _cancellation_signal: asyncio.Event,
):
    user_input = await context.get_input_text() or ""

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_input}"
    # ─────────────────────────────

    return TextResponse(context, request, text=reply)


app.run()

Python (Çağrılar)

oluşturun veya güncelleştirin main.py:

import json
from starlette.requests import Request
from starlette.responses import JSONResponse
from azure.ai.agentserver.invocations import InvocationAgentServerHost

app = InvocationAgentServerHost()


@app.invoke_handler
async def handle_invoke(request: Request):
    raw = (await request.body()).decode("utf-8").strip()
    try:
        body = json.loads(raw)
        user_message = (
            body.get("message") or body.get("input") or raw
        )
    except json.JSONDecodeError:
        user_message = raw

    # ─── YOUR AGENT LOGIC HERE ───
    reply = f"Hello! You said: {user_message}"
    # ─────────────────────────────

    return JSONResponse({"reply": reply})


if __name__ == "__main__":
    app.run()

C# (Yanıtlar)

Program.cs değerini değiştirin:

using Azure.AI.AgentServer.Responses;
using Azure.AI.AgentServer.Responses.Models;

ResponsesServer.Run<EchoHandler>();

public sealed class EchoHandler : ResponseHandler
{
    public override IAsyncEnumerable<ResponseStreamEvent> CreateAsync(
        CreateResponse request,
        ResponseContext context,
        CancellationToken cancellationToken)
    {
        return new TextResponse(context, request, createText: async ct =>
        {
            var userInput = await context.GetInputTextAsync(cancellationToken: ct) ?? "";

            // ─── YOUR AGENT LOGIC HERE ───
            var reply = $"Hello! You said: {userInput}";
            // ──────────────────────────────

            return reply;
        });
    }
}

C# (Çağrılar)

Değiştirin Program.cs:

using System.Text.Json;
using Azure.AI.AgentServer.Invocations;
using Microsoft.AspNetCore.Http;

InvocationsServer.Run<EchoHandler>();

public sealed class EchoHandler : InvocationHandler
{
    public override async Task HandleAsync(
        HttpRequest request,
        HttpResponse response,
        InvocationContext context,
        CancellationToken cancellationToken)
    {
        var raw = (await new StreamReader(request.Body).ReadToEndAsync(cancellationToken)).Trim();

        string userMessage;
        try
        {
            var body = JsonDocument.Parse(raw).RootElement;
            userMessage =
                (body.TryGetProperty("message", out var m) ? m.GetString() : null)
                ?? (body.TryGetProperty("input", out var input) ? input.GetString() : null)
                ?? raw;
        }
        catch (JsonException)
        {
            userMessage = raw;
        }

        // ─── YOUR AGENT LOGIC HERE ───
        var reply = $"Hello! You said: {userMessage}";
        // ──────────────────────────────

        await response.WriteAsJsonAsync(new { reply }, cancellationToken);
    }
}

Note

Bu örnekler, barındırma sarmalayıcısını göstermek için kullanıcı girişini yankılar. İşaretli bloğu kendi aracı mantığınızla (model çağrıları, RAG veya LangGraph veya GitHub Copilot SDK gibi bir çerçeve) değiştirin. Tam örnekler için bkz. Python örnekleri ve C# örnekleri.

3. Adım: Projeyi başlatma

Ajan kaynak dizininizden azd ai agent init komutunu çalıştırın. Azure Geliştirici CLI'sı proje dosyalarından dilinizi algılar:

Python (Yanıtlar)

azd ai agent init --protocol responses --deploy-mode code

Python (Çağrılar)

azd ai agent init --protocol invocations --deploy-mode code

C# (Yanıtlar)

azd ai agent init --protocol responses --deploy-mode code

C# (Çağrılar)

azd ai agent init --protocol invocations --deploy-mode code

Etkileşimli akış aşağıdakileri ister:

• Aracı adı: Adı özelleştirin veya varsayılanı kabul edin.
• Dökümhane Project: Var olan bir Dökümhane project kullan'ı veya Yeni bir Dökümhane project oluştur'u seçin.
• Abonelik: Azure aboneliğinizi seçin.
• Konum: Azure bir bölge seçin.

İşlem tamamlandığında şunu görürsünüz: azd projenize başarıyla yapay zeka aracısı tanımı eklendi!

4. Adım: Azure kaynakları sağlama

azd provision

Bu, Application Insights gibi gerekli Azure kaynaklarını oluşturur.

5. Adım: Ajanı yerel olarak test edin

azd ai agent run

Bu komut bir sanal ortam (Python) oluşturur veya projeyi geri yükler ve oluşturur (C#), bağımlılıkları yükler ve aracınızı başlatır. Ayrıca, ajanla sohbet edebilmeniz için tarayıcınızda ajan denetçisini açar.

CLI'dan ayrı bir terminalde de çağrı yapabilirsiniz:

azd ai agent invoke --local "Hello from my hosted agent"

6. Adım: Foundry Agent Servisi'ne Dağıtma

azd deploy

Komut tamamlandığında, çıktıda aracı deneme ortamına ve aracı uç noktasına yönelik bağlantılar gösterilir:

Deploying services (azd deploy)

  Done: Deploying service my-agent
  - Agent playground (portal): https://ai.azure.com/.../build/agents/my-agent/build?version=1
  - Agent endpoint: https://ai-account-<name>.services.ai.azure.com/api/projects/<project>/agents/my-agent/versions/1

7. Adım: Dağıtılmış aracıyı çağırın

azd ai agent invoke "Hello from my hosted agent"

Birkaç saniye içinde bir yanıt görmeniz gerekir.

Kaynakları temizle

Warning

Geçerli azd ortam Foundry projesini oluşturduysa, azd down projenin kaynak grubunu ve içindeki her şeyi kalıcı olarak siler. Başlatma sırasında mevcut bir projeyi seçtiyseniz projeyi, azd down kaynak grubunu, barındırılan aracıyı ve diğer hızlı başlangıç kaynaklarını yerinde bırakır. Artık ihtiyacınız olmayan kaynakları mevcut projeden ayrı olarak silin.

azd down

Troubleshooting

Issue	Çözüm
ModuleNotFoundError: azure.ai.agentserver	Protokol kitaplığının içinde requirements.txt olduğunu doğrulayın ve yeniden yükleyin: pip install -r requirements.txt.
C#: The type or namespace name 'AgentServer' could not be found	Protokol paketine başvurulduğunu (dotnet add package Azure.AI.AgentServer.Responses --prerelease veya Azure.AI.AgentServer.Invocations) ve projenin web SDK'sını (dotnet new web) kullandığını doğrulayın.
C#: dotnet run üzerinde Cannot resolve scoped service ... Handler from root provider	Varsayılan dotnet new web başlatma profili, katı kapsam doğrulamasını etkinleştiren ASPNETCORE_ENVIRONMENT=Development değerini ayarlar. Test etmek için kullanın azd ai agent run (barındırılan modda çalışır) veya öncesinde dotnet runayarlayınASPNETCORE_ENVIRONMENT=Production.
FOUNDRY_PROJECT_ENDPOINT not set	Uygulamayı doğrudan çalıştırmak yerine kullanın azd ai agent run (otomatik olarak ayarlar). Veya dosyanıza .env ekleyin.
Connection refused yerel çalıştırmada	Başka hiçbir işlemin 8088 numaralı bağlantı noktasını kullanmadığından emin olun.
AuthorizationFailed dağıtım sırasında	Proje kapsamında Foundry Project Manager gerekir.
Aracı takılı kaldı provisioning	Durumu denetlemek için komutunu çalıştırın azd ai agent show . Bağımlılıklar yüklenirken ilk dağıtımlar 2-3 dakika sürebilir.
azd ai agent init Başarısız	1.27.1 veya üzerini doğrulamak için komutunu çalıştırın azd version . 1.0.0-beta.4 veya üzerini doğrulamak için komutunu çalıştırın azd ext show azure.ai.agents . azd ext upgrade azure.ai.agents ile yükseltin.

İzin ve rol atama matrisinin tamamı için Barındırılan aracı izinleri başvuru bilgileri bölümüne bakın.

Öğrendiklerin

Bu hızlı başlangıç rehberinde şunları yapacaksınız:

• Mevcut aracı kodunuza bir barındırma kitaplığı eklediniz.
• Kaynak dizininizden bir azd proje başlatıldı.
• azd ai agent run ve azd ai agent invoke --local ile yerelde test edildi.
• azd deploy ile Foundry Aracı Hizmeti'ne dağıtıldı.

Sonraki Adımlar

Barındırılan aracı yaşam döngüsünü yönetme

• Araçları yönetilen bir uç noktanın arkasında birleştirmek için bir araç kutusu oluşturun ve bunu barındırılan bir aracıyla birlikte kullanın.

İlgili içerik

• Barındırılan ajanlar nedir?
• Kaynak kodundan barındırılan aracı dağıtma
• Kapsayıcıdan barındırılan aracı dağıtın
• Ajans geliştirme süreci
• Python tarafından barındırılan temsilci örnekleri
• Kendi çerçevenizle ilgili örnekler (LangGraph, GitHub Copilot SDK ve daha fazlası)
• C# için barındırılan aracı örnekleri