Guida introduttiva: Creare un agente di prompt

In questa guida rapida, si crea un agente di prompt nel Servizio Agente Fonderia e si ha una conversazione con esso. Un agente prompt è un agente definito in modo dichiarativo che combina un modello dal catalogo dei modelli di Foundry, con istruzioni, strumenti e prompt di linguaggio naturale per orientare il comportamento.

Note

Per creare un agente di prompt che usa il Microsoft Copilot harness con un SDK, vedere Usare l'Copilot harness con gli agenti prompt. Per uno scenario end-to-end del portale o di Azure Developer CLI (azd), vedere Avvio rapido: Creare un agente di ricerca sul Web.

Suggerimento

Per un'esperienza vocale gestita in tempo reale, usare un agente di prompt basato su voce. Gli agenti basati su prompt vocali utilizzano Voice Live per conversazioni vocali e non richiedono che tu ospiti il codice di orchestrazione vocale.

Se non si ha una sottoscrizione Azure, creare un account free.

Prerequisiti

Ottenere l'endpoint del progetto

Copiare l'endpoint del progetto dalla schermata iniziale nel portale di Foundry.

Gli esempi di codice in questa guida introduttiva dichiarano i relativi valori come costanti all'inizio di ogni file. Prima di eseguire un esempio, sostituire questi segnaposto:

  • your_project_endpoint: l'endpoint del progetto, nel formato https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
  • your_agent_name: nome dell'agente, ad esempio MyAgent.

Installare pacchetti ed eseguire l'autenticazione

Assicurarsi di installare la versione corretta dei pacchetti, come illustrato di seguito.

  1. Installare la versione corrente di azure-ai-projects. Questa versione usa l'API di Foundry projects (new). Gli esempi si autenticano utilizzando DefaultAzureCredential, che proviene da azure-identity.

    pip install "azure-ai-projects>=2.3.0"
    
  2. Accedi utilizzando il comando CLI az login per autenticarti prima di eseguire i tuoi script Python.

Suggerimento

Il codice usa Azure Ai Projects 2.x ed è incompatibile con Azure AI Projects 1.x. Visualizza la documentazione di Foundry (versione classica) per la versione Azure AI Projects 1.x.

Creare un agente di risposta rapida

Crea un agente per i prompt utilizzando il tuo modello distribuito. L'agente usa un PromptAgentDefinition oggetto con istruzioni che definiscono il comportamento dell'agente. È possibile aggiornare o eliminare agenti in qualsiasi momento.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your-agent-name"

# Create project client to call Foundry API
project = AIProjectClient(
    endpoint=FOUNDRY_PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create an agent with a model and instructions
agent = project.agents.create_version(
    agent_name=FOUNDRY_AGENT_NAME,
    definition=PromptAgentDefinition(
        model="gpt-5-mini",  # supports all Foundry direct models
        instructions="You are a helpful assistant that answers general questions",
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

L'output conferma che l'agente è stato creato. Nella console viene visualizzato il nome e l'ID dell'agente.

Chat con l'agente

Usa l'agente che hai creato per interagire ponendo una domanda e un'interazione successiva correlata. La conversazione mantiene la cronologia di queste interazioni.

Note

Se si richiama un agente che usa il Microsoft Copilot harness, usare invece gli esempi di chiamata specifici dell'harness. Questi esempi richiedono l'endpoint dell'agente, non l'endpoint Responses a livello di progetto. Vedere esempi di endpoint e risoluzione dei problemi.

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

# Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint"
FOUNDRY_AGENT_NAME = "your-agent-name"

# Create project and openai clients to call Foundry API
project = AIProjectClient(
    endpoint=FOUNDRY_PROJECT_ENDPOINT,
    credential=DefaultAzureCredential(),
)

# Create the agent (or a new version, if it already exists)
project.agents.create_version(
    agent_name=FOUNDRY_AGENT_NAME,
    definition=PromptAgentDefinition(
        model="gpt-5-mini",
        instructions="You are a helpful assistant that answers general questions",
    ),
)

# Get an OpenAI client pre-bound to the specified agent
openai = project.get_openai_client(agent_name=FOUNDRY_AGENT_NAME)

# Create a conversation for multi-turn chat
conversation = openai.conversations.create()

# Chat with the agent to answer questions
response = openai.responses.create(
    conversation=conversation.id,
    input="What is the size of France in square miles?",
)
print(response.output_text)

# Ask a follow-up question in the same conversation
response = openai.responses.create(
    conversation=conversation.id,
    input="And what is the capital city?",
)
print(response.output_text)

Vengono visualizzate le risposte dell'agente a entrambe le richieste. La risposta di follow-up dimostra che l'agente mantiene la cronologia delle conversazioni tra i turni.

Verifica quindi la trace del primo agente nel portale Foundry.

Pulire le risorse

Se non sono più necessarie risorse create, eliminare il gruppo di risorse associato al progetto.

  • Nel portale Azure portale selezionare il gruppo di risorse e quindi selezionare Delete. Verificare di voler eliminare il gruppo di risorse.