diff --git a/docs/agents/voice-agent-telephony-channels.mdx b/docs/agents/voice-agent-telephony-channels.mdx index b15bcaf7..da41303c 100644 --- a/docs/agents/voice-agent-telephony-channels.mdx +++ b/docs/agents/voice-agent-telephony-channels.mdx @@ -5,7 +5,7 @@ description: "Integrate Microsoft Teams Phone or Twilio with a Microsoft Foundry import { ZoneContent, ZonePivot } from "/snippets/zone-pivot.jsx" -You can now directly import a phone number you purchased from Teams and connect it to your voice agent. +You can now directly import a phone number you purchased from a telephony provider and connect it to your voice agent. @@ -13,37 +13,14 @@ Items marked (preview) in this article are currently in public preview. This pre -## Prerequisites - -- [Get Microsoft Teams Calling Plan phone numbers for your tenant](https://learn.microsoft.com/microsoftteams/getting-phone-numbers-for-your-users). -- Follow the setup for [Teams Phone System extensibility](https://learn.microsoft.com/azure/communication-services/quickstarts/tpe/teams-phone-extensibility-quickstart). -- A saved voice-first agent in a Foundry project that passes browser testing. See [Quickstart: Create a voice-first prompt agent](/get-started/prompt-voice-agent). -- [Foundry User role](../../concepts/rbac-foundry) on the project, to create and manage telephony bindings. - - - - - -> The Foundry RBAC roles were recently renamed. **Foundry User**, **Foundry Owner**, **Foundry Account Owner**, and **Foundry Project Manager** were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename. - - Permission to update the agent and its channels. - - Access to the selected Azure Communication Services resource. - - Permission to create or update a Foundry project connection. - - Permission to create or update telephony bindings. - - Event Grid write permission on the Azure Communication Services resource. - - Help from a tenant administrator when secure webhook setup requires Microsoft Entra application or app-role changes. - -The current project-managed-identity flow requires the Foundry project and Azure Communication Services resource to be in the same Microsoft Entra tenant. - -### Twilio prerequisites - -For the Twilio path, you need: +## Compare the channel integrations -- A Twilio account with at least one active, voice-capable phone number. -- The Twilio Account SID and Primary Auth Token if you need to create a Foundry project connection. -- Permission to create or read connections in the Foundry project. -- Permission to create telephony bindings for the agent. +| Path | Use it when | What you provide in Foundry | +| --- | --- | --- | +| Microsoft Teams | Your organization owns a service number in Teams and routes it through a Teams resource account to Azure Communication Services. | Teams resource-account object ID| +| Twilio | Your organization owns one or more active voice-capable numbers in Twilio. | Twilio Account SID and Auth Token. | -Treat the Twilio Auth Token as a secret. Enter it only in the Foundry connection dialog, and don't include it in documentation, logs, screenshots, or support requests. +The Twilio option appears only in supported public-cloud environments. ## Understand the call path @@ -70,58 +47,52 @@ Because the Teams number stays in Teams, the agent can act as one destination am For Twilio, Foundry uses the selected project connection to discover the numbers in your Twilio account and create a binding for each number you select. You don't create an Azure Communication Services resource or Event Grid subscription for the Twilio path. -## Compare the channel integrations - -| Path | Use it when | What you provide in Foundry | -| --- | --- | --- | -| Microsoft Teams Phone Extensibility | Your organization owns a service number in Teams and routes it through a Teams resource account to Azure Communication Services. | `28:orgid:` | -| Twilio | Your organization owns one or more active voice-capable numbers in Twilio. | An existing Twilio project connection, or the Account SID and Primary Auth Token for a new connection. | - -Direct SIP and Azure Communication Services purchased numbers aren't supported customer options in the current **Add a number** menu. The Twilio option appears only in supported public-cloud environments. +## Prerequisites -## Understand telephony bindings +### Voice agent prerequisites -A telephony binding connects a provider-specific destination to one voice agent in your project. For a Teams Phone REST binding, set `provider` to `teams_phone_extension` and pass the resource account GUID in `resource_account_object_id`. The incoming-call identifier `28:orgid:{resource-account-guid}` isn't the value of that REST property. +- A saved voice-first agent in a Foundry project that passes browser testing. See [Quickstart: Create a voice-first prompt agent](/get-started/prompt-voice-agent). +- [Foundry User role](../../concepts/rbac-foundry) on the project, to create and manage telephony bindings. -A binding holds: + -- A service-generated binding `id`. -- The provider and its destination, such as the Teams resource account object ID. -- A `status` of `active` or `suspended`, which lets you take a number offline without deleting the mapping. -- A `connection` that names the Foundry project connection for your provider. Secrets aren't stored in the binding itself. -- An `incoming_call_url` that the service generates for incoming-call delivery. + -The agent that owns the binding is identified by the request path. Create and list bindings at `{projectEndpoint}/agents/{agentName}/telephony/bindings`. To get, update, or delete one binding, append `/{bindingId}`. +> The Foundry RBAC roles were recently renamed. **Foundry User**, **Foundry Owner**, **Foundry Account Owner**, and **Foundry Project Manager** were previously named Azure AI User, Azure AI Owner, Azure AI Account Owner, and Azure AI Project Manager. You might still see the previous names in some places while the rename rolls out. The role IDs and core permissions are unchanged by the rename. -Binding reads return an `ETag`. Send that value in `If-Match` when updating or deleting the binding to avoid overwriting a concurrent change. Transfer targets are configured separately for the agent, not on each binding. +### Teams Phone prerequisites -## Prepare Microsoft Teams Phone Extensibility +For the Teams path, you need: +- [Get Microsoft Teams Calling Plan phone numbers for your tenant](/microsoftteams/getting-phone-numbers-for-your-users). +- A Teams or Microsoft 365 administrator usually completes these steps: -A Teams or Microsoft 365 administrator usually completes these steps. + - Follow [Teams Phone System extensibility quick start](https://learn.microsoft.com/azure/communication-services/quickstarts/tpe/teams-phone-extensibility-quickstart) to provision the application, bot, resource account, and Azure Communication Services association. + - Create or select the Azure Communication Services resource that receives calls for the resource account. + - Create the Teams resource account with the Phone Extensibility application ID. + - Associate the resource account with the Azure Communication Services resource, and synchronize the resource account. + - Acquire a Teams service number and assign it to the resource account. The number can use Calling Plan, Operator Connect, or Direct Routing according to your Teams telephony configuration. + - Assign the **Microsoft Teams Phone Resource Account** license when required. + - Provide Azure Communication Services server consent for the exact tenant and resource-account object ID. + - Place a controlled call and confirm that Azure Communication Services emits `Microsoft.Communication.IncomingCall`. -1. Follow [Teams Phone System extensibility quick start](https://learn.microsoft.com/azure/communication-services/quickstarts/tpe/teams-phone-extensibility-quickstart) to provision the application, bot, resource account, and Azure Communication Services association. -1. Create or select the Azure Communication Services resource that receives calls for the resource account. -1. Create the Teams resource account with the Phone Extensibility application ID. -1. Associate the resource account with the Azure Communication Services resource, and synchronize the resource account. -1. Acquire a Teams service number and assign it to the resource account. The number can use Calling Plan, Operator Connect, or Direct Routing according to your Teams telephony configuration. -1. Assign the **Microsoft Teams Phone Resource Account** license when required. -1. Provide Azure Communication Services server consent for the exact tenant and resource-account object ID. -1. Place a controlled call and confirm that Azure Communication Services emits `Microsoft.Communication.IncomingCall`. +- The Foundry owner needs to prepare: + - The callable Teams number. + - The Azure Communication Services ARM resource ID. + - The resource-account object ID. + - Confirmation that Azure Communication Services received the test call. -Provide the Foundry owner with: +The current project-managed-identity flow requires the Foundry project and Azure Communication Services resource to be in the same Microsoft Entra tenant. -- The callable Teams number. -- The Azure Communication Services ARM resource ID. -- The resource-account object ID. -- Confirmation that Azure Communication Services received the test call. +{/* Screenshot: Teams resource account showing the service number and application association. Alt text: "Teams resource account with its assigned service number and Phone Extensibility application." */} -The expected incoming destination is: +### Twilio prerequisites -```text -28:orgid: -``` +For the Twilio path, you need: -{/* Screenshot: Teams resource account showing the service number and application association. Alt text: "Teams resource account with its assigned service number and Phone Extensibility application." */} +- A [Twilio](https://www.twilio.com/phone-numbers) account with at least one active, voice-capable phone number. +- The Twilio **Account SID** and **Auth Token** if you need to create a Foundry project connection. + +Treat the Twilio Auth Token as a secret. Enter it only in the Foundry connection dialog, and don't include it in documentation, logs, screenshots, or support requests. @@ -152,8 +123,7 @@ When **Secure incoming-call delivery** is shown, choose the approved mode. | Option | Use it when | | --- | --- | | **Automatic configuration (Recommended)** | Use when the tenant allows Foundry to create or update the webhook app, app-role assignments, and Event Grid subscription. | -| **Use a customer-managed app registration and let Foundry configure Event Grid** | Use an approved dedicated single-tenant application. The signed-in user must own it or an administrator must complete the changes. | -| **Event Grid and app registration are already configured** | Use only when authenticated Event Grid delivery to the exact Foundry webhook is already complete. Foundry skips that bootstrap work. | +| **Manual configuration** | **Use a customer-managed app registration and let Foundry configure Event Grid** - Use an approved dedicated single-tenant application. The signed-in user must own it or an administrator must complete the changes. Or **Event Grid and app registration are already configured** - Use only when authenticated Event Grid delivery to the exact Foundry webhook is already complete. Foundry skips that bootstrap work. | For a customer-managed application: @@ -187,20 +157,7 @@ Enter the **Resource account object ID** that the Teams administrator provides. 28:orgid: ``` -### Add the number - -Select **Add number**. - -The portal: - -1. Verifies the voice agent. -1. Creates or updates the Azure Communication Services project connection. -1. Creates or updates the telephony binding. -1. Creates the `Microsoft.Communication.IncomingCall` Event Grid subscription when required by the selected delivery mode. - -The number appears in the **Phone numbers** card after provisioning succeeds. - -### Connect Twilio numbers +### Connect a Twilio number 1. In **Phone numbers**, select **Add a number** > **Twilio**. 1. Select a compatible existing Twilio connection. If none is available, select **Create a new Twilio connection**. @@ -235,6 +192,22 @@ The **Phone numbers** card shows each connected number, its optional label, and +## Understand telephony bindings + +A telephony binding connects a provider-specific destination to one voice agent in your project. + +A binding holds: + +- A service-generated binding `id`. +- The provider and its destination, such as the Teams resource account object ID. +- A `status` of `active` or `suspended`, which lets you take a number offline without deleting the mapping. +- A `connection` that names the Foundry project connection for your provider. Secrets aren't stored in the binding itself. +- An `incoming_call_url` that the service generates for incoming-call delivery. + +The agent that owns the binding is identified by the request path. Create and list bindings at `{projectEndpoint}/agents/{agentName}/telephony/bindings`. To get, update, or delete one binding, append `/{bindingId}`. + +Binding reads return an `ETag`. Send that value in `If-Match` when updating or deleting the binding to avoid overwriting a concurrent change. Transfer targets are configured separately for the agent, not on each binding. + ## Connect a number by using the API The REST examples in this section use Microsoft Teams Phone Extensibility. Use the Foundry portal for the Twilio connection and number-discovery flow. diff --git a/docs/agents/voice-agent-twilio-phone.mdx b/docs/agents/voice-agent-twilio-phone.mdx deleted file mode 100644 index fc4e26b0..00000000 --- a/docs/agents/voice-agent-twilio-phone.mdx +++ /dev/null @@ -1,290 +0,0 @@ ---- -title: "Connect a voice agent to a Twilio phone number" -description: "Connect a Microsoft Foundry voice-first agent to a Twilio phone number so callers reach the agent over the phone." ---- -import { ZoneContent, ZonePivot } from "/snippets/zone-pivot.jsx" - - -You can now directly import a phone number you purchased from Twilio and connect it to your voice agent. - - - -Items marked (preview) in this article are currently in public preview. This preview is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see [Supplemental Terms of Use for Microsoft Azure Previews](https://azure.microsoft.com/support/legal/preview-supplemental-terms/). - - - -## Prerequisites - -- Existing phone numbers purchased from [Twilio](https://www.twilio.com/phone-numbers). -- Twilio **Account SID** and **Auth Token**. -- A saved voice-first agent in a Foundry project that passes browser testing. See [Quickstart: Create a voice-first prompt agent](/get-started/prompt-voice-agent). - - - - - -## Connect a number in the Foundry portal - -The portal walks you through selecting the Azure Communication Services resource, choosing secure delivery, and entering the identifier. It then creates the project connection, the telephony binding, and the Event Grid subscription for you. - -### Open the phone-number channel - -1. In Foundry, open **Build** > **Agents**. -1. Select the voice-first agent. -1. Open **Channels**. -1. In **Phone numbers**, select **Add a number**. -1. Select **Twilio**. - -{/* Screenshot: Voice-first Channels page with Add a number and Twilio highlighted. Alt text: "Twilio Phone numbers channel menu for a voice-first agent." */} - -### Add the number - -Enter your Twilio *Account SID* and the primary *Auth Token*. - -The number appears in the **Select phone numbers** card after provisioning succeeds. - - - - -## Connect a number by using the API - -Replace `{projectEndpoint}` with your Foundry project endpoint and `{agentName}` with the voice agent's name. For each Foundry request, send a Microsoft Entra bearer token for `https://ai.azure.com/` and the `Foundry-Features: VoiceAgents=V1Preview` header. - -### Create the binding - -Create the binding on the agent. Set `connection` to the project connection name. The optional `phone_number` is a display number for the resource account. - -```http -POST {projectEndpoint}/agents/{agentName}/telephony/bindings?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -Content-Type: application/json - -{ - "provider": "twilio", - "connection": "my-acs-connection", - "resource_account_object_id": "00000000-0000-0000-0000-000000000000", - "phone_number": "+12065550123", - "label": "Support line" -} -``` - -Don't send the `28:orgid:` prefix, `identifier`, or `provider_config` in this request. - -The service returns `201 Created`, the binding's `id` and `incoming_call_url`, and an `ETag` response header. Save the binding ID for later requests. Use the returned `incoming_call_url` in the next step instead of constructing a callback path. - -### Read or update the binding - -Read the binding to get its current properties and `ETag`: - -```http -GET {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -``` - -Use `PATCH` with `application/merge-patch+json` to update the binding. For example, suspend new inbound calls without deleting the binding: - -```http -PATCH {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -Content-Type: application/merge-patch+json -If-Match: - -{ - "status": "suspended" -} -``` - -Set `status` to `active` to accept new calls again. Read the latest `ETag` before each update. You can't change the binding's provider. - - - -## Configure transfer to a person - -An agent that can't complete a request should reach a human rather than end the call. Configure named transfer targets for the agent. These targets are separate from its telephony bindings. - -First, read the current target list and its `ETag` response header: - -```http -GET {projectEndpoint}/agents/{agentName}/telephony/transfer_targets?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -``` - -Replace the target list with `PUT`, using the returned `ETag` in `If-Match`. Include every target you want to keep: this operation replaces the entire list, and an empty array clears it. - -```http -PUT {projectEndpoint}/agents/{agentName}/telephony/transfer_targets?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -Content-Type: application/json -If-Match: - -{ - "transfer_targets": [ - { - "name": "billing", - "description": "Billing and payment questions", - "destination": { "kind": "pstn", "value": "+14255550111" } - }, - { - "name": "operator", - "description": "A person at the front desk", - "destination": { "kind": "twilio", "value": "28:orgid:00000000-0000-0000-0000-000000000000" } - } - ] -} -``` - -A `twilio` destination can be a Twilio user, or the resource account of a call queue or auto attendant. That's how a voice agent hands a caller back into an existing Twilio call flow. - -Give each target a `description` that says when to use it. The agent chooses based on that text. - -Transfer requests select a target from the agent's configured list rather than supplying an arbitrary destination. - -## Manage a live call - -List the agent's calls, and use the service-generated call `id` as `{callId}` in subsequent requests: - -```http -GET {projectEndpoint}/agents/{agentName}/telephony/calls?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -``` - -To transfer an active call to the configured `operator` target: - -```http -POST {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}:transfer?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -Content-Type: application/json - -{ "target": "operator" } -``` - -To end an active call, send a separate request with no request body: - -```http -POST {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}:end?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -``` - -Both operations return the call record. To inspect the call's current status and lifecycle events, use `GET {projectEndpoint}/agents/{agentName}/telephony/calls/{callId}?api-version=v1`. - -## Configure audio for phone calls - -Phone networks carry narrowband audio, so tune the agent for the channel: - -- Set `noise_reduction` to `azure_deep_noise_suppression` for contact center traffic. -- Increase `silence_duration_ms`. Callers on a phone pause more than callers at a keyboard. -- Add `phrase_list` hints for the identifiers callers read aloud, such as order or policy numbers. -- Attach the `end_conversation` system tool so the agent can end a completed call. - -See [Configure a voice agent](/agents/configure-voice-agent). - -## Test the call - -1. From a controlled caller, call the configured number. -1. Confirm the agent answers. -1. Complete a short conversation. -1. Interrupt the agent. -1. Use one safe tool or knowledge path. -1. Test the approved human-handoff behavior. -1. End the call. -1. Confirm that monitoring and trace data appear. - -Record: - -- Test timestamp and time zone. -- Called number. -- Callee identifier. -- Azure Communication Services resource ID. -- Agent name and version. -- Event Grid delivery result. -- Azure Communication Services call correlation ID. - -{/* Screenshot: Phone numbers card showing the connected number and actions menu. Alt text: "Voice-agent phone-number channel after a Twilio number is connected." */} - -## Trace phone calls - -When a call arrives through telephony, the session's root trace span records the provider, the provider's call ID, and the dialed and calling numbers. You can correlate a Foundry session with a record in your telephony provider. - -Caller and callee phone numbers are personal data. Review who can read your project's Application Insights resource before you enable content capture. See [Voice agent tracing, monitoring, and evaluation](/agents/voice-agent-observability). - -## Troubleshoot telephony - -| Symptom | What to check | -| --- | --- | -| Busy signal and no services event | Twilio number activation. | -| Call connects but is silent | Media endpoint reachability, selected model and voice, output device path, and required PCM media format. | -| Call disconnects unexpectedly | Callback reachability, media errors, service limits, and correlation logs. | -| The wrong agent answers | Confirm the agent that owns the binding collection and inspect that agent's active version. | -| The number doesn't appear after refresh | Query active bindings and confirm provisioning completed; don't rely only on temporary browser state. | -| A binding update, deletion, or transfer-target replacement fails with a precondition error | Read the resource again, review any concurrent changes, and use the latest `ETag` in `If-Match`. | - -## Disconnect a number - - - -1. Open the agent **Channels** tab. -1. In **Phone numbers**, open the number's actions menu. -1. Select **Disconnect number**. -1. Confirm. - - - - -Read the binding to get its current `ETag`, and then delete it by using that value in `If-Match`. - -```http -GET {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -``` - -```http -DELETE {projectEndpoint}/agents/{agentName}/telephony/bindings/{bindingId}?api-version=v1 -Authorization: Bearer -Foundry-Features: VoiceAgents=V1Preview -If-Match: -``` - -A successful deletion returns `204 No Content`. - - - -Disconnecting removes the Foundry binding. It doesn't: - -- Release the Twilio number. -- Remove the Twilio resource account. -- Delete Azure Communication Services. -- Remove the bot or app registration. -- Revoke Twilio Phone Extensibility consent. - -Coordinate upstream cleanup separately. - -## Security checklist - -- Use Microsoft Entra authentication and managed identities. -- Don't share Azure Communication Services keys, connection strings, tokens, bot secrets, or portal cookies. -- Validate that the Event Grid topic is the intended Azure Communication Services resource. -- Use the exact public Foundry project webhook endpoint. -- Keep webhook audience and Event Grid delivery identity concepts separate. -- Use a dedicated single-tenant webhook application when governance requires it. -- Don't persist service-generated call callback or media tokens. -- Confirm the binding target before update or deletion. -- Apply recording, consent, disclosure, retention, and privacy requirements. -- Prevent sensitive caller data from being read aloud or unnecessarily stored. - -## Related content - -- [Configure a voice agent](/agents/configure-voice-agent) -- [Publish and share a voice-first agent](/agents/voice-agent-channels-publish) -- [Voice agent tracing, monitoring, and evaluation](/agents/voice-agent-observability). -- [Best practices for voice-first agents](/agents/voice-agent-best-practice) -- [Call automation in Azure Communication Services](https://learn.microsoft.com/azure/communication-services/concepts/call-automation/call-automation) -- [Azure Event Grid security and authentication](https://learn.microsoft.com/azure/event-grid/security-authentication) diff --git a/docs/docs.json b/docs/docs.json index f7e7e66d..4a4b0de1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -463,7 +463,6 @@ "agents/voice-first-with-hosted-agent", "agents/use-subagent-voice-first-agent", "agents/voice-agent-telephony-channels", - "agents/voice-agent-twilio-phone", "agents/voice-agent-best-practice", "agents/optimize-voice-agent-instructions", "agents/voice-agent-observability", diff --git a/docs/get-started/get-started-code.mdx b/docs/get-started/get-started-code.mdx index 61a294f7..dd1107cc 100644 --- a/docs/get-started/get-started-code.mdx +++ b/docs/get-started/get-started-code.mdx @@ -272,21 +272,23 @@ Interacting with a model is the basic building block of AI applications. Send a ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; + import com.azure.ai.agents.AgentsClientBuilder; + import com.azure.ai.agents.ResponsesClient; 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) { - // Format: "https://resource_name.ai.azure.com/api/projects/project_name" - String ProjectEndpoint = "your_project_endpoint"; + // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name" + String foundryProjectEndpoint = "your_project_endpoint"; // Create responses client to call Foundry API ResponsesClient responsesClient = new AgentsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) - .endpoint(ProjectEndpoint) + .endpoint(foundryProjectEndpoint) .buildResponsesClient(); // Run a responses API call @@ -433,25 +435,30 @@ An agent defines core behavior. Once created, it ensures consistent responses in ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; + import com.azure.ai.agents.AgentsClient; + import com.azure.ai.agents.AgentsClientBuilder; 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 + // 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(endpoint) + .endpoint(foundryProjectEndpoint) .buildAgentsClient(); - PromptAgentDefinition request = new PromptAgentDefinition(model); - AgentVersionDetails agent = agentsClient.createAgentVersion("MyAgent", request); + // 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()); @@ -639,68 +646,60 @@ Use the previously created agent named "MyAgent" to interact by asking a questio ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; - import com.azure.ai.agents.models.AgentReference; - import com.azure.ai.agents.models.AgentVersionDetails; + import com.azure.ai.agents.AgentsClient; + import com.azure.ai.agents.AgentsClientBuilder; 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"; + // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name" + String foundryProjectEndpoint = "your_project_endpoint"; + String foundryAgentName = "your-agent-name"; - AgentsClient agentsClient = new AgentsClientBuilder() + AgentsClientBuilder builder = new AgentsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) - .endpoint(endpoint) - .buildAgentsClient(); + .endpoint(foundryProjectEndpoint); - 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(); + // Create the agent (or a new version, if it already exists) + AgentsClient agentsClient = builder.buildAgentsClient(); + PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models + .setInstructions("You are a helpful assistant that answers general questions"); + agentsClient.createAgentVersion(foundryAgentName, agentDefinition); - ResponseCreateParams responseRequest = new ResponseCreateParams.Builder() - .input("Hello, how can you help me?") - .model(model) - .build(); + // 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); + } - Response result = client.responses().create(responseRequest); + 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()))))); } } ``` diff --git a/docs/get-started/prompt-agent.mdx b/docs/get-started/prompt-agent.mdx index 5405a7e5..c85b678b 100644 --- a/docs/get-started/prompt-agent.mdx +++ b/docs/get-started/prompt-agent.mdx @@ -210,25 +210,30 @@ Create a prompt agent using your deployed model. The agent uses a `PromptAgentDe ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; + import com.azure.ai.agents.AgentsClient; + import com.azure.ai.agents.AgentsClientBuilder; 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 + // 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(endpoint) + .endpoint(foundryProjectEndpoint) .buildAgentsClient(); - PromptAgentDefinition request = new PromptAgentDefinition(model); - AgentVersionDetails agent = agentsClient.createAgentVersion("MyAgent", request); + // 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()); @@ -403,68 +408,60 @@ Use the agent you created to interact by asking a question and a related follow- ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; - import com.azure.ai.agents.models.AgentReference; - import com.azure.ai.agents.models.AgentVersionDetails; + import com.azure.ai.agents.AgentsClient; + import com.azure.ai.agents.AgentsClientBuilder; 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"; + // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name" + String foundryProjectEndpoint = "your_project_endpoint"; + String foundryAgentName = "your-agent-name"; - AgentsClient agentsClient = new AgentsClientBuilder() + AgentsClientBuilder builder = new AgentsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) - .endpoint(endpoint) - .buildAgentsClient(); + .endpoint(foundryProjectEndpoint); + + // Create the agent (or a new version, if it already exists) + AgentsClient agentsClient = builder.buildAgentsClient(); + PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models + .setInstructions("You are a helpful assistant that answers general questions"); + agentsClient.createAgentVersion(foundryAgentName, agentDefinition); + + // 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); + } - 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); + 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()))))); } } ``` diff --git a/docs/models/instant-models.mdx b/docs/models/instant-models.mdx index 0adacbfc..188cdc72 100644 --- a/docs/models/instant-models.mdx +++ b/docs/models/instant-models.mdx @@ -113,21 +113,23 @@ Support for instant access continues to expand over time. The exact set changes For the `model` parameter, use the instant access model name, such as `"gpt-5-mini"`, instead of a deployed model name. ```java - package com.azure.ai.agents; + package com.azure.ai.foundry.samples; + import com.azure.ai.agents.AgentsClientBuilder; + import com.azure.ai.agents.ResponsesClient; 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) { - // Format: "https://resource_name.ai.azure.com/api/projects/project_name" - String ProjectEndpoint = "your_project_endpoint"; + // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name" + String foundryProjectEndpoint = "your_project_endpoint"; // Create responses client to call Foundry API ResponsesClient responsesClient = new AgentsClientBuilder() .credential(new DefaultAzureCredentialBuilder().build()) - .endpoint(ProjectEndpoint) + .endpoint(foundryProjectEndpoint) .buildResponsesClient(); // Run a responses API call diff --git a/manifest.json b/manifest.json index 2632f58e..97d6e637 100644 --- a/manifest.json +++ b/manifest.json @@ -2,8 +2,8 @@ "repo": "MicrosoftDocs/azure-ai-docs-pr", "root_toc": "articles/foundry/toc.yml", "stats": { - "total_docs": 391, - "in_repo_md": 385, + "total_docs": 389, + "in_repo_md": 383, "in_repo_yml": 3, "cross_repo": 2, "external": 1, @@ -3702,37 +3702,6 @@ "articles/foundry/includes/role-rename-note.md" ] }, - { - "name": "Connect to a Teams phone number", - "source_path": "articles/foundry/agents/how-to/voice-agent-teams-phone.md", - "category": "in-repo-md", - "section": "Agents", - "hierarchy": [ - "Agents", - "Prompt agents", - "Voice-first agents", - "Build", - "Connect to a Teams phone number" - ], - "output_path": "agents/voice-agent-teams-phone" - }, - { - "name": "Connect to a Twilio phone number", - "source_path": "articles/foundry/agents/how-to/voice-agent-twilio-phone.md", - "category": "in-repo-md", - "section": "Agents", - "hierarchy": [ - "Agents", - "Prompt agents", - "Voice-first agents", - "Build", - "Connect to a Twilio phone number" - ], - "output_path": "agents/voice-agent-twilio-phone", - "includes": [ - "articles/foundry/includes/feature-preview.md" - ] - }, { "name": "Best practices", "source_path": "articles/foundry/agents/concepts/voice-agent-best-practice.md", @@ -10610,37 +10579,6 @@ "articles/foundry/includes/role-rename-note.md" ] }, - { - "name": "Connect to a Teams phone number", - "source_path": "articles/foundry/agents/how-to/voice-agent-teams-phone.md", - "category": "in-repo-md", - "section": "Agents", - "hierarchy": [ - "Agents", - "Prompt agents", - "Voice-first agents", - "Build", - "Connect to a Teams phone number" - ], - "output_path": "agents/voice-agent-teams-phone" - }, - { - "name": "Connect to a Twilio phone number", - "source_path": "articles/foundry/agents/how-to/voice-agent-twilio-phone.md", - "category": "in-repo-md", - "section": "Agents", - "hierarchy": [ - "Agents", - "Prompt agents", - "Voice-first agents", - "Build", - "Connect to a Twilio phone number" - ], - "output_path": "agents/voice-agent-twilio-phone", - "includes": [ - "articles/foundry/includes/feature-preview.md" - ] - }, { "name": "Best practices", "source_path": "articles/foundry/agents/concepts/voice-agent-best-practice.md", diff --git a/path_map.json b/path_map.json index d53e905a..5f22d8b2 100644 --- a/path_map.json +++ b/path_map.json @@ -205,8 +205,6 @@ "articles/foundry/how-to/voice-first-with-hosted-agent.md": "agents/voice-first-with-hosted-agent", "articles/foundry/agents/how-to/use-subagent-voice-first-agent.md": "agents/use-subagent-voice-first-agent", "articles/foundry/agents/how-to/voice-agent-telephony-channels.md": "agents/voice-agent-telephony-channels", - "articles/foundry/agents/how-to/voice-agent-teams-phone.md": "agents/voice-agent-teams-phone", - "articles/foundry/agents/how-to/voice-agent-twilio-phone.md": "agents/voice-agent-twilio-phone", "articles/foundry/agents/concepts/voice-agent-best-practice.md": "agents/voice-agent-best-practice", "articles/foundry/agents/how-to/optimize-voice-agent-instructions.md": "agents/optimize-voice-agent-instructions", "articles/foundry/agents/concepts/voice-agent-observability.md": "agents/voice-agent-observability", diff --git a/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/chat-with-agent/src/main/java/com/azure/ai/foundry/samples/ChatWithAgent.java b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/chat-with-agent/src/main/java/com/azure/ai/foundry/samples/ChatWithAgent.java new file mode 100644 index 00000000..d04e57c0 --- /dev/null +++ b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/chat-with-agent/src/main/java/com/azure/ai/foundry/samples/ChatWithAgent.java @@ -0,0 +1,56 @@ +package com.azure.ai.foundry.samples; + +import com.azure.ai.agents.AgentsClient; +import com.azure.ai.agents.AgentsClientBuilder; +import com.azure.ai.agents.models.PromptAgentDefinition; +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 the agent (or a new version, if it already exists) + AgentsClient agentsClient = builder.buildAgentsClient(); + PromptAgentDefinition agentDefinition = new PromptAgentDefinition("gpt-5-mini") // supports all Foundry direct models + .setInstructions("You are a helpful assistant that answers general questions"); + agentsClient.createAgentVersion(foundryAgentName, agentDefinition); + + // 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()))))); + } +} \ No newline at end of file diff --git a/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/create-agent/src/main/java/com/azure/ai/foundry/samples/CreateAgent.java b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/create-agent/src/main/java/com/azure/ai/foundry/samples/CreateAgent.java new file mode 100644 index 00000000..ea9f641f --- /dev/null +++ b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/create-agent/src/main/java/com/azure/ai/foundry/samples/CreateAgent.java @@ -0,0 +1,30 @@ +package com.azure.ai.foundry.samples; + +import com.azure.ai.agents.AgentsClient; +import com.azure.ai.agents.AgentsClientBuilder; +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()); + } +} \ No newline at end of file diff --git a/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/responses/src/main/java/com/azure/ai/foundry/samples/CreateResponse.java b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/responses/src/main/java/com/azure/ai/foundry/samples/CreateResponse.java new file mode 100644 index 00000000..c8dd7151 --- /dev/null +++ b/raw_docs/code_samples/foundry-samples-main/samples/java/quickstart/responses/src/main/java/com/azure/ai/foundry/samples/CreateResponse.java @@ -0,0 +1,28 @@ +package com.azure.ai.foundry.samples; + +import com.azure.ai.agents.AgentsClientBuilder; +import com.azure.ai.agents.ResponsesClient; +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) { + // Format: "https://resource_name.services.ai.azure.com/api/projects/project_name" + String foundryProjectEndpoint = "your_project_endpoint"; + + // Create responses client to call Foundry API + ResponsesClient responsesClient = new AgentsClientBuilder() + .credential(new DefaultAzureCredentialBuilder().build()) + .endpoint(foundryProjectEndpoint) + .buildResponsesClient(); + + // Run a responses API call + ResponseCreateParams responseRequest = new ResponseCreateParams.Builder() + .input("What is the size of France in square miles?") + .model("gpt-5-mini") + .build(); + Response response = responsesClient.getResponseService().create(responseRequest); + System.out.println(response.output()); + } +} \ No newline at end of file