Registrace a správa vlastních agentů

Microsoft Foundry Control Plane poskytuje centralizovanou správu a monitorování pro agenty běžící na různých platformách a infrastrukturách. Můžete zaregistrovat vlastní agenty, kteří běží v Azure výpočetních službách nebo jiných cloudových prostředích, abyste získali přehled o jejich operacích a mohli řídit jejich chování.

V tomto článku se dozvíte, jak zaregistrovat vlastního agenta v řídicím plánu Foundry. Dozvíte se, jak nakonfigurovat agenta pro registraci, nastavit shromažďování dat a používat nástroje správy v rámci platformy Foundry Control Plane.

Požadavky

  • AI brána nakonfigurovaná v prostředku Foundry. Foundry používá Azure API Management k registraci agentů jako rozhraní API.

  • Agent, kterého nasadíte a zpřístupníte prostřednictvím dosažitelného koncového bodu. Koncový bod může být veřejný koncový bod nebo koncový bod, který je dostupný ze sítě, kam nasadíte prostředek Foundry.

Poznámka

Tato funkce je dostupná jenom na portálu Foundry (nový). V banneru portálu vyhledejte , abyste potvrdili, že používáte nový Foundry.

Přidání vlastního agenta

Můžete zaregistrovat vlastního agenta v řídicí rovině Foundry. Vyvíjejte agenta v technologii podle vašeho výběru pro řešení platformy i infrastruktury.

Když zaregistrujete vlastního agenta, Foundry používá api Management k tomu, aby fungoval jako proxy server pro komunikaci s vaším agentem, aby mohl řídit přístup a monitorovat aktivitu.

Následující diagram znázorňuje výslednou architekturu při registraci vlastního agenta.

Diagram znázorňující výslednou architekturu po registraci a konfiguraci vlastního agenta

Ověřte svého agenta

Ověřte, že váš agent splňuje požadavky na registraci:

  • Váš agent zveřejňuje výhradní koncový bod.
  • Síť, do které nasadíte prostředek Foundry, se může spojit s koncovým bodem agenta.
  • Agent komunikuje pomocí jednoho z podporovaných protokolů: HTTP (obecné) nebo A2A (konkrétnější).
  • Váš agent generuje data pomocí sémantických konvencí OpenTelemetry pro řešení generující AI (nebo tuto funkci nepotřebujete).
  • Můžete nakonfigurovat koncový bod, který uživatelé používají ke komunikaci s agentem. Po registraci agenta vygeneruje Foundry Control Plane novou adresu URL. Klienti a uživatelé musí tuto adresu URL použít ke komunikaci s agentem.

Příprava projektu Foundry

Než zaregistrujete vlastního agenta, který jste přidali do projektu Foundry, ujistěte se, že jste projekt nakonfigurovali správně:

  1. Přihlaste se k Microsoft Foundry. Ujistěte se, že je zapnutý přepínač New Foundry . Tyto kroky se vztahují k Foundry (nové).

  2. Ujistěte se, že je v projektu nakonfigurovaná brána AI:

    1. Na panelu nástrojů vyberte Operace.

    2. V levém podokně vyberte Správce.

    3. Otevřete kartu Brána AI .

    4. V podokně jsou uvedeny všechny brány AI nakonfigurované a namapované na prostředek Foundry. Zkontrolujte, jestli prostředek Foundry, který chcete použít, má přidruženou bránu AI.

      Snímek obrazovky portálu pro správu Foundry, který ukazuje kroky pro ověření, jestli má projekt nakonfigurovanou bránu AI

    5. Pokud prostředek Foundry, který chcete použít, nemá nakonfigurovanou bránu AI (není uvedená), přidejte ji pomocí možnosti Přidat bránu AI .

      Brána AI je bezplatná k nastavení a odemykání výkonných funkcí zásad správného řízení, jako jsou zabezpečení, diagnostická data a omezení rychlosti pro vaše agenty, nástroje a modely. Další informace najdete v tématu Vytvoření brány AI.

  3. Ujistěte se, že máte v projektu nakonfigurovanou pozorovatelnost. Řídicí vrstva Foundry používá prostředek Application Insights přidružený k vašemu vybranému projektu pro vysílání dat, která vám pomohou diagnostikovat vašeho agenta.

    1. Na panelu nástrojů vyberte Operace.

    2. V levém podokně vyberte Správce.

    3. V části Všechny projekty vyhledejte projekt pomocí vyhledávacího pole.

    4. Vyberte projekt.

    5. Vyberte kartu Připojené prostředky .

    6. Ujistěte se, že je v kategorii AppInsights přidružený prostředek.

      Snímek obrazovky portálu pro správu, který ukazuje kroky k ověření, jestli má projekt přidružený prostředek Application Insights

    7. Pokud žádný přidružený prostředek neexistuje, přidejte ho výběrem Přidat připojení>Application Insights.

