Migrace na nové prostředí pro vývojáře agentů

Tip

K dispozici je nástroj pro migraci , který pomáhá automatizovat migraci z rozhraní API Asistentů na agenty.

Služba Foundry Agent Service poskytuje upgradované vývojářské prostředí pro vytváření inteligentních agentů, které se dají snadno sestavit, verze, provozovat a sledovat. Nové rozhraní API agentů zavádí modernizované sady SDK, nové funkce na podnikové úrovni a zachovává funkce identit, zásad správného řízení a pozorovatelnosti, které v současnosti využíváte.

Požadavky

  • Předplatné Azure. Vytvořte si ho zdarma.
  • Projekt Microsoft Foundry.
  • Sada SDK služby agenta Foundry pro váš jazyk a odpovídající balíček identity pro ověřování. Nainstalujte balíčky pro váš jazyk a přihlaste se s az login nebo použijte DefaultAzureCredential:
pip install "azure-ai-projects>=2.3.0"
  • Existující kód agentů nebo asistentů, který chcete migrovat.

Následující kód inicializuje klienty použité v této příručce:

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

Použijte project pro vytváření a verzování agenta. Používejte openai (nebo ekvivalent ve vašem jazyce) ke konverzacím a odpovědím.

Klíčové výhody

Noví agenti poskytují následující výhody:

Produktivita vývojářů

  • ⭐ Další modely. Vygenerujte odpovědi pomocí libovolného modelu Foundry buď ve vašem agentu, nebo přímo jako volání generování odpovědí.
  • Další funkce. Vyhledávání na webu, vyhledávání souborů, interpret kódu, volání nástroje MCP, generování obrázků a souhrny důvodů.
  • Moderní primitiva rozhraní API Je postaveno na rozhraní API pro odpovědi místo staršího rozhraní API asistentů.
  • Režim pozadí. Podpora dlouhotrvajících nástrojů (jako je generování imagí) a trvalých datových proudů (podporuje scénáře odpojení a opětovného připojení)
  • Odolný vůči budoucnosti. Nové funkce a podpora modelů jsou k dispozici pouze u nových agentů.
  • Nové typy agentů. Vytvořte agenty založené na promptech a hostované agenty.

Připravenost podniku

  • ⭐ Single-tenant storage. Použijte úložiště s jedním tenantem a použijte vlastní Azure Cosmos DB pro ukládání stavu a zabezpečení dat.
  • Lepší zabezpečení. Určete, kdo může spouštět nebo upravovat definice agenta.
  • Oddělení povinností. Definujte agenty jednou a spusťte je s různými vstupy.
  • Nasaditelné agenty. Agenti mohou být vystaveni jako jednotlivé koncové body.

Modernizace rozhraní API

  • Vylepšená správa stavu Používá konverzace místo vláken a zpráv.
  • Stavový kontext Automaticky zachovává kontext napříč voláními.
  • Nadmnožina API rozhraní pro odpovědi Vychází z rozhraní API pro odpovědi a přidává další funkce.
  • Pracovní postupy s jedním nebo více agenty Snadno propojte agenty pro složité pracovní postupy.

Klíčové změny

Následující tabulka shrnuje hlavní změny rozhraní API mezi předchozím a aktuálním prostředím agenta.

Před Po Podrobnosti
Vlákna Konverzace Podporuje streamy položek, nejen zprávy.
Běží Reakce Odpovědi odesílají vstupní položky nebo používají objekt konverzace a přijímají výstupní položky. Smyčky volání nástrojů jsou explicitně spravované.
Asistenti / agenti Agenti (nové) Podpora promptů pro podnikové nasazení a hostovaných agentů se stavovým kontextem standardně pro jakýkoli model Foundry.

Dostupnost agentního nástroje

Následující tabulka porovnává nástroje agenta dostupné v klasických agentech a novou službu Foundry Agent Service. Použijte ho k identifikaci nástrojů, které se přímo přenesly, které se změnily a které jsou výhradní pro nové prostředí.

