Sdílet prostřednictvím

Registrace a správa vlastních agentů

Řídicí rovina Microsoft Foundry poskytuje centralizovanou správu a pozorovatelnost 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 provést registraci vlastního agenta v řídicí rovině Foundry. Dozvíte se, jak nakonfigurovat agenta pro registraci, nastavit shromažďování dat a používat funkce správy řídicí roviny Foundry.

Předpoklady

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

  • Agent, kterého nasadíte a zveřejní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ý). Vyhledejte v banneru portálu pro potvrzení, že používáte Foundry (nový).

Přidání vlastního agenta

Svého agenta můžete zaregistrovat ve Foundry Control Plane. 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 access 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 zdroj Foundry, může dosáhnout na endpoint 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 zaregistrování agenta vygeneruje řídicí rovina systému Foundry 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 project Foundry, ujistěte se, že jste správně nakonfigurovali project:

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

  2. Ujistěte se, že je ve vašem project nakonfigurovaná brána AI:

    1. Na panelu nástrojů vyberte Operace.

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

    3. Otevřete panel 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.

      Screenshot portálu pro správu Foundry, který ukazuje, jak ověřit, zda je pro projekt nakonfigurována AI brána.

    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 jste v projektu nakonfigurovali pozorovatelnost. Řídicí rovina Foundry používá prostředek Application Insights přidružený k vybranému projektu pro generování dat a pomoci vám tak 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 project pomocí vyhledávacího pole.

    4. Vyberte project.

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

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

      Screenshot portálu pro správu, který ukazuje postup ověření, jestli má project 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.

Vaše projekt je nakonfigurovaný pro pozorovatelnost a trasování.

Zaregistrujte agenta

  1. Na panelu nástrojů vyberte Operace.

  2. V podokně Přehled vyberte Zaregistrovat agenta.

    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 při jeho spuštění na své vlastní platformě:

    Vlastnictví Description Povinné
    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, uvedete https://<host>/v1/ bez /chat/completions, protože je klienti obvykle přidávají. Ano
    Protocol 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 ke specifikaci JSON karty agenta. Pokud ho nezadáte, použije systém výchozí /.well-known/agent-card.jsonhodnotu . Ne
    ID agenta OpenTelemetry ID agenta, které váš agent používá k vytváření tras podle sémantických konvencí OpenTelemetry pro generativní AI. Trasování to označuje v atributu gen_ai.agents.id u úseků 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á žádný přístup k provádění operací přímo na tomto portálu. Ne

  4. Nakonfigurujte, jak se má agent zobrazovat v řídicí rovině Foundry:

    Vlastnictví Description Povinné
    Project Projekt, ve kterém zaregistrujete agenta. 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 jenom projekty u kterých je aktivovaná brána 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 project. Foundry používá prostředek Application Insights projektu ke zaznamenávání tras a logů. 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
    Description Jasný popis tohoto agenta. Ne

  5. Uložte změny.

  6. Foundry přidá nového agenta. Pokud chcete zkontrolovat seznam agentů, vyberte v levém podokně 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 access a monitorovat aktivitu.

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

  1. Vyberte vlastního agenta.

  2. V podokně podrobností 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.

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)

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 infrastruktuře, na které agent běží, takže operace spuštění a zastavení nejsou dostupné. 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 agenta, kterého chcete blokovat. Zobrazí se informační podokno.

  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.

Povolte diagnostická data pro agenta

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

  • Runs
  • 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. Vyberte agenta.

  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 volání ke koncovému bodu agenta v rámci trasy pro běhy a streamy.

    Návod

    V tomto příkladu vidíte, jak klienti používají koncový bod nového agenta ke komunikaci s agentem. Příklad ukazuje agenta využívajícího protokol agenta z 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).

Instrumentace vlastních agentů kódu

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 pomocí jazyka LangGraph pro generování trasová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 instrumentujte 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 generování trasování OpenTelemetry do Application Insights. Stopy zahrnují názvy operací, doby trvání, volání modelu, vyvolání nástrojů a využití tokenů. Tyto stopy můžete zobrazit na portálu Foundry v sekci Trasování.

Návod

Můžete předat připojovací řetězec do Application Insights pomocí environmentální proměnné APPLICATIONINSIGHTS_CONNECTION_STRING.

Řešení pro platformy přístrojů

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 pomocí exportéru Azure Monitor pro posílání dat do Application Insights pomocí vašeho připojovacího řetězce. Podrobnosti o tom, jak jej implementovat, viz Konfigurování Azure Monitor OpenTelemetry.

Odstraňování problémů se záznamy

Pokud nevidíte stopy, zkontrolujte následující body:

  • Projekt, kde zaregistrujete svého 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 (spuštěný na jeho infrastruktuře) tak, aby odesílal trasování do Application Insights a používáte stejný prostředek Application Insights, který používá váš project.
  • Instrumentace splňuje sémantické konvence OpenTelemetry pro generování umělé inteligence.
  • Sledování zahrnuje rozsahy s atributy operation="create_agent" a gen_ai.agents.id="<agent-id>" (nebo gen_ai.agents.name="<agent-id>"). V druhém atributu je hodnota "<agent-id>", kterou jste nakonfigurovali během registrace.

Související obsah

  • Last updated on