Projekt je nakonfigurovaný pro pozorovatelnost a trasování.

Registrace agenta (prostředek)

  1. Na panelu nástrojů vyberte Operace.

  2. V podokně Přehled vyberte Zaregistrovat prostředek.

    Snímek obrazovky s tlačítkem pro registraci agenta v podokně Přehled na portálu Foundry

  3. Zobrazí se průvodce registrací. Nejprve vyplňte podrobnosti o agentu, kterého chcete zaregistrovat. Následující vlastnosti popisují agenta, jak běží na své platformě.

    Vlastnost Popis Požadované
    Adresa URL agenta Koncový bod (URL), kde váš agent běží a přijímá požadavky. Obecně platí, že v závislosti na vašem protokolu označujete základní adresu URL, kterou vaši klienti používají. Pokud například váš agent používá rozhraní API pro dokončování chatu OpenAI, uveďte https://<host>/v1/ bez /chat/completions, protože ho klienti obvykle přidávají. Ano
    Protokol Komunikační protokol, který váš agent podporuje. Obecně používejte protokol HTTP. Nebo pokud váš agent podporuje konkrétněji A2A, uveďte to. Ano
    Adresa URL karty agenta A2A Cesta k JSON specifikaci karty agenta. Pokud ho nezadáte, použije systém výchozí /.well-known/agent-card.jsonhodnotu . Ano, když je protokolA2A
    ID agenta OpenTelemetry ID agenta, které váš agent používá k emitování tras podle sémantických konvencí OpenTelemetry pro generativní AI. Trasování označuje v atributu gen_ai.agent.id rozsahy s názvem operace create_agent. Pokud tuto hodnotu nezadáte, systém pomocí hodnoty název agenta vyhledá trasování a protokoly, které tento nový agent hlásí. Ne
    Adresa URL portálu pro správu Adresa URL portálu pro správu, kde můžete pro tohoto agenta provádět další operace správy. Foundry může tuto hodnotu uložit pro pohodlí. Foundry nemá přístup k provádění operací přímo na tomto portálu. Ne

  4. Nakonfigurujte, jak se má agent zobrazovat v řídicí plošině Foundry.

    Vlastnost Popis Požadované
    Project Projekt, do kterého agenta zaregistrujete. Foundry používá bránu AI nakonfigurovanou v prostředku, který obsahuje projekt, ke konfiguraci příchozího koncového bodu pro agenta. Můžete vybrat jen projekty, které mají v prostředcích povolenou bránu AI. Pokud nevidíte žádné brány AI, nakonfigurujte bránu AI ve svém prostředku Foundry. Doporučujeme také nakonfigurovat Application Insights ve vybraném projektu. Foundry používá prostředek Application Insights projektu k ukládání tras a protokolů. Ano
    Název agenta Název agenta, jak chcete, aby se zobrazoval v Foundry. Systém může tento název také použít k vyhledání relevantních trasování a protokolů v Application Insights, pokud pro ID agenta OpenTelemetry nezadáte jinou hodnotu. Ano
    Popis Jasný popis tohoto agenta. Ne

  5. Uložte změny.

  6. Foundry přidá nového agenta. Pro zkontrolování seznamu agentů vyberte na levém panelu Assets.

  7. Pokud chcete zobrazit jenom vlastní agenty, použijte filtr Zdroj a vyberte Vlastní.

    Snímek obrazovky s registrovaným vlastním agentem

Připojení klientů k agentu

Když zaregistrujete agenta v Foundry, získáte novou adresu URL, kterou budou vaši klienti používat. Vzhledem k tomu, že Foundry funguje jako proxy pro komunikaci s vaším agentem, může řídit přístup a monitorovat aktivitu.

