Migrieren zur neuen Agents-Entwicklerumgebung

Tipp

Ein Migrationstool ist verfügbar, um die Migration von der Assistenten-API zu Agents zu automatisieren.

Der Foundry Agent Service bietet eine aktualisierte Entwicklerumgebung zum Erstellen intelligenter Agents, die einfach zu erstellen, versionieren, zu betreiben und zu beobachten sind. Die neue Agents-API führt ein modernisiertes SDK, neue Funktionen auf Unternehmensniveau ein und behält die Identitäts-, Governance- und Observability-Features bei, die Sie heute nutzen.

Voraussetzungen

  • Ein Azure-Abonnement. Erstellen Sie eine kostenlos.
  • Ein Microsoft Foundry-Projekt.
  • Das Foundry Agent Service SDK für Ihre Sprache und das entsprechende Identitätspaket für die Authentifizierung. Installieren Sie die Pakete für Ihre Sprache, und melden Sie sich mit az login oder verwenden Sie DefaultAzureCredentialan:
pip install "azure-ai-projects>=2.0.0"
  • Vorhandener Agenten- oder Assistentencode, den Sie migrieren möchten.

Der folgende Code initialisiert die clients, die in diesem Handbuch verwendet werden:

from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"

project = AIProjectClient(
    endpoint=PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()

Verwenden Sie project für die Agenterstellung und Versionsverwaltung. Verwenden Sie openai (oder die Entsprechung in Ihrer Sprache) für Unterhaltungen und Antworten.

Wichtige Vorteile

Die neuen Agents bieten die folgenden Vorteile:

Entwicklerproduktivität

  • Weitere Modelle. Generieren Sie Antworten, indem Sie entweder ein Foundry-Modell in Ihrem Agenten verwenden oder es direkt als Aufruf zur Antwortgenerierung nutzen.
  • Weitere Features. Websuche, Dateisuche, Codedolmetscher, MCP-Toolaufrufe, Bildgenerierung und Zusammenfassungen von Gründen.
  • Moderner API-Grundtyp. Basiert auf der Antwort-API anstelle der älteren Assistenten-API.
  • Hintergrundmodus. Unterstützung für lang andauernde Werkzeuge (z. B. Bildgenerierung) und dauerhafte Datenströme (unterstützt Szenarien zum Trennen/Wiederverbinden)
  • Zukunftssicher. Neue Features und Modellunterstützung werden nur den neuen Agents hinzugefügt.
  • Neue Agenttypen. Erstellen Sie promptbasierte, workflowbasierte Agents, workflowbasierte Agents (Vorschau) und gehostete Agents (Vorschau).

Unternehmensbereitschaft

  • Single-Tenant-Speicher. Verwenden Sie einen Single-Tenant-Speicher mit der Option, Ihre eigene Azure Cosmos DB zu nutzen, um den Zustand zu speichern und Ihre Daten sicher zu halten.
  • Verbesserte Sicherheit. Steuern, wer Agentdefinitionen ausführen oder ändern kann.
  • Trennung von Aufgaben. Definieren Sie Agenten einmal und führen Sie sie mit verschiedenen Eingaben aus.
  • Bereitstellungsfähige Agenten. Agents können als einzelne Endpunkte verfügbar gemacht werden.

API-Modernisierung

  • Verbesserte Zustandsverwaltung. Verwendet Unterhaltungen anstelle von Threads und Nachrichten.
  • Zustandsbehafteter Kontext. Der Kontext wird automatisch über Anrufe hinweg beibehalten.
  • Übermenge der Antwort-API. Baut auf der Antwort-API auf und fügt weitere Funktionen hinzu.
  • Einzel- oder Multi-Agent-Workflows. Verkette Agenten einfach für komplexe Workflows.

Wichtige Änderungen

In der folgenden Tabelle sind die wichtigsten API-Änderungen zwischen der vorherigen und der aktuellen Agenterfahrung zusammengefasst.

Bevor Nach Details
Threads Gespräche Unterstützt Datenströme von Elementen, nicht nur Nachrichten.
Läuft Antworten Antworten übermitteln Eingabeelemente oder verwenden ein Konversationsobjekt und empfangen Ausgabeelemente. Toolaufrufschleifen werden explizit verwaltet.
Assistent/Agenten Agenten (neue) Unterstützung für unternehmensbereite Prompts, Workflows und gehostete Agents mit speicherfähigem Kontext standardmäßig für jedes Foundry-Modell.

Verfügbarkeit des Agent-Tools

In der folgenden Tabelle werden Agenten-Tools verglichen, die in den klassischen Agents und dem neuen Foundry Agent Service verfügbar sind. Verwenden Sie sie, um zu ermitteln, welche Tools direkt übertragen werden, welche sich geändert haben und welche ausschließlich für die neue Oberfläche gelten.

Werkzeug Gießerei (klassisch) Gießerei (neu)
Agent zu Agent (A2A) Nein Ja (öffentliche Vorschau)
Azure KI-Suche Ja (GA) Ja (GA)
Azure Functions Ja (GA) Nein
Browserautomatisierung Ja (öffentliche Vorschau) Ja (öffentliche Vorschau)
Codedolmetscher Ja (GA) Ja (GA)
Computerverwendung Ja (öffentliche Vorschau) Ja (öffentliche Vorschau)
Verbundene Agents Ja (öffentliche Vorschau) Nein (Empfehlung: Workflow- und A2A-Tool)
Tiefe Forschung Ja (öffentliche Vorschau) Nein (Empfehlung: Deep Research Model with Web Search Tool)
Fabric Data-Agenten Ja (öffentliche Vorschau) Ja (öffentliche Vorschau)
Dateisuche Ja (GA) Ja (GA)
Funktion Ja (GA) Ja (GA)
Grundlagen mit Bing-Suche Ja (GA) Ja (GA)
Erdung durch Bing Custom Search Ja (öffentliche Vorschau) Ja (öffentliche Vorschau)
Bildgenerierung Nein Ja (öffentliche Vorschau)
MCP Ja (öffentliche Vorschau) Ja (GA)
OpenAPI Ja (GA) Ja (GA)
SharePoint Grundlagen Ja (öffentliche Vorschau) Ja (öffentliche Vorschau)
Websuche Nein Ja (GA)

Wichtig

In der neuen API verwenden die Unterhaltungs- und Antwort-APIs den OpenAI-Client (oder dessen Sprachäquivalent). Rufen Sie in Python project.get_openai_client() auf. Verwenden Sie projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent()in C# . Rufen Sie in JavaScript auf projectClient.getOpenAIClient(). Verwenden Sie in Java AgentsClientBuilder, um eine ResponsesClient zu erstellen. Die Agenterstellung und -versionsverwaltung verbleiben auf dem Projektclient. In den Beispielen in den einzelnen Abschnitten wird gezeigt, welcher Client verwendet werden soll.

Migrieren von Threads zu Unterhaltungen

Threads gespeicherte Nachrichten auf serverseitiger Seite. Eine Unterhaltung kann Elemente speichern, einschließlich Nachrichten, Toolaufrufe, Toolausgabe und andere Daten.

Anfragen

In den folgenden Beispielen wird die Erstellung von Threads (früher) mit der Erstellung von Unterhaltungen (aktuell) verglichen. Der aktuelle Ansatz verwendet den OpenAI-Client, der von project.get_openai_client().

Vorherige - Threads

thread = client.agents.threads.create( 
     messages=[{"role": "user", "content": "Tell me a one line funny story about unicorns"}], 
     metadata={"agent": "my-awesome-agent"}, 
) 

Aktuell – Unterhaltungen

conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "Tell me a one line funny "
                       "story about unicorns",
        }
    ],
    metadata={"agent": "my-awesome-agent"},
)

