Migreren naar de nieuwe agents-ontwikkelaarservaring

Tip

Er is een hulpprogramma voor migratie beschikbaar om de migratie van de Assistants-API naar agents te automatiseren.

Foundry Agent Service biedt een verbeterde ontwikkelaarservaring voor het bouwen van intelligente agents die eenvoudig te bouwen, versiebeheer, beheren en observeren zijn. De nieuwe agents-API introduceert een gemoderniseerde SDK, nieuwe zakelijke mogelijkheden en behoudt de identiteits-, governance- en waarneembaarheidsfuncties die u vandaag nog nodig hebt.

Voorwaarden

  • Een Azure-abonnement. Maak er gratis een.
  • Een Microsoft Foundry-project.
  • De Foundry Agent Service SDK voor uw taal en het bijbehorende identiteitspakket voor verificatie. Installeer de pakketten voor uw taal en meld u aan met az login of gebruik DefaultAzureCredential:
pip install "azure-ai-projects>=2.0.0"
  • Bestaande agents en assistenten code die u wilt migreren.

De volgende code initialiseert de clients die in deze handleiding worden gebruikt:

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()

Gebruiken project voor het maken en versiebeheer van agents. Gebruik openai (of het equivalent in uw taal) voor gesprekken en antwoorden.

Belangrijkste voordelen

De nieuwe agents bieden de volgende voordelen:

Productiviteit van ontwikkelaars

  • Meer modellen. Genereer antwoorden met behulp van een Foundry-model in uw agent of rechtstreeks als oproep voor het genereren van antwoorden.
  • Meer functies. Webzoek, Bestandszoek, code-interpretertool, MCP-aanroep, beeldgeneratie en samenvattingen van redeneringen.
  • Moderne API-primitief. Gebouwd op de Antwoorden-API in plaats van de oudere API voor assistenten.
  • Achtergrondmodus. Ondersteuning voor langlopende hulpprogramma's (zoals beeldgeneratie) en duurzame streams (ondersteunt scenario's voor verbinding verbreken/opnieuw verbinden)
  • Toekomstbestendig. Nieuwe functies en modelondersteuning worden alleen toegevoegd aan de nieuwe agents.
  • Nieuwe agenttypen. Maak op prompts gebaseerde agents, op werkstromen gebaseerde agents (preview) en gehoste agents (preview).

Bedrijfsgereedheid

  • Single-tenant storage. Gebruik opslag met één tenant, met de optie om uw eigen Azure Cosmos DB te gebruiken om de status op te slaan en uw gegevens veilig te houden.
  • Verbeterde beveiliging. Bepalen wie agentdefinities kan uitvoeren of wijzigen.
  • Scheiding van taken. Definieer agents eenmaal en voer ze uit met verschillende invoer.
  • Implementeerbare agents. Agents kunnen als afzonderlijke eindpunten worden weergegeven.

API-modernisering

  • Verbeterd toestandbeheer. Gebruikt gesprekken in plaats van threads en berichten.
  • statusgevoelige context Behoudt automatisch context tussen aanroepen.
  • Superverzameling van antwoord-API. Bouwt voort op de Response-API en voegt meer mogelijkheden toe.
  • Werkstromen met één of meerdere agents. Koppel eenvoudig agents voor complexe werkstromen.

Belangrijke wijzigingen

De volgende tabel bevat een overzicht van de belangrijkste API-wijzigingen tussen de vorige en huidige agentervaring.

Voordat Na Details
Draadjes Gesprekken Ondersteunt streams van items, niet alleen berichten.
Uitvoeringen Reacties Antwoorden verzenden invoeritems of gebruiken een gespreksobject en ontvangen uitvoeritems. Lussen voor hulpprogramma-aanroepen worden expliciet beheerd.
Assistenten/agenten Agenten (nieuw) Ondersteuning voor bedrijfsklare prompts, werkstromen en gehoste agents met standaard stateful context voor elk Foundry-model.

Beschikbaarheid van agenthulpprogramma's

In de volgende tabel worden agenthulpprogramma's vergeleken die beschikbaar zijn in klassieke agents en de nieuwe Foundry Agent Service. Gebruik deze om te bepalen welke hulpprogramma's rechtstreeks worden overgedragen, die zijn gewijzigd en die exclusief zijn voor de nieuwe ervaring.

