企业官网建设流程全解析

• AI 技能
• AI 插件
• 人工智能

导读

本文围绕开源仓库 agentic-awesome-skills 中收录的 azure-ai-projects-ts 技能文档展开，系统讲解如何通过@azure/ai-projects这一 Azure AI Foundry 项目级高阶 SDK，在 TypeScript 环境中完成 AI 代理（Agent）的创建、工具绑定、对话运行，以及连接（Connections）、部署（Deployments）、数据集（Datasets）与搜索索引（Indexes）的全生命周期管理。读完本文，你将掌握一套可直接复制运行的接入方案：从环境变量配置、凭据认证，到基于代码解释器、文件搜索、Web 搜索、Azure AI Search、函数与 MCP 工具的多种代理定义方式，并理解各操作组（Operation Groups）背后的资源管理语义。

一、技能背景：AAS 技能目录中的 Azure AI 集成

在 agentic-awesome-skills 的技能体系中，azure-ai-projects-ts属于「AI 应用开发 / 微软 Azure AI」方向的社区贡献技能（source: community，date_added: "2026-02-27"，风险等级risk: critical）。该技能的核心定位是：

面向 Azure AI Foundry 项目的高阶 SDK，覆盖 agents、connections、deployments 与 evaluations 等能力。

与该技能同目录族谱的还有 azure-ai-projects-py、azure-ai-projects-dotnet、azure-ai-projects-java，说明 AAS 将该 SDK 的能力面按语言族拆分为多份技能，供 Agent 按任务语言环境选择。本文聚焦 TypeScript 版本。

技能被标记为risk: critical意味着它可能操作真实云资源（创建/删除代理、上传数据集、读写连接凭据），因此文档末尾的 Limitations 部分特别强调：仅在任务明确匹配技能范围时使用，且输出不能替代环境级验证、测试或专家评审。

二、安装：SDK 与遥测依赖

安装@azure/ai-projects及其身份认证依赖：

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

若需要链路追踪（tracing），再安装 Azure Monitor OpenTelemetry 导出器与 OpenTelemetry API：

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

从依赖拆分可以看出使用场景的边界：@azure/ai-projects是核心 SDK，@azure/identity提供 Azure 云凭据抽象；而@azure/monitor-opentelemetry+@opentelemetry/api属于可选项，仅在需要把代理调用链路上报给 Application Insights 等监控后端时引入。

三、环境变量：最小化可运行配置

SDK 客户端实例化依赖两个环境变量：

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

注意端点与 OpenAI 直连端点不同：这里是项目级控制面端点（/api/projects/<project>），SDK 据此路由到代理、连接、部署等项目管理 API，而模型推理走的是getOpenAIClient()返回的客户端。

四、身份认证：DefaultAzureCredential 链式凭据

认证是接入的第一步。技能文档给出的标准做法是使用DefaultAzureCredential：

import { AIProjectClient } from "@azure/ai-projects"; import { DefaultAzureCredential } from "@azure/identity"; const client = new AIProjectClient( process.env.AZURE_AI_PROJECT_ENDPOINT!, new DefaultAzureCredential() );

要点说明：

• DefaultAzureCredential会按顺序尝试多种凭据来源（本地开发时常见的是 Azure CLI 登录态、环境变量凭据、托管身份等），从而让同一份代码在本地开发与云端运行时都能无缝认证；
• 客户端构造函数仅需「端点 + 凭据」两个参数；如需自定义重试、超时或添加 API 版本等选项，可传入AIProjectClientOptionalParams（见下文「关键类型」一节）；
• 安全实践：不要硬编码密钥。连接（Connections）操作组提供的getWithCredentials正是为了从项目连接中按需取出凭据，避免凭据落盘。

五、操作组（Operation Groups）总览

AIProjectClient将 Azure AI Foundry 项目的资源管理能力按域拆分为 7 个操作组，是理解整个 SDK 的骨架：

使用模式高度一致：list()是异步可迭代（for await），get(name)按名读取，createOrUpdate / upload / delete完成写操作。掌握一个操作组的模式即可举一反三。

六、获取 OpenAI 客户端：对话与响应能力

模型推理不在AIProjectClient上直接暴露，而是通过getOpenAIClient()获取一个 OpenAI 兼容客户端：