Antworten

Die JSON-Antworten zeigen die strukturellen Unterschiede zwischen Threadobjekten und Unterhaltungsobjekten.

Vorherige - Threads

{ 
  "id": "thread_1234abcd",  
  "object": "thread",  
  "created_at": 1762217858,  
  "metadata": {"agent": "my-awesome-agent"},  
  "tool_resources": {} 
} 

Aktuell – Unterhaltungen

{ 
  "id":"conv_1234abcd", 
  "created_at":1762217961, 
  "metadata":{"agent":"my-awesome-agent"}, 
  "object":"conversation" 
} 

Hinzufügen von Elementen zu einer vorhandenen Unterhaltung

Nachdem Sie eine Unterhaltung erstellt haben, verwenden Sie conversations.items.create(), um nachfolgende Nachrichten hinzuzufügen. Dieses Muster ersetzt das Hinzufügen von Nachrichten zu Threads durch client.agents.messages.create().

Zurück – Hinzufügen einer Nachricht zu einem Thread

message = client.agents.messages.create(
    thread_id=thread.id,
    role="user",
    content="Follow-up question about the same topic",
)

Aktuell – Hinzufügen von Elementen zu einer Unterhaltung

openai.conversations.items.create(
    conversation_id=conversation.id,
    items=[
        {
            "type": "message",
            "role": "user",
            "content": "Follow-up question "
                       "about the same topic",
        }
    ],
)

