> ## Documentation Index
> Fetch the complete documentation index at: https://hobbyist-e43fa225.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart: Create a prompt agent

> Create a prompt agent in Foundry Agent Service using the Microsoft Foundry SDK.

In this quickstart, you create a prompt agent in Foundry Agent Service and have a conversation with it. A prompt agent is a declaratively defined agent that combines a model from the Foundry model catalog, instructions, tools, and natural language prompts to drive behavior.

If you don't have an Azure subscription, create a [free account](https://azure.microsoft.com/pricing/purchase-options/azure-account?cid=msft_learn).

## Prerequisites

* A model deployed in Microsoft Foundry. If you don't have a model, first complete [Quickstart: Set up Microsoft Foundry resources](/get-started/quickstart-create-foundry-resources).
* The required language runtimes, global tools, and Visual Studio Code extensions as described in [Prepare your development environment](/developer-tools-and-integrations/install-cli-sdk).

## Set environment variables

Store [your project endpoint](/get-started/quickstart-create-foundry-resources#get-your-project-connection-details) as an environment variable. Also set these values for use in your scripts.

**Python and JavaScript**

```
PROJECT_ENDPOINT=<endpoint copied from welcome screen>
AGENT_NAME="MyAgent"
```

**C# and Java**

```
ProjectEndpoint = <endpoint copied from welcome screen>
AgentName = "MyAgent"
```

## Install packages and authenticate

Make sure you install the correct version of the packages as shown here.

<Tabs>
  <Tab title="Python">
    1. Install the current version of `azure-ai-projects`. This version uses the **Foundry projects (new) API** .

       ```
       pip install azure-ai-projects>=2.3.0
       ```

    2. Sign in using the CLI `az login` command to authenticate before running your Python scripts.
  </Tab>

  <Tab title="C#">
    1. Install packages:

       Add NuGet packages using the .NET CLI in the integrated terminal: These packages use the **Foundry projects (new) API**.

       ```bash theme={null}
       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. Sign in using the CLI `az login` command to authenticate before running your C# scripts.
  </Tab>

  <Tab title="TypeScript">
    1. Install the current version of `@azure/ai-projects`. This version uses the **Foundry projects (new) API**.:

       ```bash theme={null}
       npm install @azure/ai-projects
       ```

    2. Sign in using the CLI `az login` command to authenticate before running your TypeScript scripts.
  </Tab>

  <Tab title="Java">
    ```xml theme={null}
    <dependency>
        <groupId>com.azure</groupId>
        <artifactId>azure-ai-agents</artifactId>
        <version>2.2.0</version>
    </dependency>
    ```

    1. Sign in using the CLI `az login` command to authenticate before running your Java scripts.
  </Tab>

  <Tab title="REST API">
    1. Sign in using the CLI `az login` command to authenticate before running the next command.

    2. Get a temporary access token. It will expire in 60-90 minutes, you'll need to refresh after that.

       ```azurecli theme={null}
       az account get-access-token --scope https://ai.azure.com/.default
       ```

    3. Save the results as the environment variable `AZURE_AI_AUTH_TOKEN`.
  </Tab>

  <Tab title="Foundry portal">
    No installation is necessary to use the Foundry portal.
  </Tab>
</Tabs>

<Tip>
  Code uses **Azure AI Projects 2.x** and is incompatible with Azure AI Projects 1.x. [See the Foundry (classic) documentation](../../foundry-classic/index.yml)  for the Azure AI Projects 1.x version.
</Tip>

## Create a prompt agent

Create a prompt agent using your deployed model. The agent uses a `PromptAgentDefinition` with instructions that define the agent's behavior. You can update or delete agents anytime.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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})")
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    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}");
    }
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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());
        }
    }
    ```
  </Tab>

  <Tab title="REST API">
    Replace `YOUR-FOUNDRY-RESOURCE-NAME` with your values:

    ```console theme={null}
    curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/agents?api-version=2025-11-15-preview \
      -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"
            }
        }'
    ```
  </Tab>
</Tabs>

The output confirms the agent was created. You see the agent name and ID printed to the console.

## Chat with the agent

Use the agent you created to interact by asking a question and a related follow-up. The conversation maintains history across these interactions.

<Tabs>
  <Tab title="Python">
    ```python theme={null}
    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}")
    ```
  </Tab>

  <Tab title="C#">
    ```csharp theme={null}
    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());
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript theme={null}
    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 = 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);
    ```
  </Tab>

  <Tab title="Java">
    ```java theme={null}
    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);
        }
    }
    ```
  </Tab>

  <Tab title="REST API">
    Replace `YOUR-FOUNDRY-RESOURCE-NAME` with your values:

    ```console theme={null}
    # 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/conversations?api-version=2025-11-15-preview \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
      -d '{}'
    # Lets say Conversation ID created is conv_123456789. Use this in the next step

    #Chat with the agent to answer questions
    curl -X POST https://YOUR-FOUNDRY-RESOURCE-NAME.services.ai.azure.com/api/projects/YOUR-PROJECT-NAME/openai/responses?api-version=2025-11-15-preview \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
      -d '{
            "agent": {"type": "agent_reference", "name": "MyAgent"},
            "conversation" : "<YOUR_CONVERSATION_ID>",
            "input" : "What is the size of France in square miles?"
        }'

    #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/responses?api-version=2025-11-15-preview \
      -H "Content-Type: application/json" \
      -H "Authorization: Bearer $AZURE_AI_AUTH_TOKEN" \
      -d '{
            "agent": {"type": "agent_reference", "name": "MyAgent"},
            "conversation" : "<YOUR_CONVERSATION_ID>",
            "input" : "And what is the capital city?"
        }'
    ```
  </Tab>
</Tabs>

You see the agent's responses to both prompts. The follow-up response demonstrates that the agent maintains conversation history across turns.

## Clean up resources

If you no longer need any of the resources you created, delete the resource group associated with your project.

* In the [Azure portal](https://portal.azure.com), select the resource group, and then select **Delete**. Confirm that you want to delete the resource group.

## Related content

* [Agent development lifecycle](/agents/development-lifecycle)
* [What is Foundry Agent Service?](/agents/overview)
* [Use tools with agents](/tools-and-knowledge/model-context-protocol)
* [Quickstart: Deploy your first hosted agent](/agents/quickstart-hosted-agent)