Migrera till den nya utvecklarupplevelsen för agenter

Tips

Det finns ett migreringsverktyg som hjälper dig att automatisera migreringen från Assistent-API:et till agenter.

Foundry Agent Service ger en uppgraderad utvecklarupplevelse för att skapa intelligenta agenter som är enkla att skapa, version, använda och observera. Det nya agent-API:et introducerar ett moderniserat SDK, nya funktioner i företagsklass och bevarar de identitets-, styrnings- och observerbarhetsfunktioner som du förlitar dig på i dag.

Förutsättningar

  • En Azure-abonnemang. Skapa en kostnadsfritt.
  • Ett Microsoft Foundry-projekt.
  • Foundry Agent Service SDK för ditt språk och motsvarande identitetspaket för autentisering. Installera paketen för ditt språk och logga in med az login eller använd DefaultAzureCredential:
pip install "azure-ai-projects>=2.0.0"
  • Befintlig agenternas eller assistenternas kod som du vill migrera.

Följande kod initierar klienterna som används i den här guiden:

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

Använd project för att skapa och versionshantera agenter. Använd openai (eller motsvarande på ditt språk) för konversationer och svar.

Viktiga fördelar

De nya agenterna ger följande fördelar:

Utvecklarproduktivitet

  • Fler modeller. Generera svar med hjälp av en Foundry-modell i din agent eller direkt som ett svarsgenereringsanrop.
  • Fler funktioner. Sammanfattningar av webbsökning, filsökning, kodtolkare, MCP-verktyg, bildgenerering och resonemang.
  • Modern API-primitiv. Bygger på API för svar i stället för det äldre API:et för assistenter.
  • Bakgrundsläge. Stöd för tidskrävande verktyg (till exempel bildgenerering) och hållbara strömmar (stöder scenarier för frånkoppling/återanslutning)
  • Framtidssäkert. Nya funktioner och modellstöd läggs endast till i de nya agenterna.
  • Nya agenttyper. Skapa promptbaserade, arbetsflödesbaserade agenter, arbetsflödesbaserade agenter (förhandsversion) och värdbaserade agenter (förhandsversion).

Företagsberedskap

  • Single-tenant lagring. Använd single-tenant lagring, med möjligheten att använda din egen Azure Cosmos DB för att lagra tillstånden och hålla dina data säkra.
  • Förbättrad säkerhet. Kontrollera vem som kan köra eller ändra agentdefinitioner.
  • Ansvarsfördelning. Definiera agenter en gång och kör dem med olika indata.
  • Utplacerbara agenter. Agenter kan exponeras som enskilda slutpunkter.

API-modernisering

  • Förbättrad tillståndshantering. Använder konversationer i stället för trådar och meddelanden.
  • Tillståndskänslig kontext. Behåller automatiskt kontexten mellan anrop.
  • Utökad version av svars-API. Bygger på SVARS-API:et och lägger till fler funktioner.
  • Arbetsflöden med en eller flera agenter. Länka enkelt agenter för komplexa arbetsflöden.

Viktiga ändringar

I följande tabell sammanfattas de viktigaste API-ändringarna mellan den tidigare och den aktuella agentupplevelsen.

Innan Efter Detaljer
Trådar Samtal Stöder strömmar av objekt, inte bara meddelanden.
Körs Svaren Svar skickar indataobjekt eller använder ett konversationsobjekt och tar emot utdataobjekt. Anropsloopar för verktyg hanteras uttryckligen.
Assistenter/agenter Agenter (ny) Stöd för företagsklara prompter, arbetsflöden och värdbaserade agenter med tillståndskänslig kontext som standard för alla Foundry-modeller.

Tillgänglighet för agentverktyg

I följande tabell jämförs agentverktyg som är tillgängliga i klassiska agenter och den nya Foundry Agent Service. Använd den för att identifiera vilka verktyg som överförs direkt, vilka som har ändrats och vilka som är exklusiva för den nya upplevelsen.

Verktyg Foundry (klassisk) Foundry (ny)
Agent till agent (A2A) Nej Ja (offentlig förhandsversion)
Azure AI-sökning Ja (GA) Ja (GA)
Azure Functions Ja (GA) Nej
Webbläsarautomatisering Ja (offentlig förhandsversion) Ja (offentlig förhandsversion)
Kodtolkare Ja (GA) Ja (GA)
Datoranvändning Ja (offentlig förhandsversion) Ja (offentlig förhandsversion)
Anslutna agenter Ja (offentlig förhandsversion) Nej (rekommendation: Arbetsflöde och A2A-verktyg)
Djup forskning Ja (offentlig förhandsversion) Nej (rekommendation: Djupforskningsmodell med webbsökningsverktyg)
Fabric Dataagent Ja (offentlig förhandsversion) Ja (offentlig förhandsversion)
Filsökning Ja (GA) Ja (GA)
Funktion Ja (GA) Ja (GA)
Grundstötning med Bing-sökning Ja (GA) Ja (GA)
Grundstötning med anpassad Bing-sökning Ja (offentlig förhandsversion) Ja (offentlig förhandsversion)
Bildgenerering Nej Ja (offentlig förhandsversion)
MCP Ja (offentlig förhandsversion) Ja (GA)
OpenAPI Ja (GA) Ja (GA)
SharePoint jordning Ja (offentlig förhandsversion) Ja (offentlig förhandsversion)
Webbsökning Nej Ja (GA)

Viktigt

I det nya API:et använder api:erna för konversationer och svar OpenAI-klienten (eller dess språkmotsvarighet). I Python anropar du project.get_openai_client(). I C# använder du projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(). I JavaScript anropar du projectClient.getOpenAIClient(). I Java använder du AgentsClientBuilder för att skapa en ResponsesClient. Agentskapande och versionshantering finns kvar på projektklienten. Exemplen i varje avsnitt visar vilken klient som ska användas.

