En esta guía rápida, crearás un agente de conversación en Foundry Agent Service y mantendrás una conversación con él. Un agente de solicitud es un agente definido de manera declarativa que combina un modelo del catálogo de modelos de Foundry, instrucciones, herramientas y mensajes en lenguaje natural para impulsar el comportamiento.
Si no tiene una suscripción de Azure, cree una cuenta free.
Requisitos previos
Establecimiento de variables de entorno
Almacene el punto de conexión del proyecto como una variable de entorno. Establezca también estos valores para usarlos en los scripts.
Python y JavaScript
PROJECT_ENDPOINT=<endpoint copied from welcome screen>
AGENT_NAME="MyAgent"
C# y Java
ProjectEndpoint = <endpoint copied from welcome screen>
AgentName = "MyAgent"
Instalación de paquetes y autenticación
Asegúrese de instalar la versión correcta de los paquetes como se muestra aquí.
Instale la versión actual de azure-ai-projects. Esta versión usa el API (nuevo) de Foundry projects.
pip install azure-ai-projects>=2.0.0
Inicia sesión usando el comando az login de la CLI para autenticarse antes de ejecutar tus scripts de Python.
Instalar paquetes:
Agregue paquetes NuGet en el terminal integrado utilizando la CLI de .NET: estos paquetes usan la API Foundry projects (nueva).
dotnet add package Azure.AI.Projects
dotnet add package Azure.AI.Projects.Agents
dotnet add package Azure.AI.Extensions.OpenAI
dotnet add package Azure.Identity
Inicie sesión con el comando de la CLI az login para autenticarse antes de ejecutar los scripts de C#.
Instale la versión actual de @azure/ai-projects. Esta versión utiliza la API de proyectos Foundry (nuevo).
npm install @azure/ai-projects
Inicie sesión con el comando de la CLI az login para autenticarse antes de ejecutar los scripts de TypeScript.
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-ai-agents</artifactId>
<version>2.0.0</version>
</dependency>
- Inicie sesión utilizando el comando
az login de la CLI para autenticarse antes de ejecutar sus scripts de Java.
Inicie sesión con el comando de la CLI az login para autenticarse antes de ejecutar el comando siguiente.
Obtenga un token de acceso temporal. Expirará en 60-90 minutos, tienes que actualizar después de eso.
az account get-access-token --scope https://ai.azure.com/.default
Guarde los resultados como la variable AZURE_AI_AUTH_TOKENde entorno .
No es necesario realizar ninguna instalación para usar el portal de Foundry.
Creación de un agente de solicitud
Cree un agente de indicaciones utilizando su modelo implementado. El agente usa un PromptAgentDefinition con instrucciones que definen el comportamiento del agente. Puede actualizar o eliminar agentes en cualquier momento.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"
# Create project client to call Foundry API
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
# Create an agent with a model and instructions
agent = project.agents.create_version(
agent_name=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})")
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.AI.Extensions.OpenAI;
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var ProjectEndpoint = "your_project_endpoint";
var AgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(ProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create an agent with a model and instructions
ProjectsAgentDefinition agentDefinition = new DeclarativeAgentDefinition("gpt-5-mini") // supports all Foundry direct models
{
Instructions = "You are a helpful assistant that answers general questions",
};
ProjectsAgentVersion agent = projectClient.AgentAdministrationClient.CreateAgentVersion(
AgentName,
options: new(agentDefinition));
Console.WriteLine($"Agent created (id: {agent.Id}, name: {agent.Name}, version: {agent.Version})");
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project client to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
// Create an agent with a model and instructions
const agent = await project.agents.createVersion(AGENT_NAME, {
kind: "prompt",
model: "gpt-5-mini", //supports all Foundry direct models
instructions: "You are a helpful assistant that answers general questions",
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.DefaultAzureCredentialBuilder;
public class CreateAgent {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String ProjectEndpoint = "your_project_endpoint";
String AgentName = "your_agent_name";
// Create agents client to call Foundry API
AgentsClient agentsClient = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(ProjectEndpoint)
.buildAgentsClient();
// Create an agent with a model and instructions
PromptAgentDefinition request = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models
.setInstructions("You are a helpful assistant that answers general questions");
AgentVersionDetails agent = agentsClient.createAgentVersion(AgentName, request);
System.out.println("Agent ID: " + agent.getId());
System.out.println("Agent Name: " + agent.getName());
System.out.println("Agent Version: " + agent.getVersion());
}
}
Reemplace YOUR-FOUNDRY-RESOURCE-NAME con sus valores.
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents?api-version=v1 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"name": "MyAgent",
"definition": {
"kind": "prompt",
"model": "gpt-4.1-mini",
"instructions": "You are a helpful assistant that answers general questions"
}
}'
El resultado confirma que se creó el agente. Verá el nombre del agente y el identificador impresos en la consola.
Chatear con el agente
Utilice el agente que creó para interactuar, haciendo una pregunta y realizando un seguimiento relacionado. La conversación mantiene el historial a lo largo de estas interacciones.
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
# Format: "https://resource_name.ai.azure.com/api/projects/project_name"
PROJECT_ENDPOINT = "your_project_endpoint"
AGENT_NAME = "your_agent_name"
# Create project and openai clients to call Foundry API
project = AIProjectClient(
endpoint=PROJECT_ENDPOINT,
credential=DefaultAzureCredential(),
)
openai = project.get_openai_client()
# 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,
extra_body={"agent_reference": {"name": AGENT_NAME, "type": "agent_reference"}},
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,
extra_body={"agent_reference": {"name": AGENT_NAME, "type": "agent_reference"}},
input="And what is the capital city?",
)
print(response.output_text)
using Azure.Identity;
using Azure.AI.Projects;
using Azure.AI.Extensions.OpenAI;
using OpenAI.Responses;
#pragma warning disable OPENAI001
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
var ProjectEndpoint = "your_project_endpoint";
var AgentName = "your_agent_name";
// Create project client to call Foundry API
AIProjectClient projectClient = new(
endpoint: new Uri(ProjectEndpoint),
tokenProvider: new DefaultAzureCredential());
// Create a conversation for multi-turn chat
ProjectConversation conversation = projectClient.ProjectOpenAIClient.GetProjectConversationsClient().CreateProjectConversation();
// Chat with the agent to answer questions
ProjectResponsesClient responsesClient = projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(
defaultAgent: AgentName,
defaultConversationId: conversation.Id);
ResponseResult response = responsesClient.CreateResponse("What is the size of France in square miles?");
Console.WriteLine(response.GetOutputText());
// Ask a follow-up question in the same conversation
response = responsesClient.CreateResponse("And what is the capital city?");
Console.WriteLine(response.GetOutputText());
import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
const PROJECT_ENDPOINT = "your_project_endpoint";
const AGENT_NAME = "your_agent_name";
async function main(): Promise<void> {
// Create project and openai clients to call Foundry API
const project = new AIProjectClient(PROJECT_ENDPOINT, new DefaultAzureCredential());
const openai = project.getOpenAIClient();
// Create a conversation for multi-turn chat
const conversation = await openai.conversations.create();
// Chat with the agent to answer questions
const response = await openai.responses.create(
{
conversation: conversation.id,
input: "What is the size of France in square miles?",
},
{
body: { agent_reference: { name: AGENT_NAME, type: "agent_reference" } },
},
);
console.log(response.output_text);
// Ask a follow-up question in the same conversation
const response2 = await openai.responses.create(
{
conversation: conversation.id,
input: "And what is the capital city?",
},
{
body: { agent_reference: { name: AGENT_NAME, type: "agent_reference" } },
},
);
console.log(response2.output_text);
}
main().catch(console.error);
package com.azure.ai.agents;
import com.azure.ai.agents.models.AgentDetails;
import com.azure.ai.agents.models.AgentReference;
import com.azure.ai.agents.models.AzureCreateResponseOptions;
import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.identity.AuthenticationUtil;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.client.okhttp.OpenAIOkHttpClient;
import com.openai.credential.BearerTokenCredential;
import com.openai.models.conversations.Conversation;
import com.openai.models.conversations.items.ItemCreateParams;
import com.openai.models.responses.EasyInputMessage;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;
import com.openai.services.blocking.ConversationService;
public class ChatWithAgent {
public static void main(String[] args) {
// Format: "https://resource_name.ai.azure.com/api/projects/project_name"
String ProjectEndpoint = "your_project_endpoint";
String AgentName = "your_agent_name";
AgentsClientBuilder builder = new AgentsClientBuilder()
.credential(new DefaultAzureCredentialBuilder().build())
.endpoint(ProjectEndpoint);
AgentsClient agentsClient = builder.buildAgentsClient();
ResponsesClient responsesClient = builder.buildResponsesClient();
ConversationService conversationService
= builder.buildOpenAIClient().conversations();
AgentDetails agent = agentsClient.getAgent(AgentName);
Conversation conversation = conversationService.create();
conversationService.items().create(
ItemCreateParams.builder()
.conversationId(conversation.id())
.addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.SYSTEM)
.content("You are a helpful assistant that speaks like a pirate.")
.build()
).addItem(EasyInputMessage.builder()
.role(EasyInputMessage.Role.USER)
.content("Hello, agent!")
.build()
).build()
);
AgentReference agentReference = new AgentReference(agent.getName()).setVersion(agent.getVersion());
Response response = responsesClient.createAzureResponse(
new AzureCreateResponseOptions().setAgentReference(agentReference),
ResponseCreateParams.builder().conversation(conversation.id()));
OpenAIClient client = OpenAIOkHttpClient.builder()
.baseUrl(ProjectEndpoint.endsWith("/") ? ProjectEndpoint + "openai/v1" : ProjectEndpoint + "/openai/v1")
.credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier(
new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default")))
.build();
ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
.input("Hello, how can you help me?")
.model("gpt-5-mini") //supports all Foundry direct models
.build();
Response result = client.responses().create(responseRequest);
}
}
Reemplace YOUR-FOUNDRY-RESOURCE-NAME con sus valores.
# Generate a response using the agent
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"agent_reference": {"type": "agent_reference", "name": "<AGENT_NAME>"},
"input": [{"role": "user", "content": "What is the size of France in square miles?"}]
}'
# Optional Step: Create a conversation to use with the agent
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/v1/conversations \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"items": [
{
"type": "message",
"role": "user",
"content": [
{
"type": "input_text",
"text": "What is the size of France in square miles?"
}
]
}
]
}'
# Lets say Conversation ID created is conv_123456789. Use this in the next step
#Optional Step: Ask a follow-up question in the same conversation
curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/v1/responses \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
-d '{
"agent_reference": {"type": "agent_reference", "name": "<AGENT_NAME>", "version": "1"},
"conversation": "<CONVERSATION_ID>",
"input": [{"role": "user", "content": "And what is the capital?"}]
}'
Verá las respuestas del agente a ambas solicitudes. La respuesta de seguimiento muestra que el agente mantiene el historial de conversaciones entre turnos.
Limpieza de recursos
Si ya no necesita ninguno de los recursos que ha creado, elimine el grupo de recursos asociado al proyecto.
- En el portal Azure, seleccione el grupo de recursos y, a continuación, seleccione Delete. Confirme que desea eliminar el grupo de recursos.
Contenido relacionado