Nástroj Slévárna (klasická) Slévárna (nová)
Agent k agentovi (A2A) Ne Ano (Veřejný náhled)
Azure AI Vyhledávač Ano (GA) Ano (GA)
Azure Functions Ano (GA) Ne
Automatizace prohlížeče Ano (Veřejný náhled) Ano (Veřejný náhled)
Interpretér kódu Ano (GA) Ano (GA)
Použití počítače Ano (Veřejný náhled) Ano (Veřejný náhled)
Propojení agenti Ano (Veřejný náhled) Ne (doporučení: nástroj A2A)
Hloubkové výzkumy Ano (Veřejný náhled) Ne (doporučení: Model hloubkového výzkumu pomocí nástroje Pro vyhledávání na webu)
datový agent Fabric Ano (Veřejný náhled) Ano (Veřejný náhled)
Hledání souborů Ano (GA) Ano (GA)
Funkce Ano (GA) Ano (GA)
Uzemnění pomocí vyhledávání Bingem Ano (GA) Ano (GA)
Uzemnění pomocí vyhledávání na míru od Bingu Ano (Veřejný náhled) Ano (Veřejný náhled)
Generování obrázků Ne Ano (Veřejný náhled)
MCP Ano (Veřejný náhled) Ano (GA)
OpenAPI Ano (GA) Ano (GA)
Základy SharePoint Ano (Veřejný náhled) Ano (Veřejný náhled)
Vyhledávání na webu Ne Ano (GA)

Důležité

V novém rozhraní API používají rozhraní API pro konverzace a odpovědi OpenAI klienta (nebo jeho jazykový ekvivalent). V Python volejte project.get_openai_client(). V jazyce C# použijte projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(). V JavaScriptu zavolejte projectClient.getOpenAIClient(). V Java pomocí AgentsClientBuilder sestavte ResponsesClient. Vytváření a správa verzí agenta zůstávají v klientovi projektu. Příklady v každé části ukazují, kterého klienta použít.

Migrace vláken do konverzací

Vlákna ukládají zprávy na straně serveru. Konverzace může ukládat položky, včetně zpráv, volání nástrojů, výstupů nástrojů a dalších dat.

Požadavky

Následující příklady porovnávají vytváření vláken (předchozí) s vytvářením konverzací (aktuální). Aktuální přístup používá klienta OpenAI získaného z project.get_openai_client().

Předchozí – vlákna

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

Aktuální – konverzace

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

Reakce

Odpovědi JSON zobrazují strukturální rozdíly mezi objekty vlákna a objekty konverzace.

Předchozí – vlákna

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

Aktuální – konverzace

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

Přidání položek do existující konverzace

Po vytvoření konverzace použijte conversations.items.create(), abyste přidali další zprávy. Tento vzor nahrazuje přidávání zpráv do vláken za client.agents.messages.create().

Předchozí – přidání zprávy do vlákna

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

Aktuální – přidání položek do konverzace

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

Migrace běhů na odpovědi

Spuštění byla asynchronní procesy, které se spouštěly na vláknech. Odpovědi jsou jednodušší: zadejte sadu vstupních položek, které se mají spustit, a získejte seznam výstupních položek zpět. Odpovědi se dají použít samostatně nebo s objekty konverzace pro ukládání kontextu. Rozhraní API pro odpovědi používá klienta OpenAI.

Požadavky

Následující příklady porovnávají způsob vyvolání logiky agenta. Předchozí přístup používal asynchronní běhy s periodickým dotazováním. Aktuální přístup volá funkci responses.create() na klientovi OpenAI.

Předchozí – spuštění

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)

Aktuální – odpovědi

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

Reakce

Předchozí – spuštění

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

Aktuální – odpovědi

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

Přechod od klasických agentů k novým agentům

