Eseguire la migrazione alla nuova esperienza di sviluppo degli agenti.

Foundry Agent Service offre un'esperienza di sviluppo aggiornata per la creazione di agenti intelligenti facili da compilare, versione, funzionamento e osservare. La nuova API degli agenti introduce un SDK modernizzato, nuove funzionalità di livello aziendale e mantiene le funzionalità di identità, governance e osservabilità su cui ci si basa oggi.

Prerequisiti

• Una sottoscrizione di Azure. Creane uno gratis.
• Progetto Microsoft Foundry.
• azure-ai-projects Python SDK (versione 2.0.0b4 o successiva). Installa con pip install "azure-ai-projects>=2.0.0b4" --pre.
• Pacchetto azure-identity per l'autenticazione. Installare con pip install azure-identity e accedere con az login o usare DefaultAzureCredential.
• Codice di agenti o assistenti esistenti di cui si vuole eseguire la migrazione.

Il codice seguente inizializza i client usati in questa guida:

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

project_client = AIProjectClient(
    endpoint="<your-project-endpoint>",
    credential=DefaultAzureCredential(),
)
openai_client = project_client.get_openai_client()

Usare project_client per la creazione e il controllo delle versioni dell'agente. Usare openai_client per conversazioni e risposte.

Vantaggi principali

I nuovi agenti offrono i vantaggi seguenti:

Produttività degli sviluppatori

• ⭐ Altri modelli. Generare risposte usando qualsiasi modello Foundry nell'agente o direttamente come chiamata di generazione della risposta.
• Altre funzionalità. Ricerca Web, Ricerca file, Interprete codice, chiamata dello strumento MCP, generazione di immagini e riepiloghi di ragionamento.
• Primitiva dell'API moderna. Basato sull'API Risposte anziché sull'API Assistants precedente.
• A prova di futuro. Le nuove funzionalità e il supporto del modello vengono aggiunti solo ai nuovi agenti.
• Nuovi tipi di agente. Creare agenti basati su prompt o basati su flussi di lavoro.

Idoneità aziendale

• ⭐ Archiviazione a tenant singolo. Usa l'archiviazione a tenant singolo, con l'opzione di utilizzare il tuo Azure Cosmos DB per archiviare lo stato e proteggere i tuoi dati.
• Sicurezza avanzata. Controllare chi può eseguire o modificare le definizioni degli agenti.
• Separazione dei compiti. Definire gli agenti una sola volta ed eseguirli con vari input.
• Agenti distribuibili. Gli agenti possono essere esposti come singoli endpoint.

Modernizzazione delle API

• Gestione dello stato migliorata. Usa conversazioni anziché thread e messaggi.
• Contesto con stato. Mantiene automaticamente il contesto tra le chiamate.
• Superinsieme dell'API Risposte. Si basa sull'API Risposte e aggiunge altre funzionalità.
• Flussi di lavoro con agente singolo o multi-agente. Concatena facilmente gli agenti per flussi di lavoro complessi.

Modifiche chiave

La tabella seguente riepiloga le modifiche principali dell'API tra l'esperienza precedente e l'agente corrente.

Eseguire la migrazione dei thread alle conversazioni

I thread archiviano i messaggi sulla parte server. Una conversazione può archiviare elementi, inclusi messaggi, chiamate agli strumenti, output degli strumenti e altri dati.

Richieste

Gli esempi seguenti confrontano la creazione di thread (precedente) con la creazione della conversazione (corrente). L'approccio corrente usa il client OpenAI ottenuto da project_client.get_openai_client().

Precedente - Thread

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

Attuali - Conversazioni

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

Responses

Le risposte JSON mostrano le differenze strutturali tra gli oggetti thread e gli oggetti di conversazione.

Precedente - Thread

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

Attuali - Conversazioni

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

Aggiungere elementi a una conversazione esistente

Dopo aver creato una conversazione, usare conversations.items.create() per aggiungere messaggi successivi. Questo modello sostituisce l'aggiunta di messaggi ai thread con client.agents.messages.create().

Precedente: aggiungere un messaggio a un thread

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

