@azure/ai-projects
v2.11.0
Published
Azure AI Projects client library.
Readme
Azure AI Projects client library for JavaScript
The AI Projects client library is part of the Microsoft Foundry SDK, and provides easy access to resources in your Microsoft Foundry Project. Use it to:
- Create and run Agents using the
.agentsproperty on the client.
- Enhance Agents with specialized tools:
- Agent Memory Search (Preview)
- Agent-to-Agent (A2A) (Preview)
- Azure AI Search
- Bing Custom Search (Preview)
- Bing Grounding
- Browser Automation
- Code Interpreter
- Computer Use
- File Search
- Function Tool
- Image Generation
- Microsoft Fabric (Preview)
- Model Context Protocol (MCP)
- OpenAPI
- Microsoft SharePoint (Preview)
- Web Search (Preview)
- Tool Search
- Get an OpenAI client using the
.getOpenAIClient.method to run Responses, Conversations, Evals and FineTuning operations with your Agent.
- Manage hosted agent sessions and files using the
.agentsoperations on a deployment that supports sessions. - Manage skills (preview) for reusable agent capabilities, using the
.beta.skillsoperations. - Manage toolboxes for grouping tools into reusable collections, using the
.toolboxesoperations. - Manage memory stores (preview) for Agent conversations, using the
.beta.memoryStoresoperations. - Manage routines (preview) for scheduling and dispatching automated workflows, using the
.beta.routinesoperations. - Manage model versions (preview) for creating, updating, and managing custom model versions, using the
.beta.modelsoperations. - Explore additional evaluation tools (some in preview) to assess the performance of your generative AI application, using the
.evaluationRules,.beta.evaluationTaxonomies,.beta.evaluators,.beta.insights, and.beta.schedulesoperations. - Run Red Team scans (preview) to identify risks associated with your generative AI application, using the
.beta.redTeamsoperations. - Fine tune AI Models on your data.
- Enumerate AI Models deployed to your Foundry Project using the
.deploymentsoperations. - Enumerate connected Azure resources in your Foundry project using the
.connectionsoperations. - Upload documents and create Datasets to reference them using the
.datasetsoperations. - Create and enumerate Search Indexes using the
.indexesoperations.
The client library uses version v1 of the Microsoft Foundry data plane REST APIs.
Product documentation | Samples | Package (npm) | API reference documentation | SDK source code
Table of contents
- Getting started
- Key concepts
- Examples
- Performing Responses operations using OpenAI client
- Performing Agent operations
- Voice Agent operations
- GPT Live voice agents
- Using Agent tools
- Evaluation operations
- Deployments operations
- Connections operations
- Dataset operations
- Files operations
- Indexes operations
- fine-tuning operations
- Agent session operations
- Skills operations (preview)
- Toolboxes operations (preview)
- Tracing
- Troubleshooting
- Next steps
- Contributing
Getting started
Prerequisite
- LTS versions of Node.js
- An [Azure subscription][azure_sub].
- A project in Microsoft Foundry.
- An Application Insights resource connected to your Foundry project for agent tracing.
- The project endpoint URL of the form
https://your-ai-services-account-name.services.ai.azure.com/api/projects/your-project-name. It can be found in your Microsoft Foundry Project overview page. Below we will assume the environment variableFOUNDRY_PROJECT_ENDPOINTwas defined to hold this value.
Authorization
- An Entra ID is needed to authenticate the client. Your application needs an object that implements the TokenCredential interface. Code samples here use [DefaultAzureCredential][default_azure_credential]. To get that working, you will need:
- An appropriate role assignment. see Role-based access control in Microsoft Foundry portal. Role assigned can be done via the "Access Control (IAM)" tab of your Azure AI Project resource in the Azure portal.
- Azure CLI installed.
- You are logged into your Azure account by running
az login. - Note that if you have multiple Azure subscriptions, the subscription that contains your Azure AI Project resource must be your default subscription. Run
az account list --output tableto list all your subscription and see which one is the default. Runaz account set --subscription "Your Subscription ID or Name"to change your default subscription.
Install the package
npm install @azure/ai-projects dotenvKey concepts
Create and authenticate the client with Entra ID
Entra ID is the only authentication method supported at the moment by the client.
To construct an AIProjectsClient, the projectEndpoint can be fetched from [projectEndpoint][ai_project_client_endpoint]. Below we will assume the environment variable FOUNDRY_PROJECT_ENDPOINT was defined to hold this value:
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"] || "<project endpoint string>";
project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());Preview operation groups and opt-in feature flags
Some preview operations require an explicit foundryFeatures opt-in flag. For example:
await project.agents.createVersion(
"preview-agent",
{
kind: "workflow",
},
{ foundryFeatures: "WorkflowAgents=V1Preview" },
);
for await (const rule of project.evaluationRules.list()) {
console.log(rule.id);
}Preview operation groups include .beta.voiceAgents, .beta.skills, .beta.memoryStores, .beta.routines, .beta.models, .beta.evaluationTaxonomies, .beta.evaluators, .beta.insights, .beta.schedules, and .beta.redTeams. Voice Agents have both GA and preview features; see Voice Agent operations for their opt-in requirements.
Use .agentInsightMonitors to list the monitors that analyze your agents:
for await (const monitor of project.agentInsightMonitors.list()) {
console.log(`${monitor.id}: ${monitor.agent_name}`);
}Examples
Performing Responses operations using OpenAI client
Your Microsoft Foundry project may have one or more AI models deployed. These could be OpenAI models, Microsoft models, or models from other providers. Use the code below to get an authenticated OpenAI from the openai package, and execute a chat completions call.
Run the code below. Here we assume deploymentName (str) is defined. It's the deployment name of an AI model in your Foundry Project. As shown in the "Models + endpoints" tab, under the "Name" column.
See the "responses" folder in the [package samples][samples] for additional samples, including streaming responses.
const openAIClient = project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "What is the size of France in square miles?",
});
console.log("response = ", JSON.stringify(response, null, 2));
const detailResponse = await openAIClient.responses.create({
model: deploymentName,
input: "And what is the capital city?",
previous_response_id: response.id,
});
console.log("detailed response = ", JSON.stringify(detailResponse, null, 2));Performing Agent operations
The .agents property on the AIProjectsClient gives you access to all Agent operations. Agents use an extension of the
OpenAI Responses protocol, so you will likely need to get an OpenAI client to do Agent operations, as shown in the example below.
For setup, see Quickstart: Set up Microsoft Foundry resources.
const openAIClient = project.getOpenAIClient();
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})`);
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}`);
// Add a second user message to the conversation
console.log("\nAdding a second user message to the conversation...");
await openAIClient.conversations.items.create(conversation.id, {
items: [{ type: "message", role: "user", content: "And what is the capital city?" }],
});
console.log("Added a second user message to the conversation");
// Generate second response
console.log("\nGenerating second response...");
const response2 = await openAIClient.responses.create(
{
conversation: conversation.id,
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
console.log(`Response output: ${response2.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");Voice Agent operations
Use project.agents to create and manage voice agents. Choose the connection client
that matches your agent:
project.voiceAgents.realtimefor Realtime and cascaded voice agents.project.beta.voiceAgents.livefor GPT Live (preview).
The old project.beta.voiceAgents.realtime path is a deprecated compatibility alias
for the same client. Use the root path in new code. Ordinary Realtime connections are
GA and do not send a VoiceAgents preview opt-in by default.
| Scope | API or feature | VoiceAgents=V1Preview |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| GA | Realtime/cascaded definitions, delegate subagents, and phone system tools through project.agents | Not required |
| GA | project.agents.createFromPrompt (agents:generate) | Do not send |
| GA | All 14 stored Realtime conversation operations on project.voiceAgents.conversations; Realtime protocol and OpenAI Realtime models | Not required |
| GA | TPE/Twilio telephony and call-job list/get operations on project.voiceAgents.telephony | Not required |
| Conditional | Realtime connections to an agent using inline handoff, SIP transfer destinations, or post_call | Pass foundryFeatures to connect() |
| Conditional | Telephony binding/transfer/call writes and call-job create/cancel/delete on project.voiceAgents.telephony | Pass foundryFeatures only when using SIP |
| Preview | GPT Live definitions, delegation, sessions, stored conversations, and models | Required; native Live and project.beta.voiceAgents.liveConversations supply it internally |
| Preview | Inline handoff configuration/state/events, SIP models, and post_call configuration/types | Required for these preview members; use the relevant operation's opt-in |
| Preview | All seven campaign operations on project.beta.voiceAgents.telephony | Required; supplied internally |
A GA operation can accept a union with preview-only members. Opt in when selecting
Live, inline-handoff, or SIP members, or when configuring post_call; the presence
of those members does not make the entire union or operation preview.
For telephony writes, use the connection, binding, call, or call-job provider to
determine SIP usage, not just the address type: a SIP connection can use
phone_number source and destination addresses. The REST tracing sample accepts
only an existing TPE/Twilio connection for its optional outbound call; it does not
demonstrate SIP calls. Separately, transfer.require_handoff is a GA transfer-summary
setting; it does not by itself enable preview inline handoff.
When migrating older samples, replace project.beta.agents.createFromPrompt with
project.agents.createFromPrompt, project.beta.voiceAgents.conversations with
project.voiceAgents.conversations, and non-campaign uses of
project.beta.voiceAgents.telephony with project.voiceAgents.telephony. Replace
their retired Beta*OptionalParams and conversation-download response types with
the corresponding non-beta types. Keep campaign and GPT Live operations under
project.beta.voiceAgents; use the root Realtime client listed above.
This Node.js example sends text to an existing Realtime agent and prints the reply. Use an agent without an automatic greeting so the first response is the answer to your message.
// Ordinary Realtime sessions are GA and do not require a preview opt-in.
const connection = await project.voiceAgents.realtime.connect("<voice agent name>");
try {
await connection.sendText("Hello. Please introduce yourself briefly.");
for await (const event of connection) {
if (
event.type === "response.output_text.delta" ||
event.type === "response.output_audio_transcript.delta"
) {
process.stdout.write(event.delta);
} else if (event.type === "error") {
throw new Error(event.error.message);
} else if (event.type === "response.done") {
if (event.response.status !== "completed") {
throw new Error(`Voice response ${event.response.status}.`);
}
break;
}
}
} finally {
await connection.close();
}Read events with one for await loop. Leaving the loop closes the connection.
Unknown event types arrive as type: "unknown" without disconnecting the session;
their original type is in eventType. Validate rawEvent before using its fields.
Malformed events throw VoiceAgentProtocolError. Handle service error events as shown above.
To keep conversations, set store: true on the agent or on connect(), then use
project.voiceAgents.conversations to read Realtime conversations. Connecting to a disabled agent
fails with 409 Conflict and error code agent_disabled.
The inline-handoff sample shows the explicit opt-in for a Realtime agent that uses preview configuration:
const connection = await project.voiceAgents.realtime.connect("<inline-handoff agent name>", {
foundryFeatures: "VoiceAgents=V1Preview",
});
await connection.close();In Node.js, this option sends the foundry-features header. Browsers and React Native
send the equivalent foundry_features WebSocket query parameter. Use the typed option,
not the reserved generic query parameter. Default Realtime samples use GA agent
configurations; for an existing agent with inline handoff, SIP transfer destinations,
or post_call, opt in as above.
Choose a complete sample for the task you want:
| Task | Node.js sample | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | Create and read an agent definition | Configure a voice agent | | Generate an agent from a goal | Generate a voice agent | | Send speech and save the audio reply | Realtime audio | | Send text and handle a function call | Realtime text and tools | | Inspect bindings and call history without placing calls | Telephony | | Route a turn to an inline specialist (preview) | Inline handoff | | Inspect Realtime (GA) or Live (preview) recordings | Conversation recordings | | Inspect preview campaigns and GA outbound call jobs | Read-only campaigns |
The preview handoff sample opts in when creating the definition and connecting. It creates two inline Realtime specialists, observes the correlated handoff events and the target's completed response, then deletes its sample agent. If creation is interrupted, an aborted HTTP request does not cancel server-side creation: use the logged unique agent name to check for a resource that finishes later. The tracing samples are separate instrumentation walkthroughs; the basic generation, Realtime, and GPT Live examples do not require tracing setup. The configuration sample is GA by default; setting either optional post-call destination enables preview transcript delivery and adds the definition opt-in. Post-call delivery also supports optional merged-recording URLs; the sample does not request caller audio.
Stored conversations and recordings
The conversation-recordings sample is read-only and supports both persisted API
families. Set FOUNDRY_AGENT_NAME and choose FOUNDRY_VOICE_CONVERSATION_PROTOCOL=realtime
or live. Realtime uses the GA project.voiceAgents.conversations client without a
preview header; Live uses project.beta.voiceAgents.liveConversations with the required
preview header. It reads one page and can select an exact conversation or item using the
variables documented in sample.env. Use IDs returned by the REST
collections, not the native Realtime WebSocket item or response IDs. Create the
recording first by connecting with
store: true and finalize the session before downloading audio. The sample never
deletes a stored conversation or prints its caller transcripts.
Set FOUNDRY_VOICE_RECORDING_OUTPUT_FILE to opt into downloading a WAV file. With
FOUNDRY_VOICE_AUDIO_ITEM_ID, this downloads that item's heard audio; otherwise it
downloads the merged stereo recording. These WAV files are different from the raw
PCM files written by the streaming samples. Keep downloaded caller media private.
Bring-your-own-storage recordings must be read from blob_uri with your own storage
credentials; this sample does not fetch arbitrary storage URLs.
Realtime additionally exposes response inspection and generated-but-unheard item
audio. The generated-audio variables require an interrupted or truncated item where
the service produced audio beyond the heard segment; cancellation alone does not
guarantee that artifact exists. Missing audio returns 404. An unfinished merged
recording can return 409 recording_not_ready; follow its Retry-After guidance
instead of treating that response as an empty recording.
For stored GPT Live sessions, use project.beta.voiceAgents.liveConversations.
Connect with project.beta.voiceAgents.live.connect() and store: true to persist
a Live session; project.voiceAgents.realtime.connect() uses the Realtime
protocol and is not a Live connection. The following Node.js example reads a
completed Live conversation, lists its stored items without printing transcripts,
and saves its Foundry-managed merged WAV recording:
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
import { pipeline } from "node:stream/promises";
import { createWriteStream } from "node:fs";
const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const agentName = "<GPT Live agent name>";
const conversationId = "<stored Live conversation ID>";
const conversations = project.beta.voiceAgents.liveConversations;
const conversation = await conversations.get(agentName, conversationId);
console.log("Conversation:", conversation.id, conversation.status);
for await (const item of conversations.listItems(agentName, conversationId)) {
console.log("Stored item:", item.id, item.type);
}
const recording = await conversations.getAudio(agentName, conversationId);
if (recording.blob_uri) {
throw new Error("Retrieve BYOS audio from blob_uri using your own storage credentials.");
}
const audio = await conversations.downloadAudio(agentName, conversationId);
if (!audio.readableStreamBody) {
throw new Error("Expected a Node.js audio stream.");
}
await pipeline(audio.readableStreamBody, createWriteStream("live-conversation.wav"));Campaign operations use the preview project.beta.voiceAgents.telephony client.
Use deleteCampaign() to delete a campaign; deleteTelephony() is a deprecated
compatibility alias for that operation.
Call-job list/get operations use the GA project.voiceAgents.telephony client,
including jobs created by a preview campaign. The campaign sample only reads campaign
preparation, validation errors, operation monitors, and call jobs. The campaign reads
require a deployment with those preview routes enabled.
It never creates or cancels a call: campaign creation can authorize dialing before
its preparation poller returns. An empty validation-error page during preparation
does not establish that the campaign is valid or ready.
Custom query parameters
Pass query to add URL parameters for one connection. Use names supported by your
service or gateway; the names below are examples:
const connection = await project.voiceAgents.realtime.connect("my-voice-agent", {
query: {
custom_key: "custom value",
custom_flag: true,
// Explicit URL transport: only use non-sensitive prompt variables.
structured_inputs: JSON.stringify({ persona: "guide" }),
},
});
await connection.close();Values can be strings, finite numbers, or booleans. The SDK URL-encodes them and captures
them when connect() is called. A value replaces a matching endpoint parameter;
undefined removes it. These values are not reused for later connections.
Use typed options such as store, agentVersionOverride, and Realtime's
foundryFeatures instead of putting SDK settings in query. SDK/authentication
names, noncanonical structured-input names, and names starting with h- remain
reserved. Realtime explicitly permits the exact structured_inputs key with a
JSON-object string, as shown above; do not combine it with structuredInputs.
Other custom query values do not become prompt variables.
Realtime structuredInputs preserves header-based transport in Node.js. Browsers
use a URL query because they cannot send arbitrary WebSocket upgrade headers.
If your service requires the query form, opt in explicitly through
query.structured_inputs instead of structuredInputs.
Never put secrets or sensitive prompt variables in query parameters: server
and proxy access logs can retain URLs.
GPT Live voice agents
Use project.beta.voiceAgents.live for GPT Live agents. When creating the agent, set
sub_protocol: "live", model_type: "self_deployed", and model to your GPT Live
deployment name. Creation requires VoiceAgents=V1Preview.
Pass { foundryFeatures: "VoiceAgents=V1Preview" } to project.agents.create() or
createVersion(). Native Live connections always send the required preview flag
internally; callers do not need a flag on live.connect().
This short example requires an existing agent configured for mono PCM16LE audio at 24 kHz. Live advances on an audio clock even when adding text instructions, so the example sends silence until the correlated acknowledgement arrives, then closes the session. Use the complete samples below to send text or speech and read the reply.
import {
AIProjectClient,
LiveServerEventLiveInstructionsAppended,
LiveServerEventLiveErrorEvent,
} from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const connection = await project.beta.voiceAgents.live.connect("<GPT Live agent name>", {
store: false,
});
const eventId = "brief-instructions";
// Requires an agent configured for mono PCM16LE at 24 kHz.
const silence = new Uint8Array(4800); // 100 ms of audio.
let correlatedAck = false;
let serviceError: Error | undefined;
const onAppended = (event: LiveServerEventLiveInstructionsAppended): void => {
if (event.client_event_id === eventId) correlatedAck = true;
};
const onError = (event: LiveServerEventLiveErrorEvent): void => {
serviceError = new Error(event.error.message);
};
connection.on("session.instructions.appended", onAppended);
connection.on("error", onError);
try {
await connection.appendInstructions("Keep your answers brief.", { eventId });
const deadline = Date.now() + 10000;
while (!correlatedAck) {
if (serviceError) throw serviceError;
if (connection.state !== "connected") {
throw new Error(`Live connection became ${connection.state} before the instructions ACK.`);
}
if (Date.now() >= deadline) {
throw new Error("Timed out waiting for the correlated instructions ACK.");
}
await connection.sendAudio(silence);
await new Promise((resolve) => setTimeout(resolve, 100));
}
if (serviceError) throw serviceError;
} finally {
connection.off("session.instructions.appended", onAppended);
connection.off("error", onError);
await connection.close();
}Run a GPT Live sample
Set FOUNDRY_PROJECT_ENDPOINT and FOUNDRY_LIVE_MODEL in .env.
Use a deployment name, not a model catalog ID. The function sample also needs
FOUNDRY_LIVE_BACKEND_MODEL. See sample.env
for these settings and optional audio file paths.
| Task | Node.js sample | | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Send a greeting and print the spoken reply as text | GPT Live text | | Send a speech file and save the audio reply | GPT Live audio | | Run a local function and let the agent speak the result | GPT Live function calling |
From a built SDK checkout, run a sample with Node.js 22.18 or later:
node samples-dev/agents/agentVoiceLiveText.tsEach sample creates and deletes its own agent. It prints captions but does not play sound through your speakers. The audio sample uses a recorded file, not a microphone, and reads and saves raw mono PCM16LE at 24 kHz, without a WAV or other file header.
Press Enter after the reply, or Ctrl+C, to stop. Usage is billable until the session closes. Live needs continuous audio input, even for text and tools, so the samples send silence while idle. Live has no speech-finished event; a completed backend response does not mean the agent has finished speaking.
The text sample appends session instructions and waits for their correlated acknowledgement before adding commentary. That acknowledgement confirms acceptance, not completed speech; keep the session open until the expected reply arrives.
Session controls and events
connect() waits for session.started. Read the current settings from connection.session,
including the selected managed agent and version when applicable. Read events with one
for await loop or use on, off, and once listeners for subsequent events.
For listener-only consumption, supply onEvent when connecting to receive startup
events and initial audio without waiting for connect() to return. The original
startup event, including the persisted conversation ID when provided by the service,
remains available through connection.sessionStarted. An iterator started after
an onEvent callback was configured receives subsequent events, not past events.
import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";
const project = new AIProjectClient("<project endpoint>", new DefaultAzureCredential());
const connection = await project.beta.voiceAgents.live.connect("<GPT Live agent name>", {
store: true,
onEvent: (event) => {
if (event.type === "session.started") {
console.log("Conversation:", event.conversation_id);
} else if (event.type === "session.output_audio.delta") {
console.log("Received an audio chunk.");
}
},
});
try {
console.log("Session:", connection.sessionStarted.session.id);
} finally {
await connection.close();
}| Task | API or event |
| ----------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Send raw audio | sendAudio(); Live detects speech boundaries, so no audio-buffer commit is needed |
| Read transcripts | session.input_transcript.delta, session.output_transcript.delta |
| Receive audio | session.output_audio.delta; decode the base64 data before saving or playing it |
| Add text context, rather than a user message | appendInstructions(), appendThinking(), appendCommentary() |
| Pause or resume audio processing | muteInputAudio(), unmuteInputAudio() |
| Update backend settings and transcript triggers | configureSession(); the initial model, audio format, and delegation owner cannot change |
| Close the session | close(); waits for session.closed and rejects if finalization is not confirmed |
close() and dispose() also reject an unconfirmed shutdown when the socket has
already disconnected. Inspect connection.closed for the service's finalization
event and any connection error.
With Responses delegation, backend events arrive inside response.event. Use
sendResponseItem() to add a user message and requestResponse() to ask for a reply.
For a function call, wait for the calling backend response to finish, then use
sendToolOutput() to return the result and request continuation. These methods require
Responses delegation. For client-handled delegation, use appendThinking() or
appendCommentary() and pass the delegation ID as delegationId.
Decision context items support user messages, function calls and results, and
custom tool calls and results. Send them with decision.item.create; received
decision.item.created events retain the corresponding item fields and stored ID.
Decision commands require support from the service deployment.
Live does not support Realtime's response.cancel. An abort signal cancels an SDK
connection or send operation, not speech already being generated. To store Live
conversations, enable store and use project.beta.voiceAgents.liveConversations;
the service deployment must support persistence. Set liveOptions on AIProjectClient
to change connection, session-start, and close timeouts.
Use the stored-conversation sample
with FOUNDRY_VOICE_CONVERSATION_PROTOCOL=live to inspect persisted items or download their WAV audio.
Browser authentication
Use a browser credential such as InteractiveBrowserCredential. The SDK uses native
WebSocket with live and short-lived bearer-token subprotocols, including in Web Workers.
Node.js uses a bearer header instead. Do not supply realtime as a Live subprotocol,
put tokens in URLs, or embed API keys, client secrets, or long-lived tokens in browser code.
If direct browser authentication is unavailable, supply an authenticated backend relay
through webSocketFactory.
Realtime connections keep structuredInputs in the
x-ms-voice-structured-inputs header in Node.js and use the structured_inputs
URL query in browsers and Workers. Explicit Realtime query.structured_inputs
opts into URL transport on any host. GPT Live continues to use the URL query on
all hosts and has no header-based alternative.
Proxy and server access logs can retain URLs: do not put credentials, personal
data, or other sensitive information in URL-carried inputs.
Using Agent tools
Agents can be enhanced with specialized tools for various capabilities. Tools are organized by their connection requirements:
Built-in Tools
These tools work immediately without requiring external connections.
Code Interpreter
Write and run Javascript code in a sandboxed environment, process files and work with diverse data formats. OpenAI Documentation
const openAIClient = project.getOpenAIClient();
const response = await openAIClient.responses.create({
model: deploymentName,
input: "I need to solve the equation 3x + 11 = 14. Can you help me?",
tools: [{ type: "code_interpreter", container: { type: "auto" } }],
});
console.log(`Response output: ${response.output_text}`);See the full sample code in agentCodeInterpreter.ts.
File Search
Built-in RAG (Retrieval-Augmented Generation) tool to process and search through documents using vector stores for knowledge retrieval. OpenAI Documentation
const openAIClient = project.getOpenAIClient();
const assetFilePath = path.join(
__dirname,
"..",
"samples-dev",
"agents",
"assets",
"product_info.txt",
);
const vectorStore = await openAIClient.vectorStores.create({
name: "ProductInfoStreamStore",
});
console.log(`Vector store created (id: ${vectorStore.id})`);
// Upload file to vector store
const fileStream = fs.createReadStream(assetFilePath);
const uploadedFile = await openAIClient.vectorStores.files.uploadAndPoll(
vectorStore.id,
fileStream,
);
console.log(`File uploaded to vector store (id: ${uploadedFile.id})`);
// Create agent with file search tool
const agent = await project.agents.createVersion("StreamingFileSearchAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful assistant that can search through product information and provide detailed responses. Use the file search tool to find relevant information before answering.",
tools: [
{
type: "file_search",
vector_store_ids: [vectorStore.id],
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentFileSearchStream.ts.
Image Generation
Generate images based on text prompts with customizable resolution, quality, and style settings:
const agent = await project.agents.createVersion("agent-image-generation", {
kind: "prompt",
model: deploymentName,
instructions: "Generate images based on user prompts",
tools: [
{
type: "image_generation",
quality: "low",
size: "1024x1024",
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);After calling responses.create(), you can download file using the returned response:
import { fileURLToPath } from "url";
const openAIClient = project.getOpenAIClient();
const agent = await project.agents.createVersion("agent-image-generation", {
kind: "prompt",
model: deploymentName,
instructions: "Generate images based on user prompts",
tools: [
{
type: "image_generation",
quality: "low",
size: "1024x1024",
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
const response = await openAIClient.responses.create(
{
input: "Generate an image of Microsoft logo.",
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
console.log(`Response created: ${response.id}`);
const imageData = response.output?.filter((output) => output.type === "image_generation_call");
if (imageData && imageData.length > 0 && imageData[0].result) {
console.log("Downloading generated image...");
const __filename = fileURLToPath(import.meta.url);
const __dirname = path.dirname(__filename);
const filename = "microsoft.png";
const filePath = path.join(__dirname, filename);
// Decode base64 and save to file
const imageBuffer = Buffer.from(imageData[0].result, "base64");
fs.writeFileSync(filePath, imageBuffer);
console.log(`Image downloaded and saved to: ${path.resolve(filePath)}`);
} else {
console.log("No image data found in the response.");
}Web Search (Preview)
Perform general web searches to retrieve current information from the internet. OpenAI Documentation
const openAIClient = project.getOpenAIClient();
// Create Agent with web search tool
const agent = await project.agents.createVersion("agent-web-search", {
kind: "prompt",
model: deploymentName,
instructions: "You are a helpful assistant that can search the web",
tools: [
{
type: "web_search_preview",
user_location: {
type: "approximate",
country: "GB",
city: "London",
region: "London",
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation for the agent interaction
const conversation = await openAIClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send a query to search the web
console.log("\nSending web search query...");
const response = await openAIClient.responses.create(
{
conversation: conversation.id,
input: "Show me the latest London Underground service updates",
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);
console.log(`Response: ${response.output_text}`);See the full sample code in agentWebSearch.ts.
Computer Use
Enable agents to interact directly with computer systems for task automation and system operations (requires a model deployment that supports the computer tool, such as gpt-5.4; for computer-use-preview deployments, use computer_use_preview):
const agent = await project.agents.createVersion("ComputerUseAgent", {
kind: "prompt" as const,
model: deploymentName,
instructions: `
You are a computer automation assistant.
Be direct and efficient. When you reach the search results page, read and describe the actual search result titles and descriptions you can see.
`.trim(),
tools: [
{
type: "computer",
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);After calling responses.create(), process the response in an interaction loop. Handle computer_call output items and provide screenshots as computer_call_output with computer_screenshot type to continue the interaction.
See the full sample code in agentComputerUse.ts.
Model Context Protocol (MCP)
Integrate MCP servers to extend agent capabilities with standardized tools and resources. OpenAI Documentation
const openAIClient = project.getOpenAIClient();
const agent = await project.agents.createVersion("agent-mcp", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful agent that can use MCP tools to assist users. Use the available MCP tools to answer questions and perform tasks.",
tools: [
{
type: "mcp",
server_label: "api-specs",
server_url: "https://gitmcp.io/Azure/azure-rest-api-specs",
require_approval: "always",
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);
// Create a conversation thread to maintain context across multiple interactions
console.log("\nCreating conversation...");
const conversation = await openAIClient.conversations.create();
console.log(`Created conversation (id: ${conversation.id})`);
// Send initial request that will trigger the MCP tool to access Azure REST API specs
// This will generate an approval request since requireApproval="always"
console.log("\nSending request that will trigger MCP approval...");
const response = await openAIClient.responses.create(
{
conversation: conversation.id,
input: "Please summarize the Azure REST API specifications Readme",
},
{
body: { agent: { name: agent.name, type: "agent_reference" } },
},
);After calling responses.create(), check for mcp_approval_request items in the response output. Send back McpApprovalResponse with your approval decision to allow the agent to continue its work.
See the full sample code in agentMcp.ts.
OpenAPI
Call external APIs defined by OpenAPI specifications without additional client-side code. OpenAI Documentation
const weatherSpecPath = path.resolve(__dirname, "../assets", "weather_openapi.json");
const agent = await project.agents.createVersion("MyOpenApiAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful assistant that can call external APIs defined by OpenAPI specs to answer user questions. When calling the weather tool, always include the query parameter format=j1.",
tools: [
{
type: "openapi",
openapi: {
name: "get_weather",
description: "Retrieve weather information for a location using wttr.in",
spec: weatherSpecPath,
auth: { type: "anonymous" },
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentOpenApi.ts.
Function Tool
Define custom functions that allow agents to interact with external APIs, databases, or application logic. OpenAI Documentation
/**
* Define a function tool for the model to use
*/
const funcTool = {
type: "function" as const,
function: {
name: "get_horoscope",
description: "Get today's horoscope for an astrological sign.",
strict: true,
parameters: {
type: "object",
properties: {
sign: {
type: "string",
description: "An astrological sign like Taurus or Aquarius",
},
},
required: ["sign"],
additional_properties: false,
},
},
};
const agent = await project.agents.createVersion("function-tool-agent", {
kind: "prompt",
model: deploymentName,
instructions: "You are a helpful assistant that can use function tools.",
tools: [funcTool],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);After calling responses.create(), process function_call items from response output, execute your function logic with the provided arguments, and send back FunctionCallOutput with the results.
See the full sample code in agentFunctionTool.ts.
- Memory Search Tool (Preview)
The Memory Store Tool adds Memory to an Agent, allowing the Agent's AI model to search for past information related to the current user prompt.
The embeddingModelDeployment is the name of the model used to create vector embeddings for storing and searching memories.
const memoryStoreName = "AgentMemoryStore";
const embeddingModelDeployment =
process.env["MEMORY_STORE_EMBEDDING_MODEL_DEPLOYMENT_NAME"] || "<embedding model>";
const scope = "user_123";
const memoryStore = await project.beta.memoryStores.create(
memoryStoreName,
{
kind: "default",
chat_model: deploymentName,
embedding_model: embeddingModelDeployment,
options: {
user_profile_enabled: true,
chat_summary_enabled: true,
},
},
{
description: "Memory store for agent conversations",
},
);
console.log(
`Created memory store: ${memoryStore.name} (${memoryStore.id}) using chat model '${deploymentName}'`,
);
// Create an agent that will use the Memory Search tool
const agent = await project.agents.createVersion("MemorySearchAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful assistant that remembers user preferences using the memory search tool.",
tools: [
{
type: "memory_search_preview",
memory_store_name: memoryStore.name,
scope,
update_delay: 1, // wait briefly after conversation inactivity before updating memories
},
],
});See the full sample code in agentMemorySearch.ts.
Connection-Based Tools
These tools require configuring connections in your AI Foundry project and use projectConnectionId.
Azure AI Search
Integrate with Azure AI Search indexes for powerful knowledge retrieval and semantic search capabilities:
const aiSearchConnectionId = process.env["AI_SEARCH_CONNECTION_ID"] || "";
const aiSearchIndexName = process.env["AI_SEARCH_INDEX_NAME"] || "";
const agent = await project.agents.createVersion("MyAISearchAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful assistant. You must always provide citations for answers using the tool and render them as: `[message_idx:search_idx†source]`.",
tools: [
{
type: "azure_ai_search",
azure_ai_search: {
indexes: [
{
project_connection_id: aiSearchConnectionId,
index_name: aiSearchIndexName,
query_type: "simple",
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentAiSearch.ts.
Bing Grounding
Ground agent responses with real-time web search results from Bing to provide up-to-date information:
const bingProjectConnectionId = process.env["BING_GROUNDING_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyBingGroundingAgent", {
kind: "prompt",
model: deploymentName,
instructions: "You are a helpful assistant.",
tools: [
{
type: "bing_grounding",
bing_grounding: {
search_configurations: [
{
project_connection_id: bingProjectConnectionId,
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentBingGrounding.ts.
Bing Custom Search (Preview)
Use custom-configured Bing search instances for domain-specific or filtered web search results:
const bingCustomSearchProjectConnectionId = process.env["BING_CUSTOM_SEARCH_CONNECTION_ID"] || "";
const bingCustomSearchInstanceName = process.env["BING_CUSTOM_SEARCH_INSTANCE_NAME"] || "";
const agent = await project.agents.createVersion("MyAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful agent that can use Bing Custom Search tools to assist users. Use the available Bing Custom Search tools to answer questions and perform tasks.",
tools: [
{
type: "bing_custom_search_preview",
bing_custom_search_preview: {
search_configurations: [
{
project_connection_id: bingCustomSearchProjectConnectionId,
instance_name: bingCustomSearchInstanceName,
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentBingCustomSearch.ts.
Microsoft Fabric (Preview)
Connect to and query Microsoft Fabric:
const fabricProjectConnectionId = process.env["FABRIC_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyFabricAgent", {
kind: "prompt",
model: deploymentName,
instructions: "You are a helpful assistant.",
tools: [
{
type: "fabric_dataagent_preview",
fabric_dataagent_preview: {
project_connections: [
{
project_connection_id: fabricProjectConnectionId,
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentFabric.ts.
Microsoft SharePoint (Preview)
Access and search SharePoint documents, lists, and sites for enterprise knowledge integration:
const sharepointProjectConnectionId = process.env["SHAREPOINT_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a helpful agent that can use SharePoint tools to assist users. Use the available SharePoint tools to answer questions and perform tasks.",
// Define SharePoint tool that searches SharePoint content
tools: [
{
type: "sharepoint_grounding_preview",
sharepoint_grounding_preview: {
project_connections: [
{
project_connection_id: sharepointProjectConnectionId,
},
],
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentSharepoint.ts.
Browser Automation
Automate browser interactions for web scraping, testing, and interaction with web applications:
const browserAutomationProjectConnectionId =
process.env["BROWSER_AUTOMATION_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyAgent", {
kind: "prompt",
model: deploymentName,
instructions: `You are an Agent helping with browser automation tasks.
You can answer questions, provide information, and assist with various tasks
related to web browsing using the Browser Automation tool available to you.`,
// Define Browser Automation tool
tools: [
{
type: "browser_automation",
browser_automation: {
connection: {
project_connection_id: browserAutomationProjectConnectionId,
},
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentBrowserAutomation.ts.
Set FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL_NAME, and
BROWSER_AUTOMATION_PROJECT_CONNECTION_ID (the project connection resource ID for
your Azure Playwright resource) before running the sample. It uses the GA
browser_automation tool to visit https://example.com and report the page title
and visible description based on browser results. Optionally set FOUNDRY_AGENT_NAME
to choose the agent name; it defaults to MyAgent.
The streaming sample prints each completed text message once, including the
browser live-view URL, and logs remote function action names, call IDs, and
arguments without browserSessionId. Treat the live-view URL as sensitive: do not
share it or commit it to source control. Failed or incomplete responses exit with
a nonzero status instead of reporting success. The sample deletes the agent version
it created in a finally block, whether response processing succeeds or fails.
MCP with Project Connection
MCP integration using project-specific connections for accessing connected MCP servers:
const mcpProjectConnectionId = process.env["MCP_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("agent-mcp-connection-auth", {
kind: "prompt",
model: deploymentName,
instructions: "Use MCP tools as needed",
tools: [
{
type: "mcp",
server_label: "api-specs",
server_url: "https://api.githubcopilot.com/mcp",
require_approval: "always",
project_connection_id: mcpProjectConnectionId,
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentMcpConnectionAuth.ts.
Agent-to-Agent (A2A) (Preview)
Enable multi-agent collaboration where agents can communicate and delegate tasks to other specialized agents:
const a2aProjectConnectionId = process.env["A2A_PROJECT_CONNECTION_ID"] || "";
const agent = await project.agents.createVersion("MyA2AAgent", {
kind: "prompt",
model: deploymentName,
instructions: "You are a helpful assistant.",
// Define A2A tool for agent-to-agent communication
tools: [
{
type: "a2a_preview",
project_connection_id: a2aProjectConnectionId,
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentAgentToAgent.ts.
OpenAPI with Project Connection
Call external APIs defined by OpenAPI specifications using project connection authentication:
const tripAdvisorProjectConnectionId = process.env["TRIPADVISOR_PROJECT_CONNECTION_ID"] || "";
function loadOpenApiSpec(specPath: string): unknown {
if (!fs.existsSync(specPath)) {
throw new Error(`OpenAPI specification not found at: ${specPath}`);
}
try {
const data = fs.readFileSync(specPath, "utf-8");
return JSON.parse(data);
} catch (error) {
throw new Error(`Failed to read or parse OpenAPI specification at ${specPath}: ${error}`);
}
}
const tripAdvisorSpecPath = path.resolve(__dirname, "../assets", "tripadvisor_openapi.json");
const tripAdvisorSpec = loadOpenApiSpec(tripAdvisorSpecPath);
const agent = await project.agents.createVersion("MyOpenApiConnectionAgent", {
kind: "prompt",
model: deploymentName,
instructions:
"You are a travel assistant that consults the TripAdvisor Content API via project connection to answer user questions about locations.",
tools: [
{
type: "openapi",
openapi: {
name: "get_tripadvisor_location_details",
description:
"Fetch TripAdvisor location details, reviews, or photos using the Content API via project connection auth.",
spec: tripAdvisorSpec,
auth: {
type: "project_connection",
security_scheme: {
project_connection_id: tripAdvisorProjectConnectionId,
},
},
},
},
],
});
console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);See the full sample code in agentOpenApiConnectionAuth.ts.
For complete working examples of all tools, see the samples-dev directory.
Evaluation
Evaluation in Azure AI Project client library provides quantitative, AI-assisted quality and safety metrics to asses performance and Evaluate LLM Models, GenAI Application and Agents. Metrics are defined as evaluators. Built-in or custom evaluators can provide comprehensive evaluation insights.
The code below shows some evaluation operations. Full list of sample can be found under "evaluations" folder in the [package samples][samples]
const openAIClient = project.getOpenAIClient();
const dataSourceConfig = {
type: "custom" as const,
item_schema: {
type: "object",
properties: { query: { type: "string" } },
required: ["query"],
},
include_sample_schema: true,
};
const evalObject = await openAIClient.evals.create({
name: "Agent Evaluation",
data_source_config: dataSourceConfig,
testing_criteria: [
{
type: "azure_ai_evaluator",
name: "violence_detection",
evaluator_name: "builtin.violence",
data_mapping: { query: "{{item.query}}", response: "{{item.response}}" },
} as any,
],
});
console.log(`Evaluation created (id: ${evalObject.id}, name: ${evalObject.name})`);See the full sample code in agentEvaluation.ts.
Deployments operations
The code below shows some Deployments operations, which allow you to enumerate the AI models deployed to your Microsoft Foundry Projects. These models can be seen in the "Models + endpoints" tab in your Microsoft Foundry Project. Full samples can be found under the "deployment" folder in the [package samples][samples].
import { ModelDeployment } from "@azure/ai-projects";
const modelPublisher = process.env["MODEL_PUBLISHER"] || "<model publisher>";
console.log("List all deployments:");
const deployments: ModelDeployment[] = [];
const properties: Array<Record<string, string>> = [];
for await (const deployment of project.deployments.list()) {
// Check if this is a ModelDeployment (has the required properties)
if (
deployment.type === "ModelDeployment" &&
"modelName" in deployment &&
"modelPublisher" in deployment &&
"modelVersion" in deployment
) {
deployments.push(deployment);
properties.push({
name: deployment.name,
modelPublisher: deployment.modelPublisher,
modelName: deployment.modelName,
});
}
}
console.log(`Retrieved deployments: ${JSON.stringify(properties, null, 2)}`);
// List all deployments by