GitHub Copilot ChatGPT Claude Codex CLI Cursor opencode Skill Text

azure-ai-projects-ts

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.

Ciza · 0 points · 22 views 1 listing impressions 0 install-command copies
Download microsoft-skills-.github_plugins_azure-sdk-typescript_skills_azure-ai-projects-ts-e58528d.zip · 7 KB

Install

skills CLI npx skills add https://github.com/microsoft/skills/tree/main/.github/plugins/azure-sdk-typescript/skills/azure-ai-projects-ts
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install microsoft-skills@llmmart
Git git clone https://github.com/microsoft/skills.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole microsoft/skills collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Azure AI Projects SDK for TypeScript

High-level SDK for Azure AI Foundry projects with agents, connections, deployments, and evaluations.

Installation

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

For tracing:

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

Environment Variables

AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
MODEL_DEPLOYMENT_NAME=gpt-4o
AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production

Authentication

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

// Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
// Or use a specific credential directly in production:
// See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
// const credential = new ManagedIdentityCredential();

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

Operation Groups

Group Purpose
client.agents Create and manage AI agents
client.connections List connected Azure resources
client.deployments List model deployments
client.datasets Upload and manage datasets
client.indexes Create and manage search indexes
client.evaluators Manage evaluation metrics
client.memoryStores Manage agent memory

Getting OpenAI Client

const openAIClient = await client.getOpenAIClient();

// Use for responses
const response = await openAIClient.responses.create({
  model: "gpt-4o",
  input: "What is the capital of France?"
});

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

Agents

Create Agent

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

Agent with Tools

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

// 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: "Get weather for a location",
      strict: true,
      parameters: {
        type: "object",
        properties: { location: { type: "string" } },
        required: ["location"]
      }
    }
  }]
});

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

Run Agent

const openAIClient = await client.getOpenAIClient();

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

// Generate response using agent
const response = await openAIClient.responses.create(
  { conversation: conversation.id },
  { body: { agent: { name: agent.name, type: "agent_reference" } } }
);

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

Connections

// List all connections
for await (const conn of client.connections.list()) {
  console.log(conn.name, conn.type);
}

// Get connection by name
const conn = await client.connections.get("my-connection");

// Get connection with credentials
const connWithCreds = await client.connections.getWithCredentials("my-connection");

// Get default connection by type
const defaultAzureOpenAI = await client.connections.getDefault("AzureOpenAI", true);

Deployments

// List all deployments
for await (const deployment of client.deployments.list()) {
  if (deployment.type === "ModelDeployment") {
    console.log(deployment.name, deployment.modelName);
  }
}

// Filter by publisher
for await (const d of client.deployments.list({ modelPublisher: "OpenAI" })) {
  console.log(d.name);
}

// Get specific deployment
const deployment = await client.deployments.get("gpt-4o");

Datasets

// Upload single file
const dataset = await client.datasets.uploadFile(
  "my-dataset",
  "1.0",
  "./data/training.jsonl"
);

// Upload folder
const dataset = await client.datasets.uploadFolder(
  "my-dataset",
  "2.0",
  "./data/documents/"
);

// Get dataset
const ds = await client.datasets.get("my-dataset", "1.0");

// List versions
for await (const version of client.datasets.listVersions("my-dataset")) {
  console.log(version);
}

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

Indexes

import { AzureAISearchIndex } from "@azure/ai-projects";

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

// Create index
const index = await client.indexes.createOrUpdate("my-index", "1", indexConfig);

// List indexes
for await (const idx of client.indexes.list()) {
  console.log(idx.name);
}

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

Key Types

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

Best Practices

  1. Use getOpenAIClient() - For responses, conversations, files, and vector stores
  2. Version your agents - Use createVersion for reproducible agent definitions
  3. Clean up resources - Delete agents, conversations when done
  4. Use connections - Get credentials from project connections, don't hardcode
  5. Filter deployments - Use modelPublisher filter to find specific models