Migrieren von Ausführungsläufen zu Antworten

Asynchrone Prozesse wurden auf Threads ausgeführt. Antworten sind einfacher: Stellen Sie eine Reihe von Eingabeelementen bereit, die ausgeführt werden können, und rufen Sie eine Liste der Ausgabeelemente zurück. Antworten können allein oder mit Konversationsobjekten zur Speicherung des Kontexts verwendet werden. Die Antwort-API verwendet den OpenAI-Client.

Anfragen

Die folgenden Beispiele vergleichen, wie Sie die Agentlogik aufrufen. Der vorherige Ansatz verwendete asynchrone Ausführung mit Polling. Der aktuelle Ansatz führt responses.create() auf dem OpenAI-Client aus.

Vorherige Läufe

thread_id = "thread_abcd1234" 
assistant_id = "asst_efgh5678" 
run = project_client.agents.runs.create( 
  thread_id=thread_id,  
  agent_id=assistant_id, 
  additional_instructions="Please address the user as Jane Doe. The user has a premium account" 
) 
while run.status in ("queued", "in_progress"): 
  time.sleep(1) 
  run = project_client.agents.runs.get(thread_id=thread_id, run_id=run.id) 

Aktuell – Antworten

conversation_id = "conv_11112222AAAABBBB"

response = openai.responses.create(
    input="Hi, Agent! Draw a graph for a line "
          "with a slope of 4 and "
          "y-intercept of 9.",
    conversation=conversation_id,
    extra_body={
        "agent_reference": {
            "name": "my-agent",
            "type": "agent_reference",
        }
    },
)

Antworten

Vorherige Läufe

{
  "id": "run_xyz",
  "object": "thread.run",
  "created_at": 1762218810,
  "assistant_id": "asst_efgh5678",
  "thread_id": "thread_abcd1234",
  "status": "completed",
  "started_at": 1762218810,
  "expires_at": null,
  "cancelled_at": null,
  "failed_at": null,
  "completed_at": 1762218812,
  "required_action": null,
  "last_error": null,
  "model": "gpt-4.1",
  "instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers. Please address the user as Jane Doe. The user has a premium account",
  "tools": [
    {
      "type": "code_interpreter"
    }
  ],
  "tool_resources": {},
  "metadata": {},
  "temperature": 1.0,
  "top_p": 1.0,
  "max_completion_tokens": null,
  "max_prompt_tokens": null,
  "truncation_strategy": {
    "type": "auto",
    "last_messages": null
  },
  "incomplete_details": null,
  "usage": {
    "prompt_tokens": 1216,
    "completion_tokens": 76,
    "total_tokens": 1292,
    "prompt_token_details": {
      "cached_tokens": 0
    }
  },
  "response_format": "auto",
  "tool_choice": "auto",
  "parallel_tool_calls": true
}