const openAIClient = await client.getOpenAIClient(); // 用于单轮响应（responses） const response = await openAIClient.responses.create({ model: "gpt-4o", input: "What is the capital of France?" }); // 用于多轮会话（conversations） const conversation = await openAIClient.conversations.create({ items: [{ type: "message", role: "user", content: "Hello!" }] });

两个核心入口：

• responses.create：无状态推理，适合一次性问答，model应使用项目内实际存在的部署名（即环境变量MODEL_DEPLOYMENT_NAME对应的值）；
• conversations.create：有状态会话容器，items数组承载消息序列；创建后可将conversation.id传给responses.create实现多轮对话，用毕后通过conversations.delete(id)清理。

从技能文档 Best Practices 第 1 条可确认：responses、conversations、files 与 vector stores 等与推理/检索直接相关的能力都经由getOpenAIClient()使用。

七、Agent 定义：创建、工具绑定与运行

7.1 创建基础代理

client.agents操作组使用版本化接口createVersion，每次创建都需要代理名、kind（示例为"prompt"）、模型与指令：

const agent = await client.agents.createVersion("my-agent", { kind: "prompt", model: "gpt-4o", instructions: "You are a helpful assistant." });

createVersion是技能文档反复强调的最佳实践（Best Practices 第 2 条）：通过显式版本号固化代理定义，使代理行为可复现、可回滚，适合纳入 CI/CD 或作为团队共享的「代理即代码」资产。

7.2 绑定工具：六种内置工具类型

技能文档完整给出了 6 种工具绑定方式，本文按类型逐一展开。

① Code Interpreter（代码解释器）——让代理执行代码：

const agent = await client.agents.createVersion("code-agent", { kind: "prompt", model: "gpt-4o", instructions: "You can execute code.", tools: [{ type: "code_interpreter", container: { type: "auto" } }] });

container指定沙箱容器类型，"auto"表示由平台自动管理运行环境。

② File Search（文件检索）——基于向量存储的 RAG：

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

vectorStoreId来自 OpenAI 客户端的 vector stores 能力（getOpenAIClient()侧），文件先入向量库再供代理检索。

③ Web Search（Web 搜索预览）——联网检索并支持位置近似：

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" } }] });

user_location使用approximate近似位置模型，用于区域化检索结果，可按需调整国家与城市。

④ 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" }] } }] });

project_connection_id指向项目内已配置的 Azure AI Search 连接（见 Connections 操作组），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: "Get weather for a location", strict: true, parameters: { type: "object", properties: { location: { type: "string" } }, required: ["location"] } } }] });

strict: true启用严格 JSON Schema 模式，保证模型输出严格匹配parameters定义；parameters遵循标准 JSON Schema（type/properties/required）。

⑥ MCP Tool（Model Context Protocol）——接入外部 MCP 服务器：

const agent = await client.agents.createVersion("mcp-agent", { kind: "prompt", model: "gpt-4o", tools: [{ type: "mcp", server_label: "my-mcp", server_url: "https://mcp-server.example.com", require_approval: "always" }] });

server_label是 MCP 服务器的本地标签，server_url为远程 MCP 端点，require_approval: "always"表示每次调用外部 MCP 工具都要求人工审批——这与技能risk: critical的定位一致，是安全边界上的关键开关。

7.3 运行 Agent 并清理资源

代理本身不直接推理，需要通过 OpenAI 客户端的会话机制驱动：

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);

这里展示了完整的资源生命周期：创建会话 → 用agent_reference类型的 body 指定由哪个代理处理 → 清理会话与代理。deleteVersion需要同时提供agent.name与agent.version，对应版本化 API 的语义。

八、Connections：连接管理与凭据安全

Connections 操作组封装了项目内已连 Azure 资源的读取能力：

// 列出全部连接 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);

关键区分：

• get(name)只返回连接元数据（名称、类型），不含密钥；
• getWithCredentials(name)额外携带凭据，用于真正发起对下游服务的调用；
• getDefault(type, withCredentials)按资源类型（如"AzureOpenAI"）取该类型默认连接，第二个布尔参数控制是否返回凭据。

这正是技能文档 Best Practices 第 4 条「从项目连接获取凭据，不要硬编码」的落地入口，建议在读取 Azure AI Search 等下游资源时优先通过连接标识符间接引用。

九、Deployments：模型部署发现与筛选

Deployments 操作组用于在调用模型前确认可用部署：

// 列出全部部署，区分模型部署类型 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");

