Rejestrowanie agentów niestandardowych i zarządzanie nimi

Microsoft Foundry Control Plane zapewnia scentralizowane zarządzanie i obserwowalność agentów działających na różnych platformach i infrastrukturach. W tym artykule opisano zarządzanie i dane diagnostyczne dla istniejących agentów niestandardowych.

Aby zapoznać się z krokami przejścia, zobacz Migrowanie agentów niestandardowych do agentów zewnętrznych.

Wymagania wstępne

• Konto Azure z aktywną subskrypcją. Jeśli go nie masz, utwórz konto free Azure, które obejmuje subskrypcję bezpłatnej wersji próbnej.

• Projekt Foundry. Jeśli go nie masz, utwórz projekt.

• Istniejący agent niestandardowy zarejestrowany na płaszczyźnie sterowania programu Foundry.

• Istniejąca brama sztucznej inteligencji skonfigurowana w zasobie Foundry i dostępny punkt końcowy zaplecza agenta.

Dodawanie agenta niestandardowego

Nie można już dodać nowego agenta niestandardowego w Foundry Control Plane. W przypadku nowej integracji, zarejestruj agenta zewnętrznego. W przypadku istniejącego agenta niestandardowego postępuj zgodnie z przewodnikiem migracji.

Istniejąca architektura agenta niestandardowego

Istniejący agenci niestandardowi używają usługi API Management jako serwera proxy do komunikacji z agentem, dzięki czemu usługa ta może kontrolować dostęp i monitorować aktywność.

Łączenie klientów z agentem

Istniejąca rejestracja agenta niestandardowego ma adres URL bramy do użycia przez klientów. Ponieważ brama działa jako serwer proxy komunikacji z agentem, może kontrolować dostęp i monitorować aktywność. Nadal używaj tego adresu URL podczas migracji do rejestracji agenta zewnętrznego.

Aby znaleźć istniejący adres URL bramy:

1. Na liście agentów wybierz przycisk radiowy obok nazwy agenta niestandardowego, aby otworzyć okienko informacji. Nie wybieraj samej nazwy agenta, ponieważ ten link przechodzi z dala od okienka Zasoby .

2. W okienku informacji w obszarze Adres URL agenta wybierz opcję Kopiuj .

   

3. Nadal używaj tego adresu URL bramy, aby wywołać agenta.

W tym przykładzie klienci używają zestawu SDK LangGraph i istniejącego adresu URL bramy do wywołania agenta LangGraph. Ten kod tworzy wątek, wysyła komunikat z pytaniem o pogodę i przesyła strumieniowo odpowiedź z powrotem.

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())

Oczekiwane dane wyjściowe: agent przetwarza komunikat i przesyła strumieniowo odpowiedzi jako fragmenty. Każdy fragment zawiera częściowe wyniki wykonania przez agenta. Wyniki te mogą obejmować wywołania narzędzi do funkcji pogodowej i ostateczną odpowiedź na temat pogody w Los Angeles.

Blokowanie i odblokowywanie agenta

W przypadku agentów niestandardowych narzędzie Foundry nie ma dostępu do podstawowej infrastruktury, w której działa agent, więc operacje uruchamiania i zatrzymywania nie są dostępne. Jednak usługa Foundry może blokować przychodzące żądania do agenta, aby klienci nie mogli z niego korzystać. Ta funkcja umożliwia administratorom wyłączenie agenta, jeśli działa nieprawidłowo.

Aby zablokować żądania przychodzące do agenta:

1. Na pasku narzędzi wybierz pozycję Obsługa.

2. W okienku po lewej stronie wybierz pozycję Zasoby.

3. Wybierz przycisk radiowy obok agenta, który chcesz zablokować. Zostanie wyświetlone okienko informacji. Nie wybieraj nazwy agenta, ponieważ ten link przechodzi z dala od okienka Zasoby .

4. Wybierz pozycję Aktualizuj stan, a następnie wybierz pozycję Blokuj.

   

5. Potwierdź operację.

Po zablokowaniu agenta wartość Stan agenta w rozwiązaniu Foundry jest zablokowana. Agenci w stanie Zablokowany działają w skojarzonej infrastrukturze, ale nie mogą odbierać żądań przychodzących. Program Foundry blokuje wszelkie próby nawiązania połączenia z agentem.

Aby odblokować agenta:

1. Wybierz pozycję Aktualizuj stan, a następnie wybierz pozycję Odblokuj.

2. Potwierdź operację.

Włącz dane diagnostyczne agenta

