Migruj agentów niestandardowych do agentów zewnętrznych

Zarejestruj istniejącego agenta niestandardowego jako agenta zewnętrznego w usłudze Microsoft Foundry przy użyciu tego samego identyfikatora agenta OpenTelemetry. Zachowaj jego środowisko uruchomieniowe, bramę Azure API Management, adres URL wywołania, uwierzytelnianie i zasady bez zmian.

Rejestracja agenta zewnętrznego łączy dane telemetryczne agenta z usługą Foundry. Nie wdraża środowiska uruchomieniowego, nie zmienia API Management ani nie zastępuje istniejących mechanizmów sterowania bramą.

Prerequisites

• Istniejący agent niestandardowy zarejestrowany w Foundry Control Plane.

• Ten sam projekt usługi Foundry i połączony zasób usługi Application Insights, którego używasz do śladów agenta niestandardowego.

• Instrumentacja agenta, która generuje atrybut gen_ai.agent.id.

• Python 3.11 lub nowszy.

• Program PowerShell i Azure CLI. Uruchom polecenia w tym artykule w tej samej sesji programu PowerShell.

• Do zarejestrowania agenta zewnętrznego jest wymagana rola Użytkownika usługi Foundry w projekcie.

• Rola Czytelnik lub Czytelnik monitorowania w połączonym zasobie usługi Application Insights jest wymagana do wyświetlania śladów.

  Important

  Niedawno zmieniono nazwy ról RBAC w usłudze Foundry. Użytkownik Foundry, właściciel Foundry, właściciel konta Foundry i menedżer projektu Foundry były wcześniej nazywane odpowiednio użytkownikiem Azure AI, właścicielem Azure AI, właścicielem konta Azure AI i menedżerem projektu Azure AI. Poprzednie nazwy mogą być nadal widoczne w niektórych miejscach, podczas gdy zmiana nazwy jest wdrażana. Identyfikatory ról i uprawnienia podstawowe są niezmienione przez zmianę nazwy.

Przejdź do katalogu zawierającego projekt Foundry:

az login

Pobierz istniejący identyfikator agenta OpenTelemetry

Zachowaj dokładnie istniejący gen_ai.agent.id. Nie generuj nowego identyfikatora ani nie zastępuj nazwy, nazwy wyświetlanej ani identyfikatora zasobu interfejsu API Management.

1. Otwórz widok śledzenia istniejącego agenta niestandardowego w narzędziu Foundry i wybierz niedawny ślad.

2. Wybierz element span agenta i skopiuj jego atrybut gen_ai.agent.id.

3. Ustaw skopiowaną wartość w sesji programu PowerShell:

   $env:OTEL_AGENT_ID = "<gen_ai.agent.id-from-the-trace>"
   

Jeśli brakuje atrybutu, przed kontynuowaniem sprawdź instrumentację uruchomionego agenta. Aby uzyskać informacje o konfiguracji śledzenia, zobacz Konfigurowanie śledzenia w narzędziu Foundry.

Zarejestruj agenta zewnętrznego

Zainstaluj zestaw SDK i ustaw punkt końcowy projektu Foundry, a nie bramę lub adres URL zaplecza. Zachowaj OTEL_AGENT_ID bez zmian.

python -m pip install "azure-ai-projects>=2.3.0" azure-identity

$env:FOUNDRY_PROJECT_ENDPOINT = "https://<resource>.services.ai.azure.com/api/projects/<project>"

Zapisz następujący kod jako register_external_agent.py. Zastąp travel-planner nieużywaną nazwą agenta Foundry. Zestaw SDK używa logowania do Azure CLI, a allow_preview=True włącza podgląd agenta zewnętrznego.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ExternalAgentDefinition
from azure.identity import AzureCliCredential

with AIProjectClient(
    endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
    credential=AzureCliCredential(),
    allow_preview=True,
) as project_client:
    registered = project_client.agents.create_version(
        agent_name="travel-planner",
        description="Travel planner hosted outside Foundry.",
        definition=ExternalAgentDefinition(
            otel_agent_id=os.environ["OTEL_AGENT_ID"],
        ),
    )
    saved = project_client.agents.get_version(
        agent_name=registered.name,
        agent_version=registered.version,
    )
    print(f"Registered agent: {saved.name}")
    print(f"OpenTelemetry agent ID: {saved.definition.otel_agent_id}")

Informacje referencyjne: AIProjectClient, ExternalAgentDefinition, AgentsOperations i AzureCliCredential.

Uruchom skrypt:

python register_external_agent.py

Dane wyjściowe zwracają zachowany identyfikator telemetrii, na przykład:

Registered agent: travel-planner
OpenTelemetry agent ID: com.contoso.travel-planner

Jeśli nazwa już istnieje, create_version tworzy inną wersję rejestracji zamiast oddzielnego agenta.

Te przykłady dotyczą publicznej chmury Azure. W przypadku innej chmury użyj punktu końcowego Foundry i ustawień uwierzytelniania SDK obsługiwanych przez tę chmurę.

Sprawdź wywołania i ślady

Wyślij normalne żądanie za pomocą tego samego adresu URL bramy i uwierzytelniania , jak poprzednio. Potwierdź, że:

• Ten agent nadal odpowiada jak wcześniej.
• Odczyt zestawu SDK przedstawia istniejący identyfikator telemetrii.
• Nowe ślady są wyświetlane pod agentem zewnętrznym w narzędziu Foundry.

Zachowaj oryginalną rejestrację niestandardowego agenta i interfejs API usługi API Management. Rejestracja agenta zewnętrznego nie pośredniczy w ruchu ani nie zapewnia blokowania opartego na bramie; istniejąca brama nadal obsługuje wywołania.

Rozwiąż problemy z brakującymi śladami

Sprawdź projekt, połączony zasób usługi Application Insights, dokładny identyfikator telemetrii, zakres czasu, próbkowanie i opóźnienie pozyskiwania danych. Rejestracja nie tworzy śladów ani nie kopiuje historycznych danych telemetrycznych.

W usłudze Application Insights w sekcji Logs zastąp przykładowy identyfikator wartością skopiowaną ze śledzenia:

union requests, dependencies
| where ['timestamp'] > ago(30m)
| where tostring(['customDimensions']['gen_ai.agent.id'])
    == "com.contoso.travel-planner"
| project ['timestamp'], ['name'], ['operation_Id'],
    ['otelAgentId'] = tostring(['customDimensions']['gen_ai.agent.id'])
| order by ['timestamp'] desc
| take 20

Spany agenta mogą znajdować się w elemencie requests lub dependencies. Pasujący wiersz potwierdza import i tożsamość. Upewnij się również, że ślad jest widoczny pod agentem zewnętrznym w narzędziu Foundry.

Treści powiązane

• Zarejestruj agentów zewnętrznych w celu monitorowania i oceny.
• Zarządzaj istniejącymi niestandardowymi agentami.
• Skonfiguruj śledzenie w Foundry.