Aktuell – Antworten

{
  "id": "resp_3483e9c8dda4f165006909550333588190afc76a645a0e877a",
  "created_at": 1762219267.0,
  "error": null,
  "incomplete_details": null,
  "instructions": null,
  "metadata": {
    "x-ms-telemetry-agent-kind": "",
    "x-ms-telemetry-user-agent": "OpenAI/Python 2.4.0",
    "x-ms-telemetry-response-start-time": "2025-11-04T01:21:06.5346780+00:00"
  },
  "model": "gpt-4.1",
  "object": "response",
  "output": [
    {
      "id": "msg_3483e9c8dda4f1650069095503abf881909917865574cddf2c",
      "content": [
        {
          "annotations": [],
          "text": "Of course! Here's a simple plot for the line with a rate of change of 4 and a y-intercept of 9.\\n\\nThe equation of the line is:\\n\\n\\\\[ y = 4x + 9 \\\\]\\n\\nLet's draw a graph for it:\\n\\n---\\n\\n```plaintext\\n  |\\n20|                     *\\n  |                  *\\n  |               *\\n  |            *\\n10|         *\\n  |      *\\n  |   *\\n  |*\\n  +---------------------------\\n   -2 -1  0  1  2  3\\n```\\n\\n**Key points:**\\n- The y-intercept is **9**, so at \\\\(x = 0\\\\), \\\\(y = 9\\\\) (point: (0,9))\\n- For each step right (increase in x), y goes up 4 units (rate of change \\\\(m = 4\\\\))\\n  - For \\\\(x = 1\\\\): \\\\(y = 4(1) + 9 = 13\\\\) (point: (1,13))\\n  - For \\\\(x = -1\\\\): \\\\(y = 4(-1) + 9 = 5\\\\) (point: (-1,5))\\n\\nIf you'd like a precise graph or want to visualize it interactively, let me know!",

          "type": "output_text",
          "logprobs": []
        }
      ],
      "role": "assistant",
      "status": "completed",
      "type": "message"
    }
  ],
  "parallel_tool_calls": true,
  "temperature": 1.0,
  "tool_choice": "auto",
  "tools": [],
  "top_p": 1.0,
  "background": false,
  "conversation": {
    "id": "conv_3483e9c8dda4f16500GwcAgtdWlSmbMPzYLjWvDjiSe6LSFcC6"
  },
  "max_output_tokens": null,
  "max_tool_calls": null,
  "previous_response_id": null,
  "prompt": null,
  "prompt_cache_key": null,
  "reasoning": {
    "effort": null,
    "generate_summary": null,
    "summary": null
  },
  "safety_identifier": null,
  "service_tier": "default",
  "status": "completed",
  "text": {
    "format": {
      "type": "text"
    },
    "verbosity": "medium"
  },
  "top_logprobs": 0,
  "truncation": "disabled",
  "usage": {
    "input_tokens": 45,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 264,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 309
  },
  "user": null,
  "content_filters": null,
  "store": true
}

Migrieren klassischer Agents zu neuen Agents

Wenn Sie die client.agents.create_agent() Methode aus früheren SDK-Versionen verwenden, migrieren Sie zu client.agents.create_version(). Mit der neuen Methode werden strukturierte Agentdefinitionen mit expliziten kind, modelund instructions Feldern eingeführt.

Anfragen

Vorherigen

agent = client.agents.create_agent( 
    model="gpt-4.1", 
    name="my-agent",  # Name of the agent 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=code_interpreter.definitions,  # Attach the tool 
) 