Files (skills)
  • references
    • connections.md 5.5 KB
      Loading…
    • evaluations.md 8.3 KB
      Loading…
  • SKILL.md 7.4 KB
    ---
    name: azure-ai-projects-ts
    description: 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.
    license: MIT
    metadata:
      author: Microsoft
      version: "1.0.0"
      package: '@azure/ai-projects'
    ---
    
    # Azure AI Projects SDK for TypeScript
    
    High-level SDK for Azure AI Foundry projects with agents, connections, deployments, and evaluations.
    
    ## Installation
    
    ```bash
    npm install @azure/ai-projects @azure/identity
    ```
    
    For tracing:
    ```bash
    npm install @azure/monitor-opentelemetry @opentelemetry/api
    ```
    
    ## Environment Variables
    
    ```bash
    AZURE_AI_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>
    MODEL_DEPLOYMENT_NAME=gpt-4o
    AZURE_TOKEN_CREDENTIALS=prod # Required only if DefaultAzureCredential is used in production
    ```
    
    ## Authentication
    
    ```typescript
    import { AIProjectClient } from "@azure/ai-projects";
    import { DefaultAzureCredential, ManagedIdentityCredential } from "@azure/identity";
    
    // Local dev: DefaultAzureCredential. Production: set AZURE_TOKEN_CREDENTIALS=prod or AZURE_TOKEN_CREDENTIALS=<specific_credential>
    const credential = new DefaultAzureCredential({requiredEnvVars: ["AZURE_TOKEN_CREDENTIALS"]});
    // Or use a specific credential directly in production:
    // See https://learn.microsoft.com/javascript/api/overview/azure/identity-readme?view=azure-node-latest#credential-classes
    // const credential = new ManagedIdentityCredential();
    
    const client = new AIProjectClient(
      process.env.AZURE_AI_PROJECT_ENDPOINT!,
      credential
    );
    ```
    
    ## Operation Groups
    
    | Group | Purpose |
    |-------|---------|
    | `client.agents` | Create and manage AI agents |
    | `client.connections` | List connected Azure resources |
    | `client.deployments` | List model deployments |
    | `client.datasets` | Upload and manage datasets |
    | `client.indexes` | Create and manage search indexes |
    | `client.evaluators` | Manage evaluation metrics |
    | `client.memoryStores` | Manage agent memory |
    
    ## Getting OpenAI Client
    
    ```typescript
    const openAIClient = await client.getOpenAIClient();
    
    // Use for responses
    const response = await openAIClient.responses.create({
      model: "gpt-4o",
      input: "What is the capital of France?"
    });
    
    // Use for conversations
    const conversation = await openAIClient.conversations.create({
      items: [{ type: "message", role: "user", content: "Hello!" }]
    });
    ```
    
    ## Agents
    
    ### Create Agent
    
    ```typescript
    const agent = await client.agents.createVersion("my-agent", {
      kind: "prompt",
      model: "gpt-4o",
      instructions: "You are a helpful assistant."
    });
    ```
    
    ### Agent with Tools
    
    ```typescript
    // 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" } }]
    });
    
    // 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: "Get weather for a location",
          strict: true,
          parameters: {
            type: "object",
            properties: { location: { type: "string" } },
            required: ["location"]
          }
        }
      }]
    });
    
    // MCP Tool
    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"
      }]
    });
    ```
    
    ### Run Agent
    
    ```typescript
    const openAIClient = await client.getOpenAIClient();
    
    // Create conversation
    const conversation = await openAIClient.conversations.create({
      items: [{ type: "message", role: "user", content: "Hello!" }]
    });
    
    // Generate response using agent
    const response = await openAIClient.responses.create(
      { conversation: conversation.id },
      { body: { agent: { name: agent.name, type: "agent_reference" } } }
    );
    
    // Cleanup
    await openAIClient.conversations.delete(conversation.id);
    await client.agents.deleteVersion(agent.name, agent.version);
    ```
    
    ## Connections
    
    ```typescript
    // List all connections
    for await (const conn of client.connections.list()) {
      console.log(conn.name, conn.type);
    }
    
    // Get connection by name
    const conn = await client.connections.get("my-connection");
    
    // Get connection with credentials
    const connWithCreds = await client.connections.getWithCredentials("my-connection");
    
    // Get default connection by type
    const defaultAzureOpenAI = await client.connections.getDefault("AzureOpenAI", true);
    ```
    
    ## Deployments
    
    ```typescript
    // List all deployments
    for await (const deployment of client.deployments.list()) {
      if (deployment.type === "ModelDeployment") {
        console.log(deployment.name, deployment.modelName);
      }
    }
    
    // Filter by publisher
    for await (const d of client.deployments.list({ modelPublisher: "OpenAI" })) {
      console.log(d.name);
    }
    
    // Get specific deployment
    const deployment = await client.deployments.get("gpt-4o");
    ```
    
    ## Datasets
    
    ```typescript
    // Upload single file
    const dataset = await client.datasets.uploadFile(
      "my-dataset",
      "1.0",
      "./data/training.jsonl"
    );
    
    // Upload folder
    const dataset = await client.datasets.uploadFolder(
      "my-dataset",
      "2.0",
      "./data/documents/"
    );
    
    // Get dataset
    const ds = await client.datasets.get("my-dataset", "1.0");
    
    // List versions
    for await (const version of client.datasets.listVersions("my-dataset")) {
      console.log(version);
    }
    
    // Delete
    await client.datasets.delete("my-dataset", "1.0");
    ```
    
    ## Indexes
    
    ```typescript
    import { AzureAISearchIndex } from "@azure/ai-projects";
    
    const indexConfig: AzureAISearchIndex = {
      name: "my-index",
      type: "AzureSearch",
      version: "1",
      indexName: "my-index",
      connectionName: "search-connection"
    };
    
    // Create index
    const index = await client.indexes.createOrUpdate("my-index", "1", indexConfig);
    
    // List indexes
    for await (const idx of client.indexes.list()) {
      console.log(idx.name);
    }
    
    // Delete
    await client.indexes.delete("my-index", "1");
    ```
    
    ## Key Types
    
    ```typescript
    import {
      AIProjectClient,
      AIProjectClientOptionalParams,
      Connection,
      ModelDeployment,
      DatasetVersionUnion,
      AzureAISearchIndex
    } from "@azure/ai-projects";
    ```
    
    ## Best Practices
    
    1. **Use getOpenAIClient()** - For responses, conversations, files, and vector stores
    2. **Version your agents** - Use `createVersion` for reproducible agent definitions
    3. **Clean up resources** - Delete agents, conversations when done
    4. **Use connections** - Get credentials from project connections, don't hardcode
    5. **Filter deployments** - Use `modelPublisher` filter to find specific models
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.