Migrera trådar till konversationer

Trådar lagrade meddelanden på serversidan. En konversation kan lagra objekt, inklusive meddelanden, verktygsanrop, verktygsutdata och andra data.

Begäranden

I följande exempel jämförs skapande av tråd (tidigare) med skapande av konversation (aktuell). Den aktuella metoden använder OpenAI-klienten som hämtats från project.get_openai_client().

Föregående - trådar

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

Aktuell – konversationer

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

Svaren

JSON-svaren visar de strukturella skillnaderna mellan trådobjekt och konversationsobjekt.

Föregående - trådar

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

Aktuell – konversationer

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

Lägga till objekt i en befintlig konversation

När du har skapat en konversation använder du conversations.items.create() för att lägga till efterföljande meddelanden. Det här mönstret ersätter att lägga till meddelanden i trådar med client.agents.messages.create().

Föregående – lägg till ett meddelande i en tråd

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

Aktuell – lägga till objekt i en konversation

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

Migrera exekveringar till responser

Körningar var asynkrona processer som kördes mot trådar. Svar är enklare: ange en uppsättning indataobjekt som ska köras och få tillbaka en lista över utdataobjekt. Svar kan användas ensamt eller med konversationsobjekt för att lagra kontext. Svars-API:et använder OpenAI-klienten.

Begäranden

I följande exempel jämförs hur du anropar agentlogik. Den tidigare metoden använde asynkrona körningar med pollning. Det nuvarande tillvägagångssättet anropar responses.create() på OpenAI-klienten.

Föregående – körningar

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 – svar

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

Svaren

Föregående – körningar

{
  "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 – svar

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

Migrera klassiska agenter till nya agenter

Om du använder client.agents.create_agent() metoden från tidigare SDK-versioner migrerar du till client.agents.create_version(). Den nya metoden introducerar strukturerade agentdefinitioner med explicita kindfälten , modeloch instructions .

Begäranden

Tidigare

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 
) 

Nuvarande

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

Svaren

I följande JSON-exempel jämförs svarsobjekten som returnerades av de tidigare och aktuella metoderna för att skapa agenten.

Tidigare

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

Nuvarande

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

Migrera assistenter till nya agenter

Om koden använder OpenAI Assistants API (client.beta.assistants.create()) bör du migrera till Foundry Agent Service med hjälp av client.agents.create_version(). I följande exempel visas de strukturella skillnaderna.

Föregående - assistenter

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 – nya agenter

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

Kör migreringsverktyget

Ett migrationsverktyg finns på GitHub för att automatisera migreringen av dina agenter och assistenter. Verktyget migrerar kodkonstruktioner som agentdefinitioner, trådskapande, meddelandeskapande och körningsskapande. Den migrerar inte tillståndsdata som tidigare körningar, trådar eller meddelanden. Efter migreringen kan du köra den nya koden och alla nya tillståndsdata skapas i uppdaterat format.

I följande exempel visas en fullständig jämförelse före och efter. Observera att den aktuella koden använder både project för att skapa agenten och openai för konversationer och svar.

Tidigare

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

Nuvarande

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)

Verifiera migreringen

När du har migrerat koden kontrollerar du att allt fungerar korrekt:

  1. Kör den uppdaterade koden och kontrollera att den körs utan fel.
  2. Kontrollera agentens skapande genom att bekräfta att create_version() returnerar ett objekt med ett fält id och version.
  3. Testa en konversation genom att skapa en konversation, skicka ett svar och verifiera att utdataobjekt returneras.
  4. Bekräfta kontextkvarhållning genom att skicka flera svar till samma konversation och kontrollera att agenten kommer ihåg tidigare meddelanden.

Felsöka vanliga problem

Symptom Orsak Upplösning
Python: AttributeError: 'AIProjectClient' has no attribute 'conversations' Du anropade conversations.create() projektklienten i stället för OpenAI-klienten. Använd project.get_openai_client() för att hämta OpenAI-klienten och anropa openai.conversations.create()sedan .
C#: Azure.AI.Extensions.OpenAI namnområdet hittades inte NuGet-paketet Azure.AI.Extensions.OpenAI saknas. Installera Azure.AI.Projects (vilket ger Azure.AI.Extensions.OpenAI och Azure.AI.Projects.Agents som beroenden).
JavaScript: getOpenAIClient is not a function Du använder en äldre version av @azure/ai-projects. Uppdatera till @azure/ai-projects@2.0.0 eller senare: npm install @azure/ai-projects@2.0.0.
Java: AgentsClientBuilder kan inte lösa azure-ai-agents Maven-beroendet saknas eller är inaktuellt. Lägg till com.azure:azure-ai-agents:2.0.0 i dina pom.xml beroenden.
create_agent() tas bort Tidigare SDK-versioner använde create_agent(), som togs bort i v2.0.0. Ersätt med create_version() (Python/JS) eller CreateAgentVersionAsync() (C#) eller createAgentVersion() (Java) och skicka ett PromptAgentDefinition-objekt.
Gamla tråddata är inte tillgängliga Migreringsverktyget migrerar inte tillståndsdata (tidigare körningar, trådar eller meddelanden). Starta nya konversationer efter migreringen. Historiska data förblir tillgängliga via det tidigare API:et tills de är inaktuella.
responses.create() skapar ett modellfel Modellnamnet kan vara felaktigt eller otillgängligt i din region. Kontrollera modellnamnet i foundry-projektet och kontrollera tillgängligheten för modellregionen.