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. Możesz zarejestrować agentów niestandardowych uruchamianych w usługach obliczeniowych Azure lub innych środowiskach w chmurze, aby uzyskać wgląd w ich operacje i kontrolować ich zachowanie.

W tym artykule pokazano, jak zarejestrować agenta niestandardowego w systemie Foundry Control Plane. Dowiesz się, jak skonfigurować agenta do rejestracji, skonfigurować zbieranie danych i korzystać z możliwości zarządzania płaszczyzny sterowania platformy Foundry.

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.

• Gateway AI skonfigurowany w zasobie Foundry. Usługa Foundry używa Azure API Management do rejestrowania agentów jako interfejsów API.

• Agent, który wdrażasz i uwidaczniasz za pośrednictwem dostępnego punktu końcowego. Punkt końcowy może być publicznym punktem końcowym lub punktem końcowym dostępnym z sieci, w której wdrażasz zasób foundry.

Dodawanie agenta niestandardowego

Można zarejestrować niestandardowego agenta w Foundry Control Plane. Opracuj agenta w wybranej technologii zarówno dla rozwiązań platformy, jak i infrastruktury.

Podczas rejestrowania agenta niestandardowego narzędzie Foundry używa usługi API Management do działania jako serwer proxy komunikacji z agentem, dzięki czemu może kontrolować dostęp i monitorować aktywność.

Na poniższym diagramie przedstawiono wynikową architekturę podczas rejestrowania agenta niestandardowego.

Zweryfikuj swojego agenta

Sprawdź, czy agent spełnia wymagania dotyczące rejestracji:

Przygotowywanie projektu Foundry

Przed zarejestrowaniem agenta niestandardowego dodanego do projektu Foundry upewnij się, że projekt został poprawnie skonfigurowany:

1. Zaloguj się do Microsoft Foundry. Upewnij się, że przełącznik New Foundry jest włączony. Te kroki dotyczą rozwiązania Foundry (nowy).

   

2. Upewnij się, że brama sztucznej inteligencji jest skonfigurowana w projekcie:

   1. Na pasku narzędzi wybierz pozycję Zarządzaj.

   2. W okienku po lewej stronie wybierz pozycję Brama sztucznej inteligencji.

   3. W panelu skonfigurowano i przypisano do zasobu Foundry wszystkie bramy sztucznej inteligencji. Sprawdź, czy zasób usługi Foundry, którego chcesz użyć, ma skojarzoną bramę sztucznej inteligencji.

      

   4. Jeśli zasób Foundry, którego chcesz użyć, nie ma skonfigurowanej bramy sztucznej inteligencji (nie jest wymieniony na liście), dodaj korzystając z opcji Dodaj bramę AI.

      Bramę sztucznej inteligencji można bezpłatnie skonfigurować i odblokować zaawansowane funkcje zarządzania, takie jak bezpieczeństwo, dane diagnostyczne i limity częstotliwości dla agentów, narzędzi i modeli. Aby uzyskać więcej informacji, zobacz Tworzenie bramy sztucznej inteligencji.

3. Upewnij się, że w projekcie skonfigurowano możliwość obserwacji. Płaszczyzna sterowania Foundry wykorzystuje zasób Application Insights powiązany z wybranym projektem do przesyłania danych w celu ułatwienia diagnozowania agenta.

   1. Na pasku narzędzi wybierz pozycję Zarządzaj.

   2. W lewym panelu wybierz Project details.

   3. Wybierz kartę Połączone zasoby .

   4. Upewnij się, że w kategorii AppInsights istnieje skojarzony zasób.

      

   5. Jeśli nie ma skojarzonego zasobu, dodaj go, wybierając pozycję Dodaj połączenie>Application Insights.

Projekt jest skonfigurowany do obserwowania i śledzenia.

Rejestrowanie agenta (zasób)

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

2. W okienku Przegląd wybierz pozycję Zarejestruj zasób.

   

