Rejestrowanie agentów niestandardowych i zarządzanie nimi

Płaszczyzna sterowania Microsoft Foundry zapewnia scentralizowane zarządzanie i obserwowalność dla agentów działających na różnych platformach i w różnych infrastrukturach. Możesz zarejestrować agentów niestandardowych — działających w usługach obliczeniowych platformy Azure lub innych środowiskach w chmurze — aby uzyskać wgląd w ich operacje i kontrolować ich zachowanie.

W tym artykule przedstawiono sposób rejestracji niestandardowego agenta w płaszczyźnie sterowania Foundry. Dowiesz się, jak skonfigurować agenta do rejestracji, skonfigurować zbieranie danych telemetrycznych i korzystać z możliwości zarządzania płaszczyzny sterowania.

Wymagania wstępne

Przed rozpoczęciem upewnij się, że masz następujące elementy:

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

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

• Narzędzie Foundry używa usługi Azure API Management do rejestrowania agentów jako interfejsów API. Skonfiguruj bramę AI w zasobie Foundry.

• Agent wdrażany i uwidaczniany za pośrednictwem dostępnego punktu końcowego (publiczny punkt końcowy lub punkt końcowy osiągalny z sieci, w której wdrażasz zasób Foundry).

Dodawanie agenta niestandardowego

Agent niestandardowy można zarejestrować na płaszczyźnie sterowania. Opracuj agenta w technologii swojego wyboru, obejmując zarówno rozwiązania platformowe, jak i infrastrukturalne.

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

Podczas rejestrowania agenta niestandardowego wynikowa architektura jest następująca:

Zweryfikuj swojego agenta

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

Przygotowywanie projektu Foundry

Agenci niestandardowi są dodawani do projektów Foundry. Przed zarejestrowaniem agenta upewnij się, że projekt został poprawnie skonfigurowany.

1. Zaloguj się do usługi 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. Wybierz pozycję Obsługa>.

   2. Otwórz kartę Brama sztucznej inteligencji .

   3. Na stronie wymieniono wszystkie wrota AI skonfigurowane i przypisane do zasobu Foundry. Sprawdź, czy zasób 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 ma jej na liście), dodaj ją za pomocą opcji Dodaj bramę sztucznej inteligencji. Bramka AI jest darmowa w konfiguracji i odblokowywaniu zaawansowanych funkcji zarządzania, takich jak zabezpieczenia, telemetria oraz ograniczenia tempa przetwarzania dla agentów, narzędzi i modeli.

   5. Aby uzyskać więcej informacji na temat konfigurowania bramy sztucznej inteligencji, zobacz Tworzenie bramy sztucznej inteligencji.

3. Upewnij się, że w projekcie skonfigurowano możliwość obserwowania. Płaszczyzna sterowania używa zasobu usługi Azure Application Insights skojarzonego z wybranym projektem do emitowania danych telemetrycznych, aby ułatwić diagnozowanie agenta:

   1. Wybierz pozycję Obsługa>.

   2. W obszarze Wszystkie projekty użyj pola wyszukiwania, aby wyszukać projekt.

   3. Wybierz projekt.

   4. Wybierz kartę Połączone zasoby.

   5. Upewnij się, że istnieje zasób skojarzony z kategorią Application Insights.

      

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

   7. Projekt jest skonfigurowany do obserwowania i śledzenia.

Rejestrowanie agenta

Aby zarejestrować agenta, wykonaj następujące kroki:

1. Wybierz pozycję Obsługa w prawym górnym rogu nawigacji.

2. Wybierz okienko Przegląd .

3. Wybierz Zarejestruj agenta.

   

4. Zostanie wyświetlony kreator rejestracji. Najpierw wypełnij szczegółowe informacje o agencie, który chcesz zarejestrować. Poniższe właściwości opisują agenta uruchomionego na swojej platformie

   Majątek	Description	Wymagane
   Adres URL agenta	Reprezentuje 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 komunikuje się z interfejsem API uzupełniania czatów OpenAI, wskazujesz https://<host>/v1/ - bez /chat/completions jako że klienci zwykle go dodają.	Tak
   Protocol	Protokół komunikacyjny obsługiwany przez agenta. Użyj protokołu HTTP ogólnie lub jeśli agent obsługuje bardziej szczegółowo A2A, wskaż to.	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.	Nie.
   Identyfikator agenta OpenTelemetry	Identyfikator agenta, którego twój agent używa do emitowania śladów zgodnie z konwencjami semantycznymi OpenTelemetry Generative AI. Ślady wskazują to w atrybucie gen_ai.agents.id dla zakresów z nazwą operacji create_agent. Jeśli tego nie określisz, system używa wartości nazwa agenta do znajdowania ś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ść w celu ułatwienia dostępu. Usługa Foundry nie ma dostępu do bezpośredniego wykonywania operacji w takim portalu zarządzania.	Nie.

5. Następnie skonfiguruj sposób wyświetlania agenta na płaszczyźnie sterowania:

   Majątek	Description	Wymagane
   Projekt	Projekt, w którym rejestrujesz agenta. Usługa Foundry używa bramy sztucznej inteligencji skonfigurowanej w zasobie, w którym znajduje się projekt w celu skonfigurowania przychodzącego punktu końcowego do agenta. Można wybierać tylko projekty, które mają w swoich zasobach włączoną bramę sztucznej inteligencji. Jeśli nie widzisz żadnych, skonfiguruj bramę sztucznej inteligencji w zasobie usługi Foundry. Zaleca się również skonfigurowanie usługi Azure Application Insights w wybranym projekcie. Narzędzie Foundry używa zasobu Azure Application Insights projektu do rejestrowania śladów i logów.	Tak
   Nazwa agenta	Nazwa agenta, jaką chcesz, aby pojawiała się w Foundry. System może również użyć tej nazwy, aby znaleźć odpowiednie ślady i dzienniki w usłudze Azure Application Insights, jeśli nie określisz innej wartości w polu Identyfikator agenta OpenTelemetry.	Tak
   Opis	Jasny opis tego agenta.	Nie.

