Quickstart: Een promptagent maken

In deze quickstart maakt u een promptagent in Foundry Agent Service en voert u er een gesprek mee. Een promptagent is een declaratief gedefinieerde agent die een model uit de Foundry-modelcatalogus, instructies, hulpprogramma's en prompts voor natuurlijke taal combineert om gedrag te stimuleren.

Als u geen Azure abonnement hebt, maakt u een free-account.

Voorwaarden

• Een model dat is geïmplementeerd in Microsoft Foundry. Als u geen model hebt, voltooit u eerst Quickstart: Microsoft Foundry-resources instellen.
• De vereiste taalruntimes, globale hulpprogramma's en Visual Studio Code-extensies, zoals beschreven in Prepareer uw ontwikkelomgeving.

Uw projecteindpunt ophalen

Kopieer uw projecteindpunt vanuit het welkomstscherm in de Foundry-portal.

De codevoorbeelden in deze quickstart declareren hun waarden als constanten boven aan elk bestand. Voordat u een voorbeeld uitvoert, vervangt u deze tijdelijke aanduidingen:

• your_project_endpoint: Uw projecteindpunt, in de indeling https://<resource-name>.services.ai.azure.com/api/projects/<project-name>.
• your_agent_name: Een naam voor uw agent, zoals MyAgent.

Pakketten installeren en verifiëren

Zorg ervoor dat u de juiste versie van de pakketten installeert, zoals hier wordt weergegeven.

Python

1. Installeer de huidige versie van azure-ai-projects. Deze versie maakt gebruik van de Foundry-projecten (nieuwe) API. De voorbeelden authenticeren met behulp van DefaultAzureCredential, dat afkomstig is van azure-identity.

   pip install "azure-ai-projects>=2.3.0" azure-identity
   

2. Meld u aan met de OPDRACHT CLI az login om te verifiëren voordat u uw Python-scripts uitvoert.

C#

1. Pakketten installeren:

   Voeg NuGet-pakketten toe met behulp van de .NET CLI in de geïntegreerde terminal: deze pakketten gebruiken de nieuwe API van Foundry-projecten.

   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
   

2. Meld u aan met de CLI-opdracht az login om te verifiëren voordat u uw C#-scripts uitvoert.

TypeScript

1. Installeer de huidige versie van @azure/ai-projects. Deze versie maakt gebruik van de Foundry-projecten (nieuwe) API.:

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

2. Meld u aan met de CLI-opdracht az login om te verifiëren voordat u uw TypeScript-scripts uitvoert.

Java

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-ai-agents</artifactId>
    <version>2.2.0</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-core</artifactId>
    <version>1.57.0</version>
</dependency>
<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-identity</artifactId>
    <version>1.18.1</version>
</dependency>

1. Meld u aan met de CLI-opdracht az login om te verifiëren voordat u uw Java scripts uitvoert.

REST API

1. Meld u aan met de CLI-opdracht az login om te verifiëren voordat u de volgende opdracht uitvoert.

2. Een tijdelijk toegangstoken ophalen. Het verloopt na 60-90 minuten. Daarna moet u vernieuwen.

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

3. Sla de resultaten op als de omgevingsvariabele AZURE_AI_AUTH_TOKEN.

Foundryportal

Er is geen installatie nodig om de Foundry-portal te gebruiken.

Tip

Code maakt gebruik van Azure AI Projects 2.x en is niet compatibel met Azure AI Projects 1.x. Raadpleeg de documentatie voor Foundry (klassiek) voor de versie Azure AI Projects 1.x.

Een promptagent maken

Maak een promptagent met behulp van uw geïmplementeerde model. De agent gebruikt een PromptAgentDefinition met instructies waarmee het gedrag van de agent wordt gedefinieerd. U kunt agents op elk gewenst moment bijwerken of verwijderen.

Python

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

C#

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

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var foundryProjectEndpoint = "your_project_endpoint";
var foundryAgentName = "your_agent_name";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(foundryProjectEndpoint),
    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(
    foundryAgentName,
    options: new(agentDefinition));
Console.WriteLine($"Agent created (id: {agent.Id}, name: {agent.Name}, version: {agent.Version})");

TypeScript

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

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint";
const FOUNDRY_AGENT_NAME = "your_agent_name";

async function main(): Promise<void> {
    // Create project client to call Foundry API
    const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());

    // Create an agent with a model and instructions
    const agent = await project.agents.createVersion(FOUNDRY_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);

