Azure AI 项目 TypeScript SDK

azure-ai-projects-ts
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.50/5
使用3.6K

Azure AI Projects SDK for TypeScript

适用于 Azure AI Foundry 项目的高级 SDK，支持代理 (agents)、连接、部署和评估。

安装

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

如需追踪 (tracing)：

bash
npm install @azure/monitor-opentelemetry @opentelemetry/api

环境变量

bash
AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
MODEL_DEPLOYMENT_NAME=gpt-4o

身份验证

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

const client = new AIProjectClient(
  process.env.AZURE_AI_PROJECT_ENDPOINT!,
  new DefaultAzureCredential()
);

操作组

| 组 | 用途 |
|-------|---------|
| client.agents | 创建和管理 AI 代理 |
| client.connections | 列出已连接的 Azure 资源 |
| client.deployments | 列出模型部署 |
| client.datasets | 上传和管理数据集 |
| client.indexes | 创建和管理搜索索引 |
| client.evaluators | 管理评估指标 |
| client.memoryStores | 管理代理内存 |

获取 OpenAI 客户端

typescript
const openAIClient = await client.getOpenAIClient();

// 用于生成响应
const response = await openAIClient.responses.create({
  model: "gpt-4o",
  input: "法国的首都是哪里？"
});


// 用于对话
const conversation = await openAIClient.conversations.create({
  items: [{ type: "message", role: "user", content: "你好！" }]
});

代理 (Agents)

创建代理

typescript
const agent = await client.agents.createVersion("my-agent", {
  kind: "prompt",
  model: "gpt-4o",
  instructions: "你是一个得力的助手。"
});

带有工具的代理

typescript
// 代码解释器 (Code Interpreter)
const agent = await client.agents.createVersion("code-agent", {
  kind: "prompt",
  model: "gpt-4o",
  instructions: "你可以执行代码。",
  tools: [{ type: "code_interpreter", container: { type: "auto" } }]
});

// 文件搜索 (File Search)
const agent = await client.agents.createVersion("search-agent", {
  kind: "prompt",
  model: "gpt-4o",
  tools: [{ type: "file_search", vector_store_ids: [vectorStoreId] }]
});


// 网页搜索 (Web Search)
const agent = await client.agents.createVersion("web-agent", {
  kind: "prompt",
  model: "gpt-4o",
  tools: [{
    type: "web_search_preview",
    user_location: { type: "approximate", country: "US", city: "Seattle" }
  }]
});


// Azure AI Search
const agent = await client.agents.createVersion("aisearch-agent", {
  kind: "prompt",
  model: "gpt-4o",
  tools: [{
    type: "azure_ai_search",
    azure_ai_search: {
      indexes: [{
        project_connection_id: connectionId,
        index_name: "my-index",
        query_type: "simple"
      }]
    }
  }]
});


// 函数工具 (Function Tool)
const agent = await client.agents.createVersion("func-agent", {
  kind: "prompt",
  model: "gpt-4o",
  tools: [{
    type: "function",
    function: {
      name: "get_weather",
      description: "获取指定地点的天气",
      strict: true,
      parameters: {
        type: "object",
        properties: { location: { type: "string" } },
        required: ["location"]
      }
    }
  }]
});


// MCP 工具
const agent = await client.agents.createVersion("mcp-agent", {
  kin

d: "prompt",
model: "gpt-4o",
tools: [{
type: "mcp",
server_label: "my-mcp",
server_url: "https://mcp-server.example.com",
require_approval: "always"
}]
});
code
### 运行 Agent
typescript
const openAIClient = await client.getOpenAIClient();

// 创建对话
const conversation = await openAIClient.conversations.create({
items: [{ type: "message", role: "user", content: "Hello!" }]
});

// 使用 agent 生成响应
const response = await openAIClient.responses.create(
{ conversation: conversation.id },
{ body: { agent: { name: agent.name, type: "agent_reference" } } }
);

// 清理
await openAIClient.conversations.delete(conversation.id);
await client.agents.deleteVersion(agent.name, agent.version);

code
## 连接 (Connections)
typescript
// 列出所有连接
for await (const conn of client.connections.list()) {
console.log(conn.name, conn.type);
}

// 通过名称获取连接
const conn = await client.connections.get("my-connection");

// 获取带有凭据的连接
const connWithCreds = await client.connections.getWithCredentials("my-connection");

// 通过类型获取默认连接
const defaultAzureOpenAI = await client.connections.getDefault("AzureOpenAI", true);

code
## 部署 (Deployments)
typescript
// 列出所有部署
for await (const deployment of client.deployments.list()) {
if (deployment.type === "ModelDeployment") {
console.log(deployment.name, deployment.modelName);
}
}

// 按发布者过滤
for await (const d of client.deployments.list({ modelPublisher: "OpenAI" })) {
console.log(d.name);
}

// 获取特定部署
const deployment = await client.deployments.get("gpt-4o");

code
## 数据集 (Datasets)
typescript
// 上传单个文件
const dataset = await client.datasets.uploadFile(
"my-dataset",
"1.0",
"./data/training.jsonl"
);

// 上传文件夹
const dataset = await client.datasets.uploadFolder(
"my-dataset",
"2.0",
"./data/documents/"
);

// 获取数据集
const ds = await client.datasets.get("my-dataset", "1.0");

// 列出版本
for await (const version of client.datasets.listVersions("my-dataset")) {
console.log(version);
}

// 删除
await client.datasets.delete("my-dataset", "1.0");

code
## 索引 (Indexes)
typescript
import { AzureAISearchIndex } from "@azure/ai-projects";

const indexConfig: AzureAISearchIndex = {
name: "my-index",
type: "AzureSearch",
version: "1",
indexName: "my-index",
connectionName: "search-connection"
};

// 创建索引
const index = await client.indexes.createOrUpdate("my-index", "1", indexConfig);

// 列出索引
for await (const idx of client.indexes.list()) {
console.log(idx.name);
}

// 删除
await client.indexes.delete("my-index", "1");

code
## 关键类型 (Key Types)
typescript
import {
AIProjectClient,
AIProjectClientOptionalParams,
Connection,
ModelDeployment,
DatasetVersionUnion,
AzureAISearchIndex
} from "@azure/ai-projects";
``

最佳实践

1. 使用 getOpenAIClient() - 用于处理响应、对话、文件和向量存储。
2. 对 Agent 进行版本管理 - 使用 createVersion 以确保 Agent 定义的可复现性。
3. 清理资源 - 完成后删除 Agent 和对话。
4. 使用连接 - 从项目连接中获取凭据，避免硬编码。
5. 过滤部署 - 使用 modelPublisher` 过滤器查找特定模型。

适用场景

此技能适用于执行概览中描述的工作流或操作。

局限性

  • 仅在任务与以下内容明确匹配时使用此技能
  • 不要将输出结果视为针对特定环境的验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或验收标准，请立即停止并请求澄清。