Corrente: aggiungere elementi a una conversazione

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

Migrare le esecuzioni verso le risposte

Le esecuzioni erano processi asincroni eseguiti su thread. Le risposte sono più semplici: fornire un set di elementi di input da eseguire e ottenere un elenco di elementi di output. Le risposte possono essere usate da sole o con oggetti di conversazione per archiviare il contesto. L'API delle risposte usa il client OpenAI.

Richieste

Negli esempi seguenti viene confrontato il modo in cui si richiama la logica dell'agente. L'approccio precedente usava esecuzioni asincrone con il polling. L'approccio corrente chiama responses.create() sul client OpenAI.

Precedente - Esecuzioni

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) 

Current : risposte

conversation_id = "conv_11112222AAAABBBB"

response = openai_client.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"}}
)

Responses

Precedente - Esecuzioni

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

Current : risposte

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

Eseguire la migrazione degli agenti classici a nuovi agenti

Se si usa il client.agents.create_agent() metodo delle versioni precedenti dell'SDK, eseguire la migrazione a client.agents.create_version(). Il nuovo metodo introduce definizioni di agenti strutturati con campi espliciti kind, modele instructions .

Richieste

Precedente

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 
) 

Corrente

from azure.ai.projects.models import PromptAgentDefinition

agent = project_client.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."
    )
) 

Responses

Gli esempi JSON seguenti confrontano gli oggetti risposta restituiti dai metodi di creazione dell'agente precedenti e correnti.

Precedente

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

Corrente

{ 
  'metadata': {  
  }, 
  'object': 'agent.version', 
  'id': 'my-agent:1', 
  'name': 'my-agent', 
  'version': '1', 
  'description': '', 
  'created_at': 1762219751, 
  'definition': { 
    'kind': 'prompt', 
    'model': 'gpt-4.1', 
    'instructions': 'You politely help with math questions. Use the Code Interpreter tool when asked to visualize numbers.' 
  } 
} 

Eseguire la migrazione di assistenti a nuovi agenti

Se il codice usa l'API Assistenti OpenAI (client.beta.assistants.create()), eseguire la migrazione al servizio Agente Foundry usando client.agents.create_version(). Negli esempi seguenti vengono illustrate le differenze strutturali.

Indietro - Assistenti

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

Agenti attuali - nuovi

from azure.ai.projects.models import PromptAgentDefinition

agent = project_client.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."
    )
) 

Eseguire lo strumento di migrazione

Uno strumento di migrazione è disponibile in GitHub per automatizzare la migrazione degli agenti e degli assistenti. Lo strumento esegue la migrazione di costrutti di codice, come le definizioni di agenti, la creazione di thread, la creazione di messaggi e la creazione di esecuzioni. Non esegue la migrazione dei dati sullo stato, ad esempio esecuzioni precedenti, thread o messaggi. Dopo la migrazione, è possibile eseguire il nuovo codice ed eventuali nuovi dati sullo stato vengono creati nel formato aggiornato.

L'esempio seguente mostra un confronto completo prima e dopo. Si noti che il codice corrente usa sia project_client per la creazione dell'agente che openai_client per le conversazioni e le risposte.

Precedente

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

Corrente

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

with project_client.get_openai_client() as openai_client:
    agent = project_client.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()]
        ) 
    )
    conversation = openai_client.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."}], 
    ) 
    response = openai_client.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"
    ) 

Verifica la tua migrazione

Dopo aver eseguito la migrazione del codice, verificare che tutto funzioni correttamente:

1. Eseguire il codice aggiornato e verificare che venga eseguito senza errori.
2. Controllare la creazione dell'agente confermando che create_version() restituisce un oggetto con i campi id e version.
3. Testare una conversazione creando una conversazione, inviando una risposta e verificando che vengano restituiti gli elementi di output.
4. Verificare la conservazione del contesto inviando più risposte alla stessa conversazione e verificando che l'agente ricordi i messaggi precedenti.

Risolvere i problemi comuni

Contenuti correlati

• Componenti di runtime dell'agente
• Guida introduttiva: Creare un agente ospitato
• Distribuire un agente ospitato