Microsoft Foundry Temsilci Servisi

FoundryAgentAgent Framework'i Microsoft Foundry Agent Service tarafından yönetilen bir aracı tanımına bağlar. Aracının modeli, yönergeleri, barındırılan araçları ve sürümü Foundry'de yapılandırılır; uygulamanız bu tanıma bağlanır ve standart Agent Framework çalıştırma, akış ve oturum API'lerini kullanır.

Aşağıdakiler için bu tümleştirmeyi kullanın:

• Prompt Aracıları, adlandırılmış ve sürümlendirilmiş sunucu taraflı aracı tanımlarıdır.
• Barındırılan Aracılar, aracıya özgü bir uç nokta üzerinden erişilen, dağıtımı yapılmış aracı uygulamalardır.

Uygulamanızın aracı tanımına sahip olduğu doğrudan model çıkarımı için bkz. Microsoft Döküm modeli sağlayıcısı. Agent Framework uygulamasını barındırılan bir aracı olarak dağıtmak için bkz. Foundry Hosted Agents.

Paketleri yükleme

dotnet add package Azure.AI.Projects --prerelease
dotnet add package Azure.Identity
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

İstem Aracısı'na bağlanma

Foundry projesi için bir AIProjectClient oluşturun ve bir AgentReference öğesini FoundryAgent olarak sarın. Uygulamanın belirli bir Prompt Agent tanımını kullanması gerektiğinde sürümü sabitleyin.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;
using Microsoft.Agents.AI.Foundry;