Hulpmiddel Foundry (klassiek) Foundry (nieuw)
Agent naar agent (A2A) Nee Ja (openbare preview)
Azure AI Zoeken Ja (GA) Ja (GA)
Azure Functions Ja (GA) Nee
Browserautomatisering Ja (openbare preview) Ja (openbare preview)
Code-interpreter Ja (GA) Ja (GA)
Computergebruik Ja (openbare preview) Ja (openbare preview)
Verbonden agents Ja (openbare preview) Nee (aanbeveling: werkstroom en A2A-hulpprogramma)
Diep onderzoek Ja (openbare preview) Nee (aanbeveling: Deep Research-model met webzoekprogramma)
Fabric gegevensagent Ja (openbare preview) Ja (openbare preview)
Zoeken naar bestanden Ja (GA) Ja (GA)
Functie Ja (GA) Ja (GA)
Basis leggen met Bing Search Ja (GA) Ja (GA)
Basis leggen met Bing Custom Search Ja (openbare preview) Ja (openbare preview)
Afbeeldingsgeneratie Nee Ja (openbare preview)
MCP Ja (openbare preview) Ja (GA)
OpenAPI Ja (GA) Ja (GA)
SharePoint Grounding Ja (openbare preview) Ja (openbare preview)
Zoeken op internet Nee Ja (GA)

Belangrijk

In de nieuwe API gebruiken de gespreks- en antwoord-API's de OpenAI-client (of het equivalent van de taal). Roep in Python project.get_openai_client() aan. Gebruik in C# projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(). Roep in JavaScript projectClient.getOpenAIClient() aan. Gebruik in Java AgentsClientBuilder om een ResponsesClient te bouwen. Het maken en versiebeheer van de agent blijft aanwezig op de projectclient. In de voorbeelden in elke sectie ziet u welke client moet worden gebruikt.

Threads migreren naar gesprekken

Threads hebben berichten opgeslagen aan de serverzijde. Een gesprek kan items opslaan, waaronder berichten, hulpprogramma-aanroepen, uitvoer van hulpprogramma's en andere gegevens.

Verzoeken

De volgende voorbeelden vergelijken het maken van threads (vorige) met het maken van gesprekken (actueel). De huidige benadering maakt gebruik van de OpenAI-client die is verkregen van project.get_openai_client().

Vorige - threads

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

Huidig - gesprekken

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

Reacties

De JSON-antwoorden tonen de structurele verschillen tussen threadobjecten en gespreksobjecten.

Vorige - threads

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

Huidig - gesprekken

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

Items toevoegen aan een bestaand gesprek

Nadat u een gesprek hebt gemaakt, kunt u conversations.items.create() volgende berichten toevoegen. Dit patroon vervangt het toevoegen van berichten aan threads door client.agents.messages.create().

Vorige : een bericht toevoegen aan een thread

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

Huidig : items toevoegen aan een gesprek

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

Migraties van processen naar antwoorden

Uitvoeringen waren asynchrone processen die werden uitgevoerd op threads. Antwoorden zijn eenvoudiger: geef een set invoeritems op die moeten worden uitgevoerd en haal een lijst met uitvoeritems terug. Antwoorden kunnen alleen worden gebruikt of met gespreksobjecten voor het opslaan van context. De antwoorden-API maakt gebruik van de OpenAI-client.

Verzoeken

In de volgende voorbeelden wordt vergeleken hoe u agentlogica aanroept. Vorige benadering gebruikte asynchrone taakuitvoeringen met polling. De huidige benadering roept responses.create() de OpenAI-client aan.

Vorige - uitvoeringen

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) 

Huidig - antwoorden

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",
        }
    },
)

Reacties

Vorige - uitvoeringen

{
  "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
}

Huidig - antwoorden

{
  "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
}

Klassieke agents migreren naar nieuwe agents

Als u de client.agents.create_agent() methode uit eerdere SDK-versies gebruikt, migreert u naar client.agents.create_version(). De nieuwe methode introduceert gestructureerde agentdefinities met expliciete kind, modelen instructions velden.

