注册外部智能体以进行可观测性与评估（预览）

pip install "microsoft-opentelemetry[langchain]"

import os

os.environ.setdefault("AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING", "true")
os.environ.setdefault("OTEL_SEMCONV_STABILITY_OPT_IN", "gen_ai_latest_experimental")
os.environ.setdefault("OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT", "SPAN_AND_EVENT")

from microsoft.opentelemetry import use_microsoft_opentelemetry

# Human-readable name for the agent
AGENT_NAME = os.environ.get("AGENT_NAME", "weather-agent")
# Unique ID emitted as gen_ai.agent.id on every span.
# Foundry matches traces to registrations by this value.
OTEL_AGENT_ID = os.environ.get("OTEL_AGENT_ID", f"{AGENT_NAME}-v1")

use_microsoft_opentelemetry(
    enable_azure_monitor=True,
    azure_monitor_connection_string=os.environ["APPLICATIONINSIGHTS_CONNECTION_STRING"],
    sampling_ratio=1.0,
    instrumentation_options={
        "fastapi": {"enabled": False},
        "langchain": {
            "enabled": True,
            "agent_id": OTEL_AGENT_ID,
            "agent_name": AGENT_NAME,
        },
    },
)

from opentelemetry import trace

tracer = trace.get_tracer(__name__)

with tracer.start_as_current_span("agent-run") as span:
    span.set_attribute("gen_ai.agent.id", "travel-planner-agent-v1")
    # ... your agent logic ...

pip install azure-ai-projects>=2.3.0 azure-identity>=1.17.0

import os
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import ExternalAgentDefinition
from azure.identity import DefaultAzureCredential

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

# Create the project client with preview features enabled.
project = AIProjectClient(
    endpoint=endpoint,
    credential=DefaultAzureCredential(),
    allow_preview=True,
)

# Register the externally hosted agent.
agent = project.agents.create_version(
    agent_name="travel-planner-agent",
    description="Travel planning agent hosted externally.",
    definition=ExternalAgentDefinition(
        # Set explicitly when the running agent emits a gen_ai.agent.id
        # value that differs from the Foundry agent name.
        otel_agent_id="travel-planner-agent-v1",
    ),
)

print(f"Registered external agent: {agent.name}")
print(f"Resolved otel_agent_id: {agent.versions.latest.definition.otel_agent_id}")

Registered external agent: travel-planner-agent
Resolved otel_agent_id: travel-planner-agent-v1

#pragma warning disable AAIP001
using System;
using Azure.AI.Projects.Agents;
using Azure.Identity;

var endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");

// External agents are in preview. The AAIP001 pragma opts in to the preview surface.
AgentAdministrationClient agentsClient = new(
    endpoint: new Uri(endpoint),
    tokenProvider: new DefaultAzureCredential());

// Register the externally hosted agent.
ExternalAgentDefinition definition = new()
{
    // Set explicitly when the running agent emits a gen_ai.agent.id
    // that differs from the Foundry agent name.
    OtelAgentId = "travel-planner-agent-v1",
};
ProjectsAgentVersionCreationOptions options = new(definition)
{
    Description = "Travel planning agent hosted externally.",
};
ProjectsAgentVersion agent = agentsClient.CreateAgentVersion(
    agentName: "travel-planner-agent",
    options: options,
    // Create and update requests require the ExternalAgents preview feature.
    foundryFeatures: "ExternalAgents=V1Preview");

Console.WriteLine($"Registered external agent: {agent.Name}");

Registered external agent: travel-planner-agent

npm install @azure/ai-projects @azure/identity

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint =
  process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint>";

const project = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);

const agentName = "travel-planner-agent";
// Set explicitly when the running agent emits a gen_ai.agent.id value
// that differs from the Foundry agent name.
const otelAgentId = "travel-planner-agent-v1";

// Register the externally hosted agent. External agents are a preview
// feature, so the `ExternalAgents=V1Preview` opt-in is required.
const agent = await project.agents.createVersion(
  agentName,
  {
    kind: "external",
    otel_agent_id: otelAgentId,
  },
  {
    foundryFeatures: "ExternalAgents=V1Preview",
    description: "Travel planning agent hosted externally.",
  },
);

console.log(`Registered external agent: ${agent.name}`);
console.log(`Resolved otel_agent_id: ${otelAgentId}`);

Registered external agent: travel-planner-agent
Resolved otel_agent_id: travel-planner-agent-v1

# Retrieve the registered agent and its resolved otel_agent_id.
agent = project.agents.get(agent_name="travel-planner-agent")
otel_agent_id = agent.versions.latest.definition.otel_agent_id

#pragma warning disable AAIP001
// Retrieve the registered agent and its resolved otel_agent_id.
ProjectsAgentRecord agent = agentsClient.GetAgent("travel-planner-agent");
if (agent.Versions.Latest.Definition is not ExternalAgentDefinition definition)
{
    throw new InvalidOperationException("Expected an external agent definition.");
}

string otelAgentId = definition.OtelAgentId;

// Retrieve the registered agent and its resolved otel_agent_id.
const agent = await project.agents.get("travel-planner-agent");
const definition = agent.versions.latest.definition;
if (definition.kind !== "external") {
  throw new Error(
    `Expected an external agent definition, got "${definition.kind}".`,
  );
}
const otelAgentId = definition.otel_agent_id;

agents = project.agents.list(kind="external")
for a in agents:
    print(a.name)

#pragma warning disable AAIP001
foreach (ProjectsAgentRecord agent in agentsClient.GetAgents(kind: ProjectsAgentKind.External))
{
    Console.WriteLine(agent.Name);
}

const agents = project.agents.list({ kind: "external" });
for await (const agent of agents) {
  console.log(agent.name);
}

# Delete the registration. This does not affect the running agent.
# force=True removes all internal revisions of the agent atomically.
project.agents.delete(agent_name="travel-planner-agent", force=True)

#pragma warning disable AAIP001
// Delete the registration. This action doesn't affect the running agent.
// force: true removes all internal revisions of the agent atomically.
agentsClient.DeleteAgent(agentName: "travel-planner-agent", force: true);

// Delete the registration. This does not affect the running agent.
// force: true removes all internal revisions of the agent atomically.
await project.agents.delete("travel-planner-agent", { force: true });