Pokud používáte metodu client.agents.create_agent() ze starších verzí sady SDK, migrujte na client.agents.create_version(). Nová metoda zavádí definice strukturovaného agenta s explicitní kind, modela instructions pole.

Požadavky

Předchozí

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 
)

Aktuální

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

Reakce

Následující příklady JSON porovnávají objekty odpovědi vrácené předchozími a aktuálními metodami vytvoření agenta.

Předchozí

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

Aktuální

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

Převod asistentů na nové agenty

Pokud váš kód používá rozhraní API pomocníků OpenAI (client.beta.assistants.create()), migrujte do služby Foundry Agent Service pomocí client.agents.create_version(). Následující příklady ukazují strukturální rozdíly.

Předchozí – asistenti

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

Aktuální – nové agenty

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

Spuštění nástroje pro migraci

Nástroj migrace je k dispozici na GitHub, který vám pomůže automatizovat migraci agentů a asistentů. Nástroj migruje konstrukty kódu, jako jsou definice agenta, vytváření vláken, vytváření zpráv a vytváření spuštění. Nemigruje data o stavu, jako jsou minulé spuštění, vlákna nebo zprávy. Po migraci můžete spustit nový kód a všechna nová stavová data se vytvoří v aktualizovaném formátu.

Následující příklad ukazuje úplné porovnání před a po. Všimněte si, že aktuální kód používá project jak pro vytváření agentů, tak openai pro konverzace a odpovědi.

Předchozí

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

Aktuální

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)

Ověřte svou migraci

Po migraci kódu ověřte, že všechno funguje správně:

  1. Spusťte aktualizovaný kód a ověřte, že se spustí bez chyb.
  2. Zkontrolujte vytvoření agenta tím, že potvrdíte, že create_version() vrací objekt s polem id a version polem.
  3. Otestujte konverzaci tak, že vytvoříte konverzaci, odešlete odpověď a ověříte, že se vrátí výstupní položky.
  4. Potvrďte uchovávání kontextu odesláním více odpovědí do stejné konverzace a kontrolou, že si agent pamatuje dřívější zprávy.

Řešení běžných problémů

Příznak Příčina Rozlišení
Python:AttributeError: 'AIProjectClient' has no attribute 'conversations' Místo klienta OpenAI jste volali conversations.create() klienta projektu. Použijte project.get_openai_client() pro získání klienta OpenAI, potom zavolejte openai.conversations.create().
C#: Azure.AI.Extensions.OpenAI namespace nebyl nalezen. Chybí balíček NuGet Azure.AI.Extensions.OpenAI. Nainstalujte Azure.AI.Projects (který jako závislosti přináší Azure.AI.Extensions.OpenAI a Azure.AI.Projects.Agents).
JavaScript: getOpenAIClient is not a function Používáte starší verzi @azure/ai-projects. Aktualizovat na @azure/ai-projects@2.3.0 nebo novější: npm install @azure/ai-projects.
Java: AgentsClientBuilder nejde vyřešit Závislost na azure-ai-agents Maven chybí nebo je zastaralá. Přidejte com.azure:azure-ai-agents:2.2.0 k závislostem pom.xml.
create_agent() je odebraný. Používaly se create_agent()starší verze sady SDK, které byly odebrány ve verzi 2.0.0. Nahraďte create_version() (Python/JS) nebo CreateAgentVersionAsync() (C#) nebo createAgentVersion() (Java) a předejte objekt PromptAgentDefinition.
Stará data vlákna nejsou k dispozici. Nástroj pro migraci nemigruje stavová data (minulé spuštění, vlákna nebo zprávy). Po migraci zahajte nové konverzace. Historická data zůstávají přístupná prostřednictvím předchozího rozhraní API, dokud nebudou zastaralá.
responses.create() vyvolá chybu modelu. Název modelu může být ve vaší oblasti nesprávný nebo nedostupný. Ověřte název modelu v projektu Foundry a zkontrolujte dostupnost oblasti modelu.

Související obsah

  • Last updated on