Verzoeken

Vorige

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 
) 

Huidige

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()],
    ),
)

Reacties

In de volgende JSON-voorbeelden worden de antwoordobjecten vergeleken die worden geretourneerd door de vorige en huidige methoden voor het maken van agents.

Vorige

{ 
  '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' 
} 

Huidige

{
  "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"
      }
    ]
  }
}

Assistenten migreren naar nieuwe agents

Als uw code gebruikmaakt van de OpenAI Assistants-API (client.beta.assistants.create()), migreert u naar de Foundry Agent-service met behulp van client.agents.create_version(). In de volgende voorbeelden ziet u de structurele verschillen.

Vorige - 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"}], 
) 

Huidig - nieuwe agenten

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()],
    ),
)

Het hulpprogramma voor migratie uitvoeren

Er is een hulpprogramma voor migratie beschikbaar op GitHub om de migratie van uw agents en assistenten te automatiseren. Met het hulpprogramma worden codeconstructies gemigreerd, zoals agentdefinities, het maken van threads, het maken van berichten en het maken van uitvoeringen. Statusgegevens, zoals eerdere uitvoeringen, threads of berichten, worden niet gemigreerd. Na de migratie kunt u de nieuwe code uitvoeren en worden alle nieuwe toestandgegevens aangemaakt in de bijgewerkte indeling.

In het volgende voorbeeld ziet u een volledige vergelijking vóór en na. U ziet dat de huidige code zowel project voor het maken van agents als openai voor gesprekken en antwoorden gebruikt.

Vorige

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}") 

Huidige

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)

Uw migratie controleren

Nadat u uw code hebt gemigreerd, controleert u of alles correct werkt:

  1. Voer de bijgewerkte code uit en controleer of deze zonder fouten wordt uitgevoerd.
  2. Controleer het maken van de agent door te controleren of create_version() een object retourneert met een id- en version-veld.
  3. Test een gesprek door een gesprek te maken, een antwoord te verzenden en te controleren of uitvoeritems worden geretourneerd.
  4. Bevestig de retentie van context door meerdere antwoorden naar hetzelfde gesprek te verzenden en te controleren of de agent eerdere berichten onthoudt.

Veelvoorkomende problemen oplossen

Symptoom Oorzaak Resolutie
Python: AttributeError: 'AIProjectClient' has no attribute 'conversations' U hebt de projectclient aangeroepen conversations.create() in plaats van de OpenAI-client. Gebruik project.get_openai_client() om de OpenAI-client te verkrijgen en roep vervolgens openai.conversations.create() aan.
C#: Azure.AI.Extensions.OpenAI naamruimte is niet gevonden Het Azure.AI.Extensions.OpenAI NuGet-pakket ontbreekt. Installeer Azure.AI.Projects (die Azure.AI.Extensions.OpenAI en Azure.AI.Projects.Agents als afhankelijkheden brengt).
JavaScript: getOpenAIClient is not a function U gebruikt een oudere versie van @azure/ai-projects. Bijwerken naar versie @azure/ai-projects@2.0.0 of hoger: npm install @azure/ai-projects@2.0.0.
Java: AgentsClientBuilder kan het probleem niet oplossen De azure-ai-agents Maven-afhankelijkheid ontbreekt of is verouderd. Voeg deze com.azure:azure-ai-agents:2.0.0 toe aan uw pom.xml afhankelijkheden.
create_agent() is verwijderd Eerdere SDK-versies gebruikten create_agent(), wat is verwijderd in v2.0.0. Vervang door create_version() (Python/JS) of CreateAgentVersionAsync() (C#) of createAgentVersion() (Java) en geef een PromptAgentDefinition-object door.
Oude threadgegevens zijn niet beschikbaar Het hulpprogramma voor migratie migreert geen statusgegevens (eerdere uitvoeringen, threads of berichten). Start nieuwe gesprekken na de migratie. Historische gegevens blijven toegankelijk via de vorige API totdat deze zijn afgeschaft.
responses.create() genereert een modelfout De modelnaam is mogelijk onjuist of niet beschikbaar in uw regio. Controleer de modelnaam in uw Foundry-project en controleer de beschikbaarheid van de modelregio.