Java

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.services.ai.azure.com/api/projects/project_name"
        String foundryProjectEndpoint = "your_project_endpoint";
        String foundryAgentName = "your_agent_name";

        // Create agents client to call Foundry API
        AgentsClient agentsClient = new AgentsClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint(foundryProjectEndpoint)
                .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(foundryAgentName, request);

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

REST API

Vervang YOUR-FOUNDRY-RESOURCE-NAME door uw waarden:

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-5-mini",
      "instructions": "You are a helpful assistant that answers general questions"
    }
  }'

De uitvoer bevestigt dat de agent is gemaakt. U ziet de naam en id van de agent die in de console worden afgedrukt.

Chatten met de agent

Gebruik de agent die u hebt gemaakt om te communiceren door een vraag en een gerelateerde opvolging te stellen. Het gesprek onderhoudt de geschiedenis van deze interacties.

Python

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

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

C#

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

#pragma warning disable OPENAI001

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
var foundryProjectEndpoint = "your_project_endpoint";
var foundryAgentName = "your_agent_name";

// Create project client to call Foundry API
AIProjectClient projectClient = new(
    endpoint: new Uri(foundryProjectEndpoint),
    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: foundryAgentName,
    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());

TypeScript

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

// Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
const FOUNDRY_PROJECT_ENDPOINT = "your_project_endpoint";
const FOUNDRY_AGENT_NAME = "your_agent_name";

async function main(): Promise<void> {
    // Create project and openai clients to call Foundry API
    const project = new AIProjectClient(FOUNDRY_PROJECT_ENDPOINT, new DefaultAzureCredential());
    const openai = project.getOpenAIClient({
        azureConfig: { allowPreview: true, agentName: FOUNDRY_AGENT_NAME },
    });

    // 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?",
    });
    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?",
    });
    console.log(response2.output_text);
}

main().catch(console.error);

Java

package com.azure.ai.agents;

import com.azure.identity.DefaultAzureCredentialBuilder;
import com.openai.client.OpenAIClient;
import com.openai.models.conversations.Conversation;
import com.openai.models.responses.Response;
import com.openai.models.responses.ResponseCreateParams;

public class ChatWithAgent {
    public static void main(String[] args) {
        // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name"
        String foundryProjectEndpoint = "your_project_endpoint";
        String foundryAgentName = "your_agent_name";
        
        AgentsClientBuilder builder = new AgentsClientBuilder()
                .credential(new DefaultAzureCredentialBuilder().build())
                .endpoint(foundryProjectEndpoint);

        // Create an OpenAI client bound to the agent endpoint
        OpenAIClient openai = builder.buildAgentScopedOpenAIClient(foundryAgentName);

        // Create a conversation for multi-turn chat
        Conversation conversation = openai.conversations().create();

        // Chat with the agent to answer questions
        Response response = openai.responses().create(
            ResponseCreateParams.builder()
                .conversation(conversation.id())
                .input("What is the size of France in square miles?")
                .build());
        printResponse(response);

        // Ask a follow-up question in the same conversation
        Response followUp = openai.responses().create(
            ResponseCreateParams.builder()
                .conversation(conversation.id())
                .input("And what is the capital city?")
                .build());
        printResponse(followUp);
    }

    private static void printResponse(Response response) {
        response.output().forEach(item -> item.message().ifPresent(message ->
            message.content().forEach(content -> content.outputText().ifPresent(
                text -> System.out.println(text.text())))));
    }
}

REST API

Vervang YOUR-FOUNDRY-RESOURCE-NAME door uw waarden en stel de FOUNDRY_AGENT_NAME omgevingsvariabele in op de naam van de agent die u hebt gebruikt:

# Generate a response using the agent

curl -X POST "https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/responses?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
  -d '{
    "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/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/conversations?api-version=v1" \
  -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/agents/${FOUNDRY_AGENT_NAME}/endpoint/protocols/openai/responses?api-version=v1" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
  -d '{
    "conversation": "<CONVERSATION_ID>",
    "input": [{"role": "user", "content": "And what is the capital?"}]
  }'

U ziet de antwoorden van de agent op beide prompts. Het vervolgantwoord laat zien dat de agent de gespreksgeschiedenis om de beurt onderhoudt.

Resources opschonen

Als u geen resources meer nodig hebt die u hebt gemaakt, verwijdert u de resourcegroep die aan uw project is gekoppeld.

• Selecteer in de Azure portal de resourcegroep en selecteer vervolgens Uitwijderen. Bevestig dat u de resourcegroep wilt verwijderen.

Verwante inhoud

• Levenscyclus van agentontwikkeling
• Wat is de Foundry Agent-dienst?
• Hulpprogramma's gebruiken met agenten
• Quickstart: Uw eerste gehoste agent implementeren