Início Rápido do Microsoft Foundry

Neste guia de início rápido, irá começar a usar modelos e agentes no Foundry.

Tu vais:

• Gerar uma resposta a partir de um modelo
• Crie um agente com um prompt definido
• Realize uma conversa de vários turnos com o agente

Pré-requisitos

• Um modelo implementado no Microsoft Foundry. Se não tiver um modelo, primeiro complete o Quickstart: Configure os recursos do Microsoft Foundry.
• Os tempos de execução da linguagem necessários, ferramentas globais e extensões do Visual Studio Code são descritos em Prepare o seu ambiente de desenvolvimento.

Define variáveis de ambiente e obtém o código

Armazena o endpoint do teu projeto como uma variável de ambiente. Defina também esses valores para uso em seus scripts.

PROJECT_ENDPOINT=<endpoint copied from welcome screen>
AGENT_NAME="MyAgent"
MODEL_DEPLOYMENT_NAME="gpt-4.1-mini"

Python

Acompanhe abaixo ou obtenha o código:

Obter o código

Inicia sessão usando o comando CLI az login para autenticar antes de executar os teus scripts em Python.

C#

Acompanhe abaixo ou obtenha o código:

Obter o código

Inicia sessão usando o comando CLI az login para autenticar antes de executares os teus scripts C#.

TypeScript

Acompanhe abaixo ou obtenha o código:

Obter o código

Inicia sessão usando o comando CLI az login para autenticar antes de executar os teus scripts TypeScript.

Java

Acompanhe abaixo ou obtenha o código:

Obter o código

Inicia sessão usando o comando CLI az login para autenticar antes de executares os teus scripts Java.

API REST

Acompanhe abaixo ou obtenha o código:

Obtenha o código.

1. Inicie sessão usando o comando CLI az login para autenticar antes de executar o próximo comando.

2. Obtenha um token de acesso temporário. Ele expirará em 60-90 minutos, você precisará atualizar depois disso.

   az account get-access-token --scope https://ai.azure.com/.default
   

3. Salve os resultados como a variável AZURE_AI_AUTH_TOKENde ambiente .

Portal da fundição

Não é necessário código ao usar o portal da Foundry.

Instalar e autenticar

Garante que instalas a versão correta de pré-visualização/pré-lançamento dos pacotes como mostrado aqui.

Python

1. Instale estes pacotes, incluindo a versão de pré-visualização de azure-ai-projects. Esta versão utiliza a API (nova) dos projetos Foundry (pré-visualização).

   pip install --pre "azure-ai-projects>=2.0.0b4"
   pip install python-dotenv
   

2. Inicia sessão usando o comando CLI az login para autenticar antes de executar os teus scripts em Python.

C#

1. Instalar pacotes:

   Adicionar pacotes NuGet usando a CLI .NET no terminal integrado: Estes pacotes usam a API (nova) dos projetos Foundry (pré-visualização).

   dotnet add package Azure.AI.Projects --prerelease
   dotnet add package Azure.AI.Projects.OpenAI --prerelease
   dotnet add package Azure.Identity
   

2. Inicia sessão usando o comando CLI az login para autenticar antes de executares os teus scripts C#.

TypeScript

1. Instale estes pacotes, incluindo a versão de pré-visualização de @azure/ai-projects. Esta versão utiliza a API (nova) dos projetos Foundry (pré-visualização).:

   npm install @azure/ai-projects@beta @azure/identity dotenv
   

2. Inicia sessão usando o comando CLI az login para autenticar antes de executar os teus scripts TypeScript.

Java

1. Inicia sessão usando o comando CLI az login para autenticar antes de executares os teus scripts Java.

API REST

1. Inicie sessão usando o comando CLI az login para autenticar antes de executar o próximo comando.

2. Obtenha um token de acesso temporário. Ele expirará em 60-90 minutos, você precisará atualizar depois disso.

   az account get-access-token --scope https://ai.azure.com/.default
   

3. Salve os resultados como a variável AZURE_AI_AUTH_TOKENde ambiente .

Portal da fundição

Não é necessária qualquer instalação para utilizar o portal da Foundry.

Sugestão

O código usa o Azure AI Projects 2.x e é incompatível com o Azure AI Projects 1.x. Consulte a documentação do Foundry (clássico) para a versão Azure AI Projects 1.x.

Bate-papo com um modelo

Interagir com um modelo é o bloco de construção básico das aplicações de IA. Envie uma entrada e receba uma resposta do modelo:

Python

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

load_dotenv()

print(f"Using PROJECT_ENDPOINT: {os.environ['PROJECT_ENDPOINT']}")
print(f"Using MODEL_DEPLOYMENT_NAME: {os.environ['MODEL_DEPLOYMENT_NAME']}")

project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

openai_client = project_client.get_openai_client()

response = openai_client.responses.create(
    model=os.environ["MODEL_DEPLOYMENT_NAME"],
    input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")

C#

using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI;
using OpenAI.Responses;

#pragma warning disable OPENAI001

string projectEndpoint  = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Missing environment variable 'PROJECT_ENDPOINT'");
string modelDeploymentName  = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("Missing environment variable 'MODEL_DEPLOYMENT_NAME'");

AIProjectClient projectClient = new(new Uri(projectEndpoint ), new AzureCliCredential());

ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForModel(modelDeploymentName);
ResponseResult response = await responseClient.CreateResponseAsync("What is the size of France in square miles?");

Console.WriteLine(response.GetOutputText());

TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";

async function main(): Promise<void> {
    const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
    const openAIClient = await project.getOpenAIClient();
    const response = await openAIClient.responses.create({
        model: deploymentName,
        input: "What is the size of France in square miles?",
    });
    console.log(`Response output: ${response.output_text}`);
}

main().catch(console.error);

Java

package com.azure.ai.agents;

import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class CreateResponse {
    public static void main(String[] args) {
        String endpoint = Configuration.getGlobalConfiguration().get("PROJECT_ENDPOINT");
        String model = Configuration.getGlobalConfiguration().get("MODEL_DEPLOYMENT_NAME");
        // Code sample for creating a response
        ResponsesClient responsesClient = new AgentsClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint(endpoint)
                .serviceVersion(AgentsServiceVersion.V2025_11_15_PREVIEW)
                .buildResponsesClient();

        ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
                .input("Hello, how can you help me?")
                .model(model)
                .build();

        Response response = responsesClient.getResponseService().create(responseRequest);

        System.out.println("Response ID: " + response.id());
        System.out.println("Response Model: " + response.model());
        System.out.println("Response Created At: " + response.createdAt());
        System.out.println("Response Output: " + response.output());
    }
}

API REST

Substitua YOUR-FOUNDRY-RESOURCE-NAME pelos seus valores:

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 '{
        "model": "gpt-4.1-mini",
        "input": "What is the size of France in square miles?"
}'

Portal da fundição

1. Depois que o modelo for implantado, você será automaticamente movido de Início para a seção Compilação . O seu novo modelo está selecionado e pronto para experimentar.

2. Comece a conversar com seu modelo, por exemplo: "Escreva-me um poema sobre flores".

Depois de executar o código, vês uma resposta gerada por modelo na consola (por exemplo, um poema curto ou uma resposta ao teu prompt). Isto confirma que o endpoint do projeto, a autenticação e a implementação do modelo estão a funcionar corretamente.

Sugestão

O código usa o Azure AI Projects 2.x e é incompatível com o Azure AI Projects 1.x. Consulte a documentação do Foundry (clássico) para a versão Azure AI Projects 1.x.

Criar um agente

Crie um agente usando seu modelo implantado.

Um agente define o comportamento principal. Uma vez criado, ele garante respostas consistentes nas interações do usuário sem repetir instruções a cada vez. Você pode atualizar ou excluir agentes a qualquer momento.

Python

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition

load_dotenv()

project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

agent = project_client.agents.create_version(
    agent_name=os.environ["AGENT_NAME"],
    definition=PromptAgentDefinition(
        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        instructions="You are a helpful assistant that answers general questions",
    ),
)
print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

C#

using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;

string projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Missing environment variable 'PROJECT_ENDPOINT'");
string modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("Missing environment variable 'MODEL_DEPLOYMENT_NAME'");
string agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
    ?? throw new InvalidOperationException("Missing environment variable 'AGENT_NAME'");

AIProjectClient projectClient = new(new Uri(projectEndpoint), new AzureCliCredential());

AgentDefinition agentDefinition = new PromptAgentDefinition(modelDeploymentName)
{
    Instructions = "You are a helpful assistant that answers general questions",
};

AgentVersion newAgentVersion = projectClient.Agents.CreateAgentVersion(
    agentName,
    options: new(agentDefinition));