Distribuce nové adresy URL tak, aby klienti mohli volat agenta:

  1. V seznamu agentů výběrem přepínače vedle názvu vlastního agenta otevřete informační podokno. Nevybírejte samotný název agenta, protože tento odkaz přejde mimo podokno Prostředky .

  2. V informačním podokně v části Adresa URL agenta vyberte možnost Kopírovat .

    Snímek obrazovky s postupem pro zkopírování nové adresy URL agenta po registraci

  3. Pomocí nové adresy URL můžete místo původního koncového bodu volat agenta.

V tomto příkladu nasadíte agenta LangGraph. Klienti k jeho využití používají sadu LangGraph SDK. Klient používá novou hodnotu adresy URL agenta . Tento kód vytvoří vlákno, odešle zprávu s dotazem na počasí a streamuje odpověď zpět.

import asyncio
from langgraph_sdk import get_client

client = get_client(url="https://apim-my-foundry-resource.azure-api.net/my-custom-agent/")

async def stream_run():
    thread = await client.threads.create()
    input_data = {"messages": [{"role": "human", "content": "What's the weather in LA?"}]}

    async for chunk in client.runs.stream(thread['thread_id'], assistant_id="your_assistant_id", input=input_data):
        print(chunk)

asyncio.run(stream_run())

Očekávaný výstup: Agent zpracuje zprávu a streamuje zpět odpovědi jako bloky dat. Každý blok dat obsahuje částečné výsledky spuštění agenta. Tyto výsledky mohou zahrnovat volání nástrojů do funkce počasí a konečnou odpověď na počasí v Los Angeles.

Poznámka

I když Foundry funguje jako proxy pro příchozí požadavky pro vašeho agenta, původní schéma autorizace a ověřování v původním koncovém bodu stále platí. Při využívání nového koncového bodu zadejte stejný mechanismus ověřování, jako kdybyste používali původní koncový bod.

Blokování a odblokování agenta

U vlastních agentů nemá Foundry přístup k základní infrastruktuře, ve které běží agent, takže operace spuštění a zastavení nejsou k dispozici. Foundry ale může blokovat příchozí požadavky agenta, aby ho klienti nemohli využívat. Tato funkce umožňuje správcům zakázat agenta, pokud se chová nesprávně.

Blokování příchozích požadavků pro vašeho agenta:

  1. Na panelu nástrojů vyberte Operace.

  2. V levém podokně vyberte Prostředky.

  3. Vyberte rádiové tlačítko vedle agenta, kterého chcete blokovat. Zobrazí se informační podokno. Nevybírejte název agenta, protože tento odkaz přejde mimo podokno Prostředky .

  4. Vyberte Aktualizovat stav a pak vyberte Blokovat.

    Snímek obrazovky s postupem blokování příchozích požadavků na agenta

  5. Potvrďte operaci.

Jakmile agenta zablokujete, hodnota Stav agenta v Foundry je blokována. Agenti v zablokovaném stavu běží ve své přidružené infrastruktuře, ale nemůžou přijímat příchozí požadavky. Foundry blokuje všechny pokusy o rozhraní s agentem.

Odblokování agenta:

  1. Vyberte Aktualizovat stav a pak vyberte Odblokovat.

  2. Potvrďte operaci.

Povolit diagnostická data pro agenta

Foundry používá otevřený standard OpenTelemetry k pochopení toho, co agenti dělají. Pokud má váš projekt nakonfigurovaný Application Insights, Foundry ve výchozím nastavení protokoluje požadavky do Application Insights. Foundry také používá tato data k výpočtu:

  • Běhy
  • Míra chyb
  • Využití (pokud je k dispozici)

Pokud chcete dosáhnout nejlepší úrovně věrnosti, Foundry očekává, že vlastní agenti budou dodržovat sémantické konvence pro generování řešení AI ve standardu OpenTelemetry.

Zobrazení trasování a protokolů odeslaných do Foundry

  1. Na panelu nástrojů vyberte Operace.

  2. V levém podokně vyberte Prostředky.

  3. Výběrem přepínače vedle agenta otevřete informační podokno. Nevybírejte název agenta, protože tento odkaz přejde mimo podokno Prostředky .

  4. V části Trasování se zobrazí jedna položka pro každé volání HTTP provedené do koncového bodu agenta.

    Pokud chcete zobrazit podrobnosti, vyberte položku.

    Snímek obrazovky s voláním koncového bodu agenta pod trasou pro spuštění a datové proudy

    Tip

    V tomto příkladu vidíte, jak klienti používají koncový bod nového agenta ke komunikaci s agentem. Příklad ukazuje agenta obsluhovaného protokolem Agena od LangChain. Klienti používají trasu /runs/stream.