Aktuellen

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked to "
            "visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

Antworten

Die folgenden JSON-Beispiele vergleichen die Antwortobjekte, die von den vorherigen und aktuellen Agent-Erstellungsmethoden zurückgegeben werden.

Vorherigen

{ 
  'id': 'asst_AVKrdr2KJthDnZiJ51nca1jy', 
  'object': 'assistant', 
  'created_at': 1762218496, 
  'name': 'my-agent', 
  'description': None, 
  'model': 'gpt-4.1', 
  'instructions': 'You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.', 
  'tools': [ 
    { 
      'type': 'code_interpreter' 
    } 
  ], 
  'top_p': 1.0, 
  'temperature': 1.0, 
  'tool_resources': { 
    'code_interpreter': { 
      'file_ids': [      
      ] 
    } 
  }, 
  'metadata': { 
  }, 
  'response_format': 'auto' 
} 

Aktuellen

{
  "metadata": {},
  "object": "agent.version",
  "id": "code-agent:1",
  "name": "code-agent",
  "version": "1",
  "description": "Agent with code interpreter",
  "created_at": 1772045947,
  "definition": {
    "kind": "prompt",
    "model": "gpt-4.1",
    "instructions": "You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",
    "tools": [
      {
        "type": "code_interpreter"
      }
    ]
  }
}

Migrieren von Assistenten zu neuen Agents

Wenn Ihr Code die OpenAI Assistenten-API (client.beta.assistants.create()) verwendet, migrieren Sie mithilfe des Foundry Agent Service client.agents.create_version(). Die folgenden Beispiele zeigen die strukturellen Unterschiede.

Vorherige - Assistenten

assistant = client.beta.assistants.create( 
    model="gpt-4.1", 
    name="my-assistant", 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=[{"type": "code_interpreter"}], 
) 

Aktuell – neue Agents

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked to "
            "visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

Ausführen des Migrationstools

Ein migrationstool ist auf GitHub verfügbar, um die Migration Ihrer Agents und Assistenten zu automatisieren. Das Tool migriert Codekonstrukte wie Agentdefinitionen, Threaderstellung, Nachrichtenerstellung und Laufzeiterstellung. Zustandsdaten wie vergangene Ausführungen, Threads oder Nachrichten werden nicht migriert. Nach der Migration können Sie den neuen Code ausführen, und alle neuen Statusdaten werden im aktualisierten Format erstellt.

Das folgende Beispiel zeigt einen vollständigen Vor- und Nachher-Vergleich. Beachten Sie, dass der aktuelle Code sowohl project für die Agenterstellung als auch openai für Unterhaltungen und Antworten verwendet wird.

Vorherigen

agent = project_client.agents.create_agent( 
    model="gpt-4.1", 
    name="my-agent", 
    instructions="You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.",  # Instructions for the agent 
    tools=[{"type": "code_interpreter"}] 
) 
thread = project_client.agents.threads.create() 
message = project_client.agents.messages.create( 
    thread_id=thread.id, 
    role="user",  # Role of the message sender 
    content="Hi, Agent! Draw a graph for a line with a rate of change of 4 and y-intercept of 9.",  # Message content 
) 
run = project_client.agents.runs.create_and_process( 
    thread_id=thread.id, 
    agent_id=agent.id, 
    additional_instructions="Please address the user as Jane Doe. The user has a premium account", 
) 
messages = project_client.agents.messages.list(thread_id=thread.id) 
for message in messages: 
    print(f"Role: {message.role}, Content: {message.content}") 

Aktuellen

from azure.ai.projects.models import (
    CodeInterpreterTool,
    PromptAgentDefinition,
)

# Create the agent
agent = project.agents.create_version(
    agent_name="my-agent",
    definition=PromptAgentDefinition(
        model="gpt-4.1",
        instructions=(
            "You politely help with math "
            "questions. Use the Code "
            "Interpreter tool when asked "
            "to visualize numbers."
        ),
        tools=[CodeInterpreterTool()],
    ),
)