Usługa Foundry używa otwartego standardu OpenTelemetry, aby zrozumieć, co robią agenci. Jeśli projekt ma skonfigurowaną usługę Application Insights, program Foundry domyślnie rejestruje żądania do usługi Application Insights. Funkcja Foundry używa również tych danych do obliczenia:

• Uruchamia
• Częstotliwość błędów
• Użycie (jeśli jest dostępne)

Aby uzyskać najlepszy poziom dokładności, Foundry oczekuje, że agenci dedykowani będą zgodni z konwencjami semantycznymi dla rozwiązań generacyjnych AI w standardzie OpenTelemetry.

Wyświetlanie śladów i dzienników wysłanych do usługi Foundry

1. Na pasku narzędzi wybierz pozycję Obsługa.

2. W okienku po lewej stronie wybierz pozycję Zasoby.

3. Wybierz przycisk radiowy obok agenta, aby otworzyć okienko informacji. Nie wybieraj nazwy agenta, ponieważ ten link przechodzi z dala od okienka Zasoby .

4. Sekcja Ślady zawiera jeden wpis dla każdego wywołania HTTP wykonanego do punktu końcowego agenta.

   Aby wyświetlić szczegóły, wybierz wpis.

   

   Wskazówka

   W tym przykładzie można zobaczyć, jak klienci używają punktu końcowego nowego agenta do komunikowania się z agentem. W przykładzie przedstawiono agenta obsługiwanego przy użyciu protokołu agenta z pakietu LangChain. Klienci używają trasy /runs/stream.

W tym przykładzie ślad nie zawiera żadnych szczegółów poza wpisem HTTP. Kod agenta nie zawiera żadnych dalszych instrumentacji. W następnej sekcji dowiesz się, jak instrumentować kod i uzyskiwać szczegółowe informacje, takie jak wywołania narzędzi i wywołania modelu JĘZYKA (LLM).

Instrumentacja niestandardowych agentów kodu

Jeśli tworzysz agenta przy użyciu kodu niestandardowego, instrumentuj rozwiązanie, aby emitować ślady zgodnie ze standardem OpenTelemetry i wysyłać je do usługi Application Insights. Instrumentacja zapewnia narzędziu Foundry dostęp do szczegółowych informacji o tym, co robi agent.

Wysyłaj ślady do zasobu projektu usługi „Application Insights” przy użyciu klucza instrumentacji. Aby uzyskać klucz instrumentacji skojarzony z projektem, postępuj zgodnie z instrukcjami w artykule Łączenie usługi Application Insights z projektem foundry.

W tym przykładzie skonfigurujesz agenta opracowanego za pomocą biblioteki LangGraph, aby emitować ślady w standardzie OpenTelemetry. Narzędzie śledzące przechwytuje wszystkie operacje agenta, w tym wywołania narzędzi i interakcje z modelem. Następnie narzędzie tracer wysyła operacje do usługi Application Insights na potrzeby monitorowania.

Ten kod używa pakietu langchain-azure-ai . Aby uzyskać wskazówki dotyczące instrumentowania określonych rozwiązań za pomocą biblioteki OpenTelemetry, w zależności od języka programowania i struktury używanej przez rozwiązanie, zobacz Interfejsy API języka i zestawy SDK.

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

Następnie skonfiguruj 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] })

Oczekiwane dane wyjściowe: agent działa normalnie podczas automatycznego emitowania śladów OpenTelemetry do usługi Application Insights. Ślady obejmują nazwy operacji, czasy trwania, wywołania modelu, wywołania narzędzi i użycie tokenu. Te ślady można wyświetlić w portalu Foundry w sekcji Ślady .

Rozwiązania platformy instrumentów

Jeśli agent działa w rozwiązaniu platformy, które obsługuje bibliotekę OpenTelemetry, ale nie obsługuje usługi Application Insights, wdróż moduł zbierający OpenTelemetry i skonfiguruj oprogramowanie do wysyłania danych OTLP do modułu zbierającego (standardowa konfiguracja OpenTelemetry).

Skonfiguruj moduł zbierający z użyciem eksportera Azure Monitor, aby przekazywać dane do usługi Application Insights przy użyciu łańcucha znaków połączenia. Aby uzyskać szczegółowe informacje na temat implementacji, zobacz Konfigurowanie Azure Monitor OpenTelemetry.

Rozwiązywanie problemów ze śladami

Jeśli nie widzisz śladów, sprawdź następujące elementy:

Powiązana zawartość

• Migruj agentów niestandardowych do agentów zewnętrznych
• Czym jest Microsoft Foundry Control Plane?
• Monitorowanie kondycji i wydajności agentów w całej flocie