V tomto příkladu trasování neobsahuje žádné podrobnosti nad rámec příspěvku HTTP. Kód agenta neobsahuje žádnou další instrumentaci. V další části se dozvíte, jak instrumentovat kód a získat podrobnosti, jako jsou volání nástrojů a volání LLM (Large Language Model).

Nástroje pro vlastní agenty kódů

Pokud vytvoříte agenta pomocí vlastního kódu, instrumentujte své řešení tak, aby vygeneroval trasování podle standardu OpenTelemetry a odeslal je do Application Insights. Instrumentace poskytuje Foundry přístup k podrobným informacím o tom, co váš agent dělá.

Pomocí instrumentačního klíče odešlete trasování do prostředku Application Insights vašeho projektu. Pokud chcete získat instrumentační klíč přidružený k vašemu projektu, postupujte podle pokynů v tématu Připojení Application Insights k projektu Foundry.

V tomto příkladu nakonfigurujete agenta vyvinutého v LangGraphu, aby emitoval sledování ve standardu OpenTelemetry. Tracer zachycuje všechny operace agenta, včetně volání nástrojů a interakcí modelu. Tracer pak odešle operace do Application Insights pro monitorování.

Tento kód používá balíček langchain-azure-ai . Pokyny k instrumentaci konkrétních řešení pomocí OpenTelemetry najdete v závislosti na programovacím jazyce a architektuře, které vaše řešení používá, viz rozhraní API jazyka a sady SDK.

pip install -U langchain-azure-ai[opentelemetry]

Pak nasaďte svého agenta:

from langchain.agents import create_agent
from langchain_azure_ai.callbacks.tracers import AzureAIOpenTelemetryTracer

application_insights_connection_string = "InstrumentationKey=12345678-..."

tracer = AzureAIOpenTelemetryTracer(
    connection_string=application_insights_connection_string,
    enable_content_recording=True,
)

def get_weather(city: str) -> str:
    """Get weather for a given city."""
    return f"It's always sunny in {city}!"

agent = create_agent(
    model="openai:gpt-5.1",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
).with_config({ "callbacks": [tracer] })

Očekávaný výstup: Agent běží normálně při automatickém vysílání tras OpenTelemetry do Application Insights. Sledování zahrnuje názvy operací, doby trvání, volání modelů, vyvolání nástrojů a použití tokenů. Tyto trasy můžete zobrazit na portálu Foundry v části Trasy.

Tip

Do Application Insights můžete předat připojovací řetězec pomocí proměnné prostředí APPLICATIONINSIGHTS_CONNECTION_STRING.

Řešení pro platformu Instrument

Pokud váš agent běží na řešení platformy, které podporuje OpenTelemetry, ale nepodporuje Application Insights, nasaďte kolektor OpenTelemetry a nakonfigurujte software tak, aby odesílal data OTLP do kolektoru (standardní konfigurace OpenTelemetry).

Nakonfigurujte kolektor s exportérem Azure Monitor tak, aby předával data do Application Insights pomocí vašeho připojovací řetězec. Podrobnosti o tom, jak ho implementovat, najdete v tématu Konfigurování Azure Monitor OpenTelemetry.

Řešení potíží se sledováním

Pokud stopy nevidíte, zkontrolujte následující položky:

  • Projekt, ve kterém zaregistrujete agenta, má nakonfigurovanou službu Application Insights. Pokud jste po registraci vlastního agenta nakonfigurovali Application Insights, musíte agenta zrušit a zaregistrovat ho znovu. Pokud jste ji změnili, konfigurace Application Insights se po registraci automaticky neaktualizuje.
  • Nakonfigurovali jste agenta (běžícího na své infrastruktuře) tak, aby odesílal stopy do služby Application Insights, a používáte stejný prostředek Application Insights jako váš projekt.
  • Instrumentace splňuje sémantické konvence OpenTelemetry pro generování umělé inteligence.
  • Trasování zahrnuje rozsahy s atributem gen_ai.operation.name="create_agent" a gen_ai.agent.id="<agent-id>" (nebo gen_ai.agent.name="<agent-id>"). V druhém atributu je hodnota "<agent-id>", kterou jste nakonfigurovali během registrace.

Související obsah

  • Last updated on