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:

  • Sunucu tarafı aracı tanımları olarak adlandırılan ve sürümü oluşturulmuş istem Aracıları.
  • Aracıya özgü bir uç nokta üzerinden ulaşılan, dağıtılmış aracı uygulamaları olan barındırılan Aracılar.

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ı. Bir Agent Framework uygulamasını Barındırılan Aracı olarak dağıtmak için bkz. Foundry Barındırılan Aracılar.

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 olarak AgentReferenceFoundryAgentsarmalar. 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 öğesini ProjectsAgentRecord veya açıkça alınan bir sürümü kullanmak için öğesini ProjectsAgentVersion alabilir ve ardından bu nesneyi öğesine projectClient.AsAIAgent(...)geçirebilirsiniz.

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

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

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?"));

Important

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. Üretimde, istenmeyen kimlik bilgisi yoklamasını önlemek için gibi ManagedIdentityCredential belirli bir kimlik bilgilerini tercih edin.

Barındırılan Aracıya bağlanma

Barındırılan Aracılar aracıya özgü bir OpenAI uç noktasını kullanıma sunar. Proje uç noktasından ve kayıtlı aracı adından uç noktayı derleyin, ardından öğesine AIProjectClient.AsAIAgent(...)geçirin.

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.

İstem Aracısı'na bağlanma

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ı bildirirse, istemcinin istendiğinde yürütebilmesi için oluştururken FoundryAgent eşleşen çağrılabilen aracıyı geçirintools=. Bkz. Prompt Agent yayımlama ve bağlama örneği.

Barındırılan Aracıya bağlanma

Barındırılan Aracılar için gerekli agent_versiondeğildir. 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ı yetkilidir, bu nedenle istemci tarafı davranışı uygulamaya ait Agent(client=FoundryChatClient(...))olan 'dan farklıdır.

Tools

Araç türü FoundryAgent(...) öğesine iletildi Davranış
FunctionToolçağrılabilen yerel Python Yalnızca Eşleşen işlev tanımı Foundry aracısının üzerinde zaten mevcut olduğunda desteklenir. Çağrılabilir, Foundry istediğinde uygulama işleminde ç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.

Araç Kutusu eki ve doğrudan MCP tüketim kılavuzu için bkz. Microsoft Döküm Aracı Kutusu.

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ı kalıcı hale 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 aracı tanımında bildirilmemişse.

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ısı tanımı gerçeğin kaynağı olduğundan, geçirilen default_options veya agent.run(...) kabul edilen her seçenek değildir.

Seçenek İstem Aracısı davranışı
model Göz ardı edildi. Model, Foundry aracı 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 Kullanılabilir olduğunda Döküm aracı oturumu kullanılır ve bu oturumla eşlenir.
extra_body Çerçeve tarafından sağlanan aracı başvurusu ile 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 aynı istemci tarafı filtrelemesini alır, ancak dağıtılan aracı iletilen herhangi bir seçeneği kabul edebilir, yoksayabilir veya yeniden yorumlayabilir. Belirli bir Barındırılan Aracıya karşı davranışı doğrulayın.

İpucu

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 oturumlarını yönetme

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

Uygulamanın bunu 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 sarmalayın.

    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(

İpucu

Tam bir örnek için örneğeusing_deployed_agent.py bakın.

Özel HTTP zaman aşımı ayarlama

FoundryAgent , OpenAI SDK zaman aşımını varsayılan olarak devralır. Çok aşamalı konuşmalar veya ağ koşulları farklı bir sınır gerektirdiğinde saniyeler içinde geçirin timeout= .

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 İstem ve Barındırılan Aracılar tümleştirmesi şu anda Agent Framework Go için kullanılamıyor. 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:

  • veya runile RunAsync bir istek çalıştırın.
  • veya run(..., stream=True)ile RunStreamingAsync güncelleştirme akışı yapın.
  • Konuşmaya devam etmek için öğesini AgentSession yeniden kullanma.
  • 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üvenilen sunucu tarafı durumunda 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

  • Last updated on