# Create a conversation with initial message
conversation = openai.conversations.create(
    items=[
        {
            "type": "message",
            "role": "user",
            "content": (
                "Hi, Agent! Draw a graph "
                "for a line with a rate "
                "of change of 4 and "
                "y-intercept of 9."
            ),
        }
    ],
)

# Send a response with the agent
response = openai.responses.create(
    conversation=conversation.id,
    extra_body={
        "agent_reference": {
            "name": agent.name,
            "type": "agent_reference",
        }
    },
    input=(
        "Please address the user as "
        "Jane Doe. The user has a "
        "premium account"
    ),
)

# Print the response output
for item in response.output:
    if item.type == "message":
        for block in item.content:
            print(block.text)

Überprüfen Sie die Migration

Vergewissern Sie sich, dass alles ordnungsgemäß funktioniert, nachdem Sie Ihren Code migriert haben:

  1. Führen Sie den aktualisierten Code aus , und stellen Sie sicher, dass er ohne Fehler ausgeführt wird.
  2. Überprüfen Sie die Agenterstellung, indem Sie bestätigen, dass create_version() ein Objekt mit einem id und einem version Feld zurückgegeben wird.
  3. Testen Sie eine Unterhaltung , indem Sie eine Unterhaltung erstellen, eine Antwort senden und überprüfen, ob Ausgabeelemente zurückgegeben werden.
  4. Bestätigen Sie die Kontextaufbewahrung , indem Sie mehrere Antworten an dieselbe Unterhaltung senden und überprüfen, ob sich der Agent an frühere Nachrichten erinnert.

Behandeln häufiger Probleme

Symptom Ursache Auflösung
Python: AttributeError: 'AIProjectClient' has no attribute 'conversations' Sie haben conversations.create() für den Projektclient anstelle des OpenAI-Clients aufgerufen. Verwenden Sie project.get_openai_client(), um den OpenAI-Client abzurufen, und rufen Sie dann openai.conversations.create() auf.
C#: Azure.AI.Extensions.OpenAI Namespace nicht gefunden Das Azure.AI.Extensions.OpenAI NuGet-Paket fehlt. Installieren Sie Azure.AI.Projects (was Azure.AI.Extensions.OpenAI und Azure.AI.Projects.Agents als Abhängigkeiten bringt).
JavaScript: getOpenAIClient is not a function Sie verwenden eine ältere Version von @azure/ai-projects. Aktualisieren auf @azure/ai-projects@2.0.0 oder höher: npm install @azure/ai-projects@2.0.0.
Java: AgentsClientBuilder kann nicht aufgelöst werden. Die azure-ai-agents Maven-Abhängigkeit fehlt oder ist veraltet. Fügen Sie com.azure:azure-ai-agents:2.0.0 zu Ihren pom.xml Abhängigkeiten hinzu.
create_agent() wird entfernt. Frühere SDK-Versionen verwendeten create_agent(), welche in v2.0.0 entfernt wurde. Ersetzen Sie durch create_version() (Python/JS) oder CreateAgentVersionAsync() (C#) oder createAgentVersion() (Java) und übergeben Sie ein PromptAgentDefinition-Objekt.
Alte Threaddaten sind nicht verfügbar. Das Migrationstool migriert keine Statusdaten (vergangene Ausführungen, Threads oder Nachrichten). Neue Unterhaltungen nach der Migration starten. Auf historische Daten kann über die vorherige API zugegriffen werden, bis sie veraltet ist.
responses.create() löst einen Modellfehler aus. Der Modellname ist möglicherweise falsch oder in Ihrer Region nicht verfügbar. Überprüfen Sie den Modellnamen in Ihrem Foundry-Projekt, und überprüfen Sie die Verfügbarkeit der Modellregion.