List<AgentVersion> agentVersions = projectClient.Agents.GetAgentVersions(agentName);
foreach (AgentVersion agentVersion in agentVersions)
{
    Console.WriteLine($"Agent: {agentVersion.Id}, Name: {agentVersion.Name}, Version: {agentVersion.Version}");
}

TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";

async function main(): Promise<void> {
    const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
    const agent = await project.agents.createVersion("my-agent-basic", {
        kind: "prompt",
        model: deploymentName,
        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);

Java

package com.azure.ai.agents;

import com.azure.ai.agents.models.AgentVersionDetails;
import com.azure.ai.agents.models.PromptAgentDefinition;
import com.azure.core.util.Configuration;
import com.azure.identity.DefaultAzureCredentialBuilder;

public class CreateAgent {
    public static void main(String[] args) {
        String endpoint = Configuration.getGlobalConfiguration().get("PROJECT_ENDPOINT");
        String model = Configuration.getGlobalConfiguration().get("MODEL_DEPLOYMENT_NAME");
        // Code sample for creating an agent
        AgentsClient agentsClient = new AgentsClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint(endpoint)
                .buildAgentsClient();

        PromptAgentDefinition request = new PromptAgentDefinition(model);
        AgentVersionDetails agent = agentsClient.createAgentVersion("MyAgent", request);

        System.out.println("Agent ID: " + agent.getId());
        System.out.println("Agent Name: " + agent.getName());
        System.out.println("Agent Version: " + agent.getVersion());
    }
}

API REST

Substitua YOUR-FOUNDRY-RESOURCE-NAME pelos seus 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"
    }
  }'

Portal da fundição

Agora crie um agente e interaja com ele.

1. Ainda na seção Compilar , selecione Agentes no painel esquerdo.
2. Selecione Criar agente e atribua-lhe um nome.

A saída confirma que o agente foi criado. Para separadores do SDK, vês o nome e o ID do agente impressos na consola.

Sugestão

O código usa o Azure AI Projects 2.x e é incompatível com o Azure AI Projects 1.x. Consulte a documentação do Foundry (clássico) para a versão Azure AI Projects 1.x.

Conversar com um agente

Utilize o agente previamente criado chamado "MyAgent" para interagir, fazendo uma pergunta e seguindo com uma questão relacionada. A conversa mantém o histórico destas interações.

Python

import os
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient

load_dotenv()

project_client = AIProjectClient(
    endpoint=os.environ["PROJECT_ENDPOINT"],
    credential=DefaultAzureCredential(),
)

agent_name = os.environ["AGENT_NAME"]
openai_client = project_client.get_openai_client()

# Optional Step: Create a conversation to use with the agent
conversation = openai_client.conversations.create()
print(f"Created conversation (id: {conversation.id})")

# Chat with the agent to answer questions
response = openai_client.responses.create(
    conversation=conversation.id, #Optional conversation context for multi-turn
    extra_body={"agent_reference": {"name": agent_name, "type": "agent_reference"}},
    input="What is the size of France in square miles?",
)
print(f"Response output: {response.output_text}")

# Optional Step: Ask a follow-up question in the same conversation
response = openai_client.responses.create(
    conversation=conversation.id,
    extra_body={"agent_reference": {"name": agent_name, "type": "agent_reference"}},
    input="And what is the capital city?",
)
print(f"Response output: {response.output_text}")

C#

using Azure.AI.Projects;
using Azure.AI.Projects.OpenAI;
using Azure.Identity;
using OpenAI.Responses;

#pragma warning disable OPENAI001