list()返回的部署对象带type判别字段（示例判断"ModelDeployment"），并暴露modelName属性；list({ modelPublisher: "OpenAI" })展示了按模型发布方过滤的能力——技能文档 Best Practices 第 5 条建议用modelPublisher筛选以定位特定模型族（如 OpenAI 系），避免在混合模型环境中盲目调用。

十、Datasets：数据集上传与版本管理

Datasets 操作组支持单文件与文件夹两种上传方式，并带版本概念：

// 上传单个文件 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");

uploadFile与uploadFolder的前两个参数均为（数据集名, 版本号），第三个参数是本地路径；数据集的读写均以「名称 + 版本」二元组定位，天然支持多版本并存与回滚，适合存放评估（evaluations）所需的训练/测试样本——这与操作组client.evaluators的评估能力形成配套。

十一、Indexes：Azure AI Search 索引生命周期

Indexes 操作组管理搜索索引资源，使用AzureAISearchIndex类型描述配置：

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");

AzureAISearchIndex配置项解析：

索引与 Agent 的 File Search / Azure AI Search 工具配合：索引先行（createOrUpdate），再把索引挂到代理的azure_ai_search工具上，形成「数据入索引 → 代理检索」的 RAG 闭环。

十二、关键类型（Key Types）

技能文档明确列出的核心导出类型，供类型安全的工程引用：

import { AIProjectClient, AIProjectClientOptionalParams, Connection, ModelDeployment, DatasetVersionUnion, AzureAISearchIndex } from "@azure/ai-projects";

十三、最佳实践汇总

技能文档的 Best Practices 部分为生产化使用提供了 5 条准则，展开如下：

1. 优先使用getOpenAIClient()：responses、conversations、files、vector stores 等推理与检索能力统一经此客户端访问，避免绕过 SDK 直接构造底层 HTTP 调用；
2. 为 Agent 做版本管理：使用createVersion固化代理定义，保证可复现、可回滚，便于团队协作与审计；
3. 及时清理资源：对话、代理在任务结束后调用conversations.delete/agents.deleteVersion释放，避免云端资源堆积产生费用；
4. 善用 Connections 取凭据：通过getWithCredentials/getDefault(type, true)按需取凭据，杜绝在代码或环境变量中硬编码密钥；
5. 用modelPublisher过滤部署：在多模型项目中按发布方（如"OpenAI"）筛选部署，精准命中目标模型族。

十四、适用范围与限制（When to Use & Limitations）

技能文档明确了该技能的边界，这也是引用该技能时 Agent 应遵守的护栏：

• 适用范围：仅当任务与本文档概述中描述的工作流/动作吻合时使用——即面向 Azure AI Foundry 项目做代理创建、连接管理、部署查询、数据集与索引维护、评估等操作；
• 不替代验证：SDK 输出不能替代环境级验证、测试或专家评审；云端资源行为可能因订阅、策略与版本而不同，生产变更前必须实测；
• 缺失即询问：当输入、权限、安全边界或成功标准不明确时，应停止执行并请求澄清，而非擅自猜测——尤其考虑到该技能risk: critical的风险等级，涉及资源创建/删除类操作前务必确认影响范围。

十五、仓库中的相关资源

想进一步在 AAS 生态中定位与本主题相关的素材，可参考以下仓库路径：

• 本文档源：plugins/agentic-awesome-skills-claude/skills/azure-ai-projects-ts/SKILL.md（另见 plugins/agentic-awesome-skills/skills/azure-ai-projects-ts/SKILL.md 的同源副本）；
• 同族跨语言技能：plugins/agentic-awesome-skills-claude/skills/azure-ai-projects-py/SKILL.md、azure-ai-projects-dotnet、azure-ai-projects-java；
• 配套观测能力：plugins/agentic-awesome-skills-claude/skills/azure-monitor-opentelemetry-py/SKILL.md（与 tracing 依赖@azure/monitor-opentelemetry同域）；
• 技能目录索引：skills_index.json 与 data/catalog.json，可查看该技能在整体目录中的分类归属。

综上，azure-ai-projects-ts技能文档提供了一条从「端点配置 → 凭据认证 → 操作组遍历 → 代理定义与运行 → 资源清理」的完整 TypeScript 接入路径。将其与 AAS 的本地目录发现与技能调度机制配合，即可让 Agent 在真实 Azure AI Foundry 项目中安全、可审计地完成代理化应用的构建与运维。

• AI 技能
• AI 插件
• 人工智能