Azure AI Projects Ts

1---
2name: azure-ai-projects-ts
3description: Build AI applications using Azure AI Projects SDK for JavaScript (@azure/ai-projects). Use when working with Foundry project clients, agents, connections, deployments, datasets, indexes, evaluations, or getting OpenAI clients.
4package: "@azure/ai-projects"
5---
6 
7# Azure AI Projects SDK for TypeScript
8 
9High-level SDK for Azure AI Foundry projects with agents, connections, deployments, and evaluations.
10 
11## Installation
12 
13```bash
14npm install @azure/ai-projects @azure/identity
15```
16 
17For tracing:
18```bash
19npm install @azure/monitor-opentelemetry @opentelemetry/api
20```
21 
22## Environment Variables
23 
24```bash
25AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
26MODEL_DEPLOYMENT_NAME=gpt-4o
27```
28 
29## Authentication
30 
31```typescript
32import { AIProjectClient } from "@azure/ai-projects";
33import { DefaultAzureCredential } from "@azure/identity";
34 
35const client = new AIProjectClient(
36  process.env.AZURE_AI_PROJECT_ENDPOINT!,
37  new DefaultAzureCredential()
38);
39```
40 
41## Operation Groups
42 
43| Group | Purpose |
44|-------|---------|
45| `client.agents` | Create and manage AI agents |
46| `client.connections` | List connected Azure resources |
47| `client.deployments` | List model deployments |
48| `client.datasets` | Upload and manage datasets |
49| `client.indexes` | Create and manage search indexes |
50| `client.evaluators` | Manage evaluation metrics |
51| `client.memoryStores` | Manage agent memory |
52 
53## Getting OpenAI Client
54 
55```typescript
56const openAIClient = await client.getOpenAIClient();
57 
58// Use for responses
59const response = await openAIClient.responses.create({
60  model: "gpt-4o",
61  input: "What is the capital of France?"
62});
63 
64// Use for conversations
65const conversation = await openAIClient.conversations.create({
66  items: [{ type: "message", role: "user", content: "Hello!" }]
67});
68```
69 
70## Agents
71 
72### Create Agent
73 
74```typescript
75const agent = await client.agents.createVersion("my-agent", {
76  kind: "prompt",
77  model: "gpt-4o",
78  instructions: "You are a helpful assistant."
79});
80```
81 
82### Agent with Tools
83 
84```typescript
85// Code Interpreter
86const agent = await client.agents.createVersion("code-agent", {
87  kind: "prompt",
88  model: "gpt-4o",
89  instructions: "You can execute code.",
90  tools: [{ type: "code_interpreter", container: { type: "auto" } }]
91});
92 
93// File Search
94const agent = await client.agents.createVersion("search-agent", {
95  kind: "prompt",
96  model: "gpt-4o",
97  tools: [{ type: "file_search", vector_store_ids: [vectorStoreId] }]
98});
99 
100// Web Search
101const agent = await client.agents.createVersion("web-agent", {
102  kind: "prompt",
103  model: "gpt-4o",
104  tools: [{
105    type: "web_search_preview",
106    user_location: { type: "approximate", country: "US", city: "Seattle" }
107  }]
108});
109 
110// Azure AI Search
111const agent = await client.agents.createVersion("aisearch-agent", {
112  kind: "prompt",
113  model: "gpt-4o",
114  tools: [{
115    type: "azure_ai_search",
116    azure_ai_search: {
117      indexes: [{
118        project_connection_id: connectionId,
119        index_name: "my-index",
120        query_type: "simple"
121      }]
122    }
123  }]
124});
125 
126// Function Tool
127const agent = await client.agents.createVersion("func-agent", {
128  kind: "prompt",
129  model: "gpt-4o",
130  tools: [{
131    type: "function",
132    function: {
133      name: "get_weather",
134      description: "Get weather for a location",
135      strict: true,
136      parameters: {
137        type: "object",
138        properties: { location: { type: "string" } },
139        required: ["location"]
140      }
141    }
142  }]
143});
144 
145// MCP Tool
146const agent = await client.agents.createVersion("mcp-agent", {
147  kind: "prompt",
148  model: "gpt-4o",
149  tools: [{
150    type: "mcp",
151    server_label: "my-mcp",
152    server_url: "https://mcp-server.example.com",
153    require_approval: "always"
154  }]
155});
156```
157 
158### Run Agent
159 
160```typescript
161const openAIClient = await client.getOpenAIClient();
162 
163// Create conversation
164const conversation = await openAIClient.conversations.create({
165  items: [{ type: "message", role: "user", content: "Hello!" }]
166});
167 
168// Generate response using agent
169const response = await openAIClient.responses.create(
170  { conversation: conversation.id },
171  { body: { agent: { name: agent.name, type: "agent_reference" } } }
172);
173 
174// Cleanup
175await openAIClient.conversations.delete(conversation.id);
176await client.agents.deleteVersion(agent.name, agent.version);
177```
178 
179## Connections
180 
181```typescript
182// List all connections
183for await (const conn of client.connections.list()) {
184  console.log(conn.name, conn.type);
185}
186 
187// Get connection by name
188const conn = await client.connections.get("my-connection");
189 
190// Get connection with credentials
191const connWithCreds = await client.connections.getWithCredentials("my-connection");
192 
193// Get default connection by type
194const defaultAzureOpenAI = await client.connections.getDefault("AzureOpenAI", true);
195```
196 
197## Deployments
198 
199```typescript
200// List all deployments
201for await (const deployment of client.deployments.list()) {
202  if (deployment.type === "ModelDeployment") {
203    console.log(deployment.name, deployment.modelName);
204  }
205}
206 
207// Filter by publisher
208for await (const d of client.deployments.list({ modelPublisher: "OpenAI" })) {
209  console.log(d.name);
210}
211 
212// Get specific deployment
213const deployment = await client.deployments.get("gpt-4o");
214```
215 
216## Datasets
217 
218```typescript
219// Upload single file
220const dataset = await client.datasets.uploadFile(
221  "my-dataset",
222  "1.0",
223  "./data/training.jsonl"
224);
225 
226// Upload folder
227const dataset = await client.datasets.uploadFolder(
228  "my-dataset",
229  "2.0",
230  "./data/documents/"
231);
232 
233// Get dataset
234const ds = await client.datasets.get("my-dataset", "1.0");
235 
236// List versions
237for await (const version of client.datasets.listVersions("my-dataset")) {
238  console.log(version);
239}
240 
241// Delete
242await client.datasets.delete("my-dataset", "1.0");
243```
244 
245## Indexes
246 
247```typescript
248import { AzureAISearchIndex } from "@azure/ai-projects";
249 
250const indexConfig: AzureAISearchIndex = {
251  name: "my-index",
252  type: "AzureSearch",
253  version: "1",
254  indexName: "my-index",
255  connectionName: "search-connection"
256};
257 
258// Create index
259const index = await client.indexes.createOrUpdate("my-index", "1", indexConfig);
260 
261// List indexes
262for await (const idx of client.indexes.list()) {
263  console.log(idx.name);
264}
265 
266// Delete
267await client.indexes.delete("my-index", "1");
268```
269 
270## Key Types
271 
272```typescript
273import {
274  AIProjectClient,
275  AIProjectClientOptionalParams,
276  Connection,
277  ModelDeployment,
278  DatasetVersionUnion,
279  AzureAISearchIndex
280} from "@azure/ai-projects";
281```
282 
283## Best Practices
284 
2851. **Use getOpenAIClient()** - For responses, conversations, files, and vector stores
2862. **Version your agents** - Use `createVersion` for reproducible agent definitions
2873. **Clean up resources** - Delete agents, conversations when done
2884. **Use connections** - Get credentials from project connections, don't hardcode
2895. **Filter deployments** - Use `modelPublisher` filter to find specific models
290