6. Zapisz zmiany.

7. Usługa Foundry dodaje nowego agenta. Wybierz kartę Zasoby w okienku po lewej stronie, aby sprawdzić listę agentów.

8. 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. Narzędzie Foundry działa jak serwer proxy dla komunikacji z twoim agentem, co pozwala kontrolować dostęp i monitorować aktywność.

Aby udostępnić nowy adres URL dla swoich klientów, aby wywołali agenta:

1. Wybierz agenta niestandardowego przy użyciu selektora radiowego.

2. Na panelu szczegółów po prawej stronie w obszarze Adres URL agenta wybierz opcję kopiowania.

   

3. Użyj nowego adresu URL, aby wywołać agenta zamiast oryginalnego punktu końcowego.

W tym przykładzie wdrożysz agenta LangGraph, a klienci korzystają z LangGraph SDK do jego obsługi. 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.

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)

Oczekiwane dane wyjściowe: agent przetwarza komunikat i przesyła strumieniowo odpowiedzi jako fragmenty. Każdy fragment zawiera częściowe wyniki wykonania agenta, które 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 infrastruktury bazowej, gdzie działa agent, dlatego operacje uruchamiania i zatrzymywania nie są dostępne. Jednak usługa Foundry może blokować przychodzące żądania do agenta, uniemożliwiając klientom korzystanie z niego. Ta funkcja umożliwia administratorom wyłączenie agenta, jeśli działa nieprawidłowo.

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

1. Wybierz pozycję Obsługa w prawym górnym rogu nawigacji.

2. Wybierz pozycję Zasoby w okienku po lewej stronie.

3. Wybierz agenta, który chcesz zablokować. Zostanie wyświetlony panel informacji.

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

   

5. Potwierdź operację.

Po zablokowaniu agenta stan agenta w narzędziu Foundry jest wyświetlany jako Zablokowany. 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łączanie telemetrii agenta

Usługa Foundry używa otwartego standardu OpenTelemetry, aby zrozumieć, co robią agenci. Jeśli projekt ma skonfigurowaną usługę Azure Application Insights, usługa Foundry domyślnie rejestruje żądania w usłudze Azure Application Insights. Ta telemetria jest również używana do obliczania:

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

Aby uzyskać najlepszy poziom wierności, Foundry oczekuje, że agenci niestandardowi będą zgodni z konwencjami semantycznymi dla rozwiązania AI generatywnej w standardzie OpenTelemetry.

Wyświetlanie przebiegów i śladów

Możesz wyświetlić ślady i dzienniki wysyłane do usługi Foundry. Aby je wyświetlić:

1. Wybierz pozycję Obsługa w prawym górnym rogu nawigacji.

2. Wybierz pozycję Zasoby w okienku po lewej stronie.

3. Wybierz agenta.

4. Wyświetlane są sekcje Ślady .

5. Zostanie wyświetlony jeden wpis dla każdego wywołania HTTP wykonanego do punktu końcowego agenta.

6. 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.

7. Zwróć uwagę, że w tym przykładzie nie ma dalszych szczegółów oprócz wpisu HTTP w śladzie. Wynika to z faktu, że do kodu agenta nie dodano dodatkowej instrumentacji. Zapoznaj się z następną sekcją, aby dowiedzieć się, jak instrumentować kod i uzyskać więcej szczegółów, takich jak wywołania narzędzi, wywołania LLM itp.

Instrumentacja niestandardowych agentów kodu

Jeśli tworzysz agenta przy użyciu kodu niestandardowego, musisz przygotować swoje rozwiązanie do emitowania śladów zgodnie ze standardem OpenTelemetry i przesyłać je do usługi Azure Application Insights. Instrumentacja umożliwia narzędziu Foundry dostęp do wyższego poziomu szczegółów dotyczących działania agenta.

Wysyłaj ślady do zasobu Azure Application Insights w swoim projekcie, używając jego klucza instrumentacji. Aby uzyskać klucz instrumentacji skojarzony z projektem, postępuj zgodnie z instrukcjami w temacie Włączanie śledzenia w projekcie.

W tym przykładzie skonfigurujesz agenta opracowanego za pomocą biblioteki LangGraph, aby emitować ślady w standardzie OpenTelemetry. Narzędzie tracer przechwytuje wszystkie operacje agenta, w tym wywołania narzędzi i interakcje modelu, i wysyła je do usługi Azure Application Insights w celu monitorowania.

Ten kod używa pakietu langchain-azure-ai . Dowiedz się, jak instrumentować konkretne rozwiązania za pomocą biblioteki OpenTelemetry w zależności od języka programowania i platformy używanej w rozwiązaniu w temacie 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 Azure 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.

Instrumentacja rozwiązań platformy

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

Skonfiguruj kolektor za pomocą eksportera usługi Azure Monitor, aby przekazywać dane do usługi Application Insights przy użyciu ciągu połączenia. Aby uzyskać szczegółowe informacje na temat implementowania, zobacz Konfigurowanie usługi Azure Monitor OpenTelemetry.

Rozwiązywanie problemów ze śladami

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

Treści powiązane

• Co to jest płaszczyzna sterowania rozwiązania Microsoft Foundry?
• Monitorowanie agentów w całej Twojej flocie
• Optymalizowanie kosztów i wydajności floty agentów