var projectClient = new AIProjectClient(
    new Uri(Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")!),
    new DefaultAzureCredential());

FoundryAgent agent = projectClient.AsAIAgent(
    new AgentReference(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!,
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_VERSION")!));

Console.WriteLine(await agent.RunAsync("What can you help me with?"));

Ayrıca, en son sürümünü kullanmak için bir ProjectsAgentRecord veya açıkça alınmış bir sürümü kullanmak için bir ProjectsAgentVersion alabilir, ardından bu nesneyi projectClient.AsAIAgent(...) öğesine geçirebilirsiniz.

En son Prompt Agent sürümünü alma

Uygulamanın ada göre kayıtlı en son sürümü belirlemesi gerektiğinde AgentAdministrationClient kullanın.

ProjectsAgentRecord agentRecord =
    await projectClient.AgentAdministrationClient.GetAgentAsync(
        Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")!);

FoundryAgent latestAgent = projectClient.AsAIAgent(agentRecord);
Console.WriteLine(await latestAgent.RunAsync("What can you help me with?"));

Önemli

A FoundryAgent , Foundry tanımında depolanan modeli, yönergeleri ve barındırılan araçları kullanır. Foundry'de bu özellikleri yapılandırın; istemci, çalışma zamanında bunları değiştiremez.

Warning

DefaultAzureCredential geliştirme için uygundur. Üretim ortamında, istenmeyen kimlik bilgisi yoklamasını önlemek için ManagedIdentityCredential gibi belirli bir kimlik bilgisini tercih edin.

Barındırılan Aracıya Bağlan

Barındırılan Aracılar, aracıya özgü bir OpenAI uç noktası sunar. Uç noktayı proje uç noktasını ve kayıtlı aracı adını kullanarak oluşturun, ardından bunu AIProjectClient.AsAIAgent(...) öğesine iletin.

Env.TraversePath().Load();

// Port the Hosted-* samples listen on when run locally with `dotnet run`.
const int LocalAgentPort = 8088;

// AZURE_AI_AGENT_NAME is the registered server-side agent name.
string agentName = Environment.GetEnvironmentVariable("AZURE_AI_AGENT_NAME")
    ?? throw new InvalidOperationException("AZURE_AI_AGENT_NAME is not set.");

// Pick the server to talk to. `--local` and `--remote` mirror the flag `azd ai agent invoke`
// exposes; with neither, ask at startup.
    ══════════════════════════════════════════════════════════
    """);
Console.ResetColor();
Console.WriteLine();

Uç noktanın yönetici tarafından denetlenen sürüm seçicisi etkin Barındırılan Aracı sürümünü belirler.

Paketleri yükleme

pip install agent-framework-foundry

Configuration

FOUNDRY_PROJECT_ENDPOINT="https://<your-project>.services.ai.azure.com"
FOUNDRY_AGENT_NAME="my-agent"
FOUNDRY_AGENT_VERSION="1.0"

İstem Aracıları için FOUNDRY_AGENT_VERSION kullanın. Barındırılan Aracılar bunu atlayabilir.

Komut Aracısı'na Bağlan

Proje uç noktasını, aracı adını ve aracı sürümünü sağlayın. Hizmet depolanan modeli, yönergeleri ve barındırılan araç yapılandırmasını sağlar.

async def main() -> None:
    agent = FoundryAgent(
        project_endpoint="https://your-project.services.ai.azure.com",
        agent_name="my-prompt-agent",
        agent_version="1.0",
        credential=AzureCliCredential(),
    )

    result = await agent.run("What is the capital of France?")
    print(f"Agent: {result}")

    # Streaming
    print("Agent (streaming): ", end="", flush=True)
    async for chunk in agent.run("Tell me a fun fact.", stream=True):
        if chunk.text:
            print(chunk.text, end="", flush=True)
    print()

Bir İstem Aracısı yerel bir işlev aracı tanımlarsa, istemcinin istendiğinde bunu yürütebilmesi için FoundryAgent oluşturulurken eşleşen çağrılabilir öğeyi tools= üzerinden iletin. Bkz. Prompt Agent yayımlama ve bağlama örneği.

Barındırılan Aracıya Bağlan

Barındırılan Aracılar agent_version gerektirmez. Proje uç noktası ve kayıtlı aracı adıyla bağlanın.

async def main() -> None:
    # HostedAgents don't need agent_version
    agent = FoundryAgent(
        project_endpoint=os.getenv("FOUNDRY_PROJECT_ENDPOINT"),
        agent_name=os.getenv("FOUNDRY_AGENT_NAME"),
        credential=AzureCliCredential(),
    )

    result = await agent.run("Summarize the latest news about AI.")
    print(f"Agent: {result}")

Ne işe yarar ve nelerle çalışmaz? FoundryAgent

FoundryAgent Foundry'de zaten var olan bir aracı tanımına bağlanır. Depolanan yönergeler ve araç yapılandırması esas alındığından, istemci tarafındaki davranış uygulamaya ait olan Agent(client=FoundryChatClient(...))’den farklıdır.

Tools

Araç türü FoundryAgent(...) öğesine iletildi	Davranış
FunctionTool yerel bir çağrılabilir Python işleviyle	Yalnızca Eşleşen işlev tanımı Foundry aracısının üzerinde zaten mevcut olduğunda desteklenir. Çağrılabilir işlev, Foundry tarafından istendiğinde uygulama sürecinde çalışır.
Web araması, kod yorumlayıcı, dosya arama, MCP, görüntü oluşturma ve Microsoft Döküm Aracı Kutusu gibi barındırılan araçlar	Bunları Foundry aracı tanımında yapılandırın. Bunları istemci tarafında geçirmek, bunları hizmet tarafından yönetilen aracıya eklemez.

Toolbox bağlantısı ve doğrudan MCP kullanımıyla ilgili yönergeler için bkz. Microsoft Foundry Toolbox.

Yeni bir model görünür aracı yapım zamanında kaydedemezsiniz. Çağrılabilen bir işlev geçirilmesi yalnızca Foundry aracısının önceden bildirmiş olduğu bir işlev için yerel uygulamayı sağlar.

Bağlam sağlayıcıları

Bağlam sağlayıcısı davranışı	FoundryAgent ile çalışır mı?
Alınan bellek, RAG kod parçacıkları veya kullanıcı profili bilgileri gibi iletiler ekler	Yes. Eklenen bağlam istekle birlikte iletilir.
Konuşmayı saklar veya gözlemler	Yes. Sağlayıcı, istek ve yanıt çevresinde yerel olarak çalışır.
Araçları dinamik olarak ekler	Hayır, bu araçlar zaten Foundry ajan tanımında belirtilmiş değilse.

Uygulamanın dinamik araç seçimine, beceri yüklemesine veya çalışma zamanında model görünür araçları değiştiren herhangi bir davranışa ihtiyacı olduğunda kullanın Agent(client=FoundryChatClient(...)) .

Çalıştırma seçenekleri

Foundry aracı tanımı asıl referans olduğundan, default_options veya agent.run(...) üzerinden iletilen seçeneklerin tümü geçerli sayılmaz.

Seçenek	İstem Aracısı davranışı
model	Göz ardı edildi. Model, Foundry ajan tanımından gelir.
tools, tool_choice, parallel_tool_calls	İstekten kaldırıldı. Araçlar, Foundry aracı tanımında bildirilmelidir.
instructions ve sistem veya geliştirici iletileri	Göz ardı edildi. Depolanan Foundry yönergeleri yetkilidir.
conversation_id	Uygun olduğunda Foundry aracısı oturumunda kullanılır ve bu oturumla eşlenir.
extra_body	Çerçevenin sağladığı aracı referansıyla iletildi ve birleştirildi.
Örnekleme parametreleri, meta veriler, user, storeve response_format	İletildi, ancak Foundry aracısı veya model yapılandırması bunları geçersiz kılabilir veya kısıtlayabilir.

Barındırılan aracılar da aynı istemci taraflı filtrelemeye tabi olur, ancak dağıtılan aracı kendisine iletilen herhangi bir seçeneği kabul edebilir, yok sayabilir veya yeniden yorumlayabilir. Belirli bir Barındırılan Aracıya karşı davranışı doğrulayın.

Tip

Yönergeler, oluşturma seçenekleri veya araçlar üzerinde çalıştırma başına denetime ihtiyacınız olduğunda kullanın Agent(client=FoundryChatClient(...)) .

Barındırılan Aracı hizmeti oturumunu yönetin

Hizmet tarafı oturumları kullanan barındırılan Aracılar için önizleme Yanıtları yüzeyi gerekir:

Uygulamanın onu bir kiracıya veya kullanıcıya bağlaması gerektiğinde, hizmet oturumunu açıkça oluşturun; ardından tanımlayıcısını bir Agent Framework oturumu olarak kapsülleştirin.

    queries = [
        "Hi!",
        "Your name is Javis. What can you do?",
        "What is your name?",
    ]
    for query in queries:
        print(f"\nUser: {query}")
        print("Agent: ", end="", flush=True)
        async for chunk in agent.run(query, session=session, stream=True):
            if chunk.text:
                print(chunk.text, end="", flush=True)
    print()


async def run_service_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
) -> None:
    """Let Foundry create the hosted-agent session, then delete it when finished."""
    session = AgentSession()
    print("\nService-managed hosted-agent session")
    print(f"Before first request: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    try:
        await run_conversation(agent, session)
        print(f"After conversation: {session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)}")
    finally:
        hosted_session_id = session.state.get(FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY)
        if isinstance(hosted_session_id, str) and hosted_session_id:
            await project_client.agents.delete_session(agent_name, hosted_session_id)
            print(f"Deleted session: {hosted_session_id}")


async def run_user_managed_session(
    *,
    agent: FoundryAgent,
    project_client: AIProjectClient,
    agent_name: str,
    agent_version: str | None,
) -> None:
    """Create, attach, and delete a hosted-agent session explicitly."""
    resolved_agent_version = agent_version
    if resolved_agent_version is None:
        agent_details = await project_client.agents.get(agent_name)
        resolved_agent_version = agent_details.versions.latest.version

    hosted_session = await project_client.agents.create_session(
        agent_name,
        version_indicator=VersionRefIndicator(agent_version=resolved_agent_version),
    )
    session = AgentSession()
    session.state[FOUNDRY_HOSTED_AGENT_SESSION_ID_KEY] = hosted_session.agent_session_id

    print("\nUser-managed hosted-agent session")
    print(f"Created session: {hosted_session.agent_session_id}")
    try:
        await run_conversation(agent, session)
    finally:
        await project_client.agents.delete_session(agent_name, hosted_session.agent_session_id)
        print(f"Deleted session: {hosted_session.agent_session_id}")


async def main() -> None:
    credential = AzureCliCredential()
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
    agent_name = os.environ["FOUNDRY_AGENT_NAME"]
    agent_version = os.getenv("FOUNDRY_AGENT_VERSION")

    project_client = AIProjectClient(

Tip

Eksiksiz bir örnek için using_deployed_agent.py örneğe bakın.

Özel HTTP zaman aşımı ayarlama

FoundryAgent , OpenAI SDK zaman aşımını varsayılan olarak devralır. Çok turlu konuşmalar veya ağ koşulları farklı bir sınır değeri gerektirdiğinde, timeout= değerini saniye cinsinden iletin.

from agent_framework.foundry import FoundryAgent
from azure.identity import AzureCliCredential

agent = FoundryAgent(
    project_endpoint="https://your-project.services.ai.azure.com",
    agent_name="my-prompt-agent",
    credential=AzureCliCredential(),
    timeout=120.0,
)

Zaman aşımı HTTP istemcisinin aracı başına kopyasına uygulanır ve aynı AIProjectClientöğesini paylaşan diğer aracıları etkilemez.

Uyarı

FoundryAgent Prompt ve Hosted Agents entegrasyonu şu anda Agent Framework Go için mevcut değildir. En son durum için bkz. Agent Framework Go deposu .

Konuşmaları çalıştırma, akışla yayınlama ve sürdürme

Bağlandıktan sonra, diğer Agent Framework aracıları ile aynı API'leri kullanın:

• Bir isteği RunAsync veya run ile çalıştırın.
• Güncellemeleri RunStreamingAsync ile veya run(..., stream=True) ile alın.
• Bir konuşmayı sürdürmek için AgentSession öğesini yeniden kullanın.
• Konuşmanın Foundry projesinde görünür ve kalıcı olması gerektiğinde, Foundry sunucu tarafı konuşma API'lerini kullanın.

Foundry aracısı adlarını, sürümlerini, uç noktalarını ve konuşma tanımlayıcılarını güvenilir sunucu tarafındaki durumda tutun. Var olan bir konuşmayı sürdürmeden önce çağıranı yetkilandırın.

Sonraki Adımlar

Microsoft Döküm modeli sağlayıcısını gözden geçirme