3. Zostanie wyświetlony kreator rejestracji. Najpierw wypełnij szczegółowe informacje o agencie, który chcesz zarejestrować. Następujące właściwości opisują działanie agenta na jego platformie:

   Właściwość	Opis	Wymagane
   Adres URL agenta	Punkt końcowy (adres URL), w którym agent uruchamia i odbiera żądania. Ogólnie rzecz biorąc, ale w zależności od protokołu wskazujesz podstawowy adres URL używany przez klientów. Jeśli na przykład agent używa interfejsu API uzupełniania czatów OpenAI, wskazujesz https://<host>/v1/ bez /chat/completions, ponieważ klienci zazwyczaj dodają go sami.	Tak
   Protokół	Protokół komunikacyjny, który obsługuje agent. Użyj protokołu HTTP w ogóle. Lub jeśli agent obsługuje usługę A2A bardziej szczegółowo, wskaż ten agent.	Tak
   Adres URL karty agenta A2A	Ścieżka do specyfikacji JSON karty agenta. Jeśli go nie określisz, system używa wartości domyślnej /.well-known/agent-card.json.	Tak, gdy protokół to A2A
   Identyfikator agenta OpenTelemetry	Identyfikator agenta, który twój agent używa do emitowania śladów zgodnie z semantycznymi konwencjami OpenTelemetry dla generatywnej sztucznej inteligencji. Ślady wskazują na to w atrybucie gen_ai.agent.id dla zakresów z nazwą operacji create_agent. Jeśli nie określisz tej wartości, system użyje wartości nazwa agenta do znalezienia śladów i dzienników, które zgłasza ten nowy agent.	Nie
   Adres URL portalu administracyjnego	Adres URL portalu administracyjnego, w którym można wykonywać dalsze operacje administracyjne dla tego agenta. Funkcja Foundry może przechowywać tę wartość dla wygody. Usługa Foundry nie ma dostępu do wykonywania operacji bezpośrednio w tym portalu.	Nie

4. Skonfiguruj, jak chcesz, aby agent był widoczny w Foundry Control Plane.

   Właściwość	Opis	Wymagane
   Project	Projekt, w którym rejestrujesz agenta. Narzędzie Foundry używa bramy AI skonfigurowanej w zasobie, który zawiera projekt, aby skonfigurować punkt końcowy przychodzący do agenta. Możesz wybrać tylko projekty z włączoną bramą sztucznej inteligencji w swoich zasobach. Jeśli nie widzisz żadnych bram sztucznej inteligencji, skonfiguruj bramę sztucznej inteligencji w zasobie usługi Foundry. Zalecamy również skonfigurowanie usługi Application Insights w wybranym projekcie. Narzędzie Foundry używa zasobu usługi Application Insights projektu do przesyłania śladów i dzienników.	Tak
   Nazwa agenta	Nazwa agenta, jak ma się wyświetlać w narzędziu Foundry. System może również używać tej nazwy do znajdowania odpowiednich śladów i dzienników w usłudze Application Insights, jeśli nie określisz innej wartości dla identyfikatora agenta OpenTelemetry.	Tak
   Opis	Jasny opis tego agenta.	Nie

5. Zapisz zmiany.

6. Usługa Foundry dodaje nowego agenta. Aby sprawdzić listę agentów, wybierz pozycję Zasoby w okienku po lewej stronie.

7. Aby wyświetlić tylko agentów niestandardowych, użyj filtru Źródła i wybierz pozycję Niestandardowe.

   

Łączenie klientów z agentem

Po zarejestrowaniu agenta w narzędziu Foundry otrzymasz nowy adres URL używany przez klientów. Ponieważ narzędzie Foundry działa jako serwer proxy komunikacji z agentem, może kontrolować dostęp i monitorować aktywność.

Aby rozpowszechnić nowy adres URL, aby klienci mogli wywoływać agenta:

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. Użyj nowego adresu URL, aby wywołać agenta zamiast oryginalnego punktu końcowego.

W tym przykładzie wdrożysz agenta LangGraph. Klienci używają zestawu SDK LangGraph do korzystania z niego. Klient używa nowej wartości adresu URL agenta . 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ść

• Czym jest Microsoft Foundry Control Plane?
• Monitorowanie kondycji i wydajności agentów w całej flocie