string projectEndpoint = Environment.GetEnvironmentVariable("PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("Missing environment variable 'PROJECT_ENDPOINT'");
string modelDeploymentName = Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME")
    ?? throw new InvalidOperationException("Missing environment variable 'MODEL_DEPLOYMENT_NAME'");
string agentName = Environment.GetEnvironmentVariable("AGENT_NAME")
    ?? throw new InvalidOperationException("Missing environment variable 'AGENT_NAME'");

AIProjectClient projectClient = new(new Uri(projectEndpoint), new AzureCliCredential());

// Optional Step: Create a conversation to use with the agent
ProjectConversation conversation = projectClient.OpenAI.Conversations.CreateProjectConversation();

ProjectResponsesClient responsesClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(
    defaultAgent: agentName,
    defaultConversationId: conversation.Id);

// Chat with the agent to answer questions
ResponseResult response = responsesClient.CreateResponse("What is the size of France in square miles?");
Console.WriteLine(response.GetOutputText());

// Optional Step: Ask a follow-up question in the same conversation
response = responsesClient.CreateResponse("And what is the capital city?");
Console.WriteLine(response.GetOutputText());

TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import { AIProjectClient } from "@azure/ai-projects";
import "dotenv/config";

const projectEndpoint = process.env["PROJECT_ENDPOINT"] || "<project endpoint>";
const deploymentName = process.env["MODEL_DEPLOYMENT_NAME"] || "<model deployment name>";

async function main(): Promise<void> {
    const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
    const openAIClient = await project.getOpenAIClient();
    
    // Create agent
    console.log("Creating agent...");
    const agent = await project.agents.createVersion("my-agent-basic", {
        kind: "prompt",
        model: deploymentName,
        instructions: "You are a helpful assistant that answers general questions",
    });
    console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
    
    // Create conversation with initial user message
    // You can save the conversation ID to database to retrieve later
    console.log("\nCreating conversation with initial user message...");
    const conversation = await openAIClient.conversations.create({
        items: [
            { type: "message", role: "user", content: "What is the size of France in square miles?" },
        ],
    });
    console.log(`Created conversation with initial user message (id: ${conversation.id})`);

    // Generate response using the agent
    console.log("\nGenerating response...");
    const response = await openAIClient.responses.create(
        {
            conversation: conversation.id,
        },
        {
            body: { agent: { name: agent.name, type: "agent_reference" } },
        },
    );
    console.log(`Response output: ${response.output_text}`);

     // Clean up
    console.log("\nCleaning up resources...");
    await openAIClient.conversations.delete(conversation.id);
    console.log("Conversation deleted");

    await project.agents.deleteVersion(agent.name, agent.version);
    console.log("Agent deleted");
}

main().catch(console.error);

Java

package com.azure.ai.agents;

import com.azure.ai.agents.models.AgentReference;
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.azure.AzureOpenAIServiceVersion;
import com.openai.azure.AzureUrlPathMode;
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;

public class ChatWithAgent {
    public static void main(String[] args) {
        String endpoint = Configuration.getGlobalConfiguration().get("AZURE_AGENTS_ENDPOINT");
        String agentName = "MyAgent";
        
        AgentsClient agentsClient = new AgentsClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint(endpoint)
                .buildAgentsClient();

        AgentDetails agent = agentsClient.getAgent(agentName);

        Conversation conversation = conversationsClient.getConversationService().create();
        conversationsClient.getConversationService().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.createWithAgentConversation(agentReference, conversation.id());

        OpenAIClient client = OpenAIOkHttpClient.builder()
            .baseUrl(endpoint.endsWith("/") ? endpoint + "openai" : endpoint + "/openai")
            .azureUrlPathMode(AzureUrlPathMode.UNIFIED)
            .credential(BearerTokenCredential.create(AuthenticationUtil.getBearerTokenSupplier(
                    new DefaultAzureCredentialBuilder().build(), "https://ai.azure.com/.default")))
            .azureServiceVersion(AzureOpenAIServiceVersion.fromString("2025-11-15-preview"))
            .build();

        ResponseCreateParams responseRequest = new ResponseCreateParams.Builder()
            .input("Hello, how can you help me?")
            .model(model)
            .build();

        Response result = client.responses().create(responseRequest);
    }
}

API REST

Substitua YOUR-FOUNDRY-RESOURCE-NAME pelos seus 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?"}]
  }'

Portal da fundição

Interaja com seu agente.

1. Adicione instruções, como "Você é um assistente de escrita útil."
2. Comece a conversar com seu agente, por exemplo, "Escreva um poema sobre o sol".
3. Acompanhe com "Que tal um haiku?"

Vês as respostas do agente a ambos os prompts. A resposta de seguimento demonstra que o agente mantém o histórico de conversas entre turnos.

Sugestão

O código usa o Azure AI Projects 2.x e é incompatível com o Azure AI Projects 1.x. Consulte a documentação do Foundry (clássico) para a versão Azure AI Projects 1.x.

Limpeza de recursos

Se você não precisar mais de nenhum dos recursos criados, exclua o grupo de recursos associado ao seu projeto.

• No portal Azure, selecione o grupo de recursos e depois selecione Eliminar. Confirme que deseja excluir o grupo de recursos.

Próximo passo

Ideia para prototipar - Construir e avaliar um agente empresarial