Ansluta agenter till Microsoft 365 med Work IQ (förhandsversion)

Använd Foundry Toolkit för Visual Studio Code för att lägga till Work IQ som ett inbyggt verktyg när du skapar en verktygslåda och anslut sedan agenten till den publicerade verktygslådans slutpunkt. Verktyget gör de valda Work IQ-alternativen tillgängliga via MCP-slutpunkten.

1. Välj Foundry Toolkit i aktivitetsfältet.
2. Under Mina resurser expanderar du Ditt projektnamn>Verktyg.
3. Välj ikonen + Lägg till verktygslåda .
4. På fliken Skapa ett anpassat verktyg anger du verktygslådans namn och beskrivning.
5. Välj Lägg till verktyg och välj sedan Arbets-IQ.
6. I Lägg till arbets-IQ-verktyget väljer du de Microsoft 365 Copilot data som du vill använda. Work IQ Chat ansluter via en A2A-slutpunkt. Andra alternativ ansluter via MCP-slutpunkter, inklusive Copilot Chat, Teams, Word, Outlook Calendar, Outlook Mail, Microsoft 365 användarprofil, SharePoint och OneDrive.
7. För varje valt alternativ väljer du en befintlig anslutning eller väljer Skapa ny anslutning.
8. Välj Lägg till.
9. Välj Publicera.

Det fullständiga arbetsflödet för att skapa verktygslådan finns i Kuratera avsiktsbaserad verktygslåda i Foundry.

Om du vill lägga till arbets-IQ-verktyget via en verktygslåda med hjälp av kod eller REST-API:et väljer du fliken Python, .NET, JavaScript eller REST API i det här avsnittet.

Installera paketet:

pip install "azure-ai-projects>=2.3.0"

Ange följande miljövariabler:

• FOUNDRY_PROJECT_ENDPOINT – projektslutpunkten, som finns på sidan Översikt i ditt Foundry-projekt.
• WORK_IQ_PROJECT_CONNECTION_ID — det fullständigt kvalificerade resurs-ID:t för Work IQ-projektanslutningen.

Välj Fråga agenter om du vill använda Azure AI Projects SDK för att skapa en agent på serversidan eller värdbaserade agenter för att använda Microsoft Agent Framework för att skapa en tillfällig, processbaserad agent som ansluter till verktyget via en verktygslåda.

Aktivera agenter

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import PromptAgentDefinition, WorkIQPreviewTool

endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    tool_payload = WorkIQPreviewTool(
        project_connection_id=os.environ["WORK_IQ_PROJECT_CONNECTION_ID"],
    )

    agent = project_client.agents.create_version(
        agent_name="MyAgent",
        definition=PromptAgentDefinition(
        model="gpt-5-mini",
            instructions="Use the available WorkIQ tools to answer questions and perform tasks.",
            tools=[tool_payload],
        ),
    )
    print(f"Agent created (id: {agent.id}, name: {agent.name}, version: {agent.version})")

    user_input = "Summarize my recent emails about Project Contoso."
    response = openai_client.responses.create(
        input=user_input,
        extra_body={"agent_reference": {"name": agent.name, "type": "agent_reference"}},
    )

    print(f"Agent response: {response.output_text}")

    # Clean up the agent version so unused versions don't accumulate in the project.
    project_client.agents.delete_version(agent_name=agent.name, agent_version=agent.version)
    print("Agent deleted")

Förväntade utdata: Agenten anropar Arbets-IQ med användarens fråga. Arbets-IQ hämtar och syntetiserar användarens relevanta Microsoft 365 innehåll, grundat i deras behörigheter och returnerar svaret.

Hostade agenter

Skapa en verktygslåda med WorkIQPreviewToolboxTool. Den verktygslådespecifika typen skiljer sig från WorkIQPreviewTool, vilket lägger till Arbets-IQ direkt till en promptagent.

import os

from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import WorkIQPreviewToolboxTool
from azure.identity import DefaultAzureCredential

project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
work_iq_connection_id = os.environ["WORK_IQ_PROJECT_CONNECTION_ID"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(
        endpoint=project_endpoint,
        credential=credential,
    ) as project,
):
    toolbox = project.toolboxes.create_version(
        name="work-iq-toolbox",
        description="Toolbox with the Work IQ tool",
        tools=[
            WorkIQPreviewToolboxTool(
                project_connection_id=work_iq_connection_id,
            )
        ],
    )
    print(f"Created toolbox: {toolbox.name}, version: {toolbox.version}")

Exemplet returnerar den nya verktygslådans version:

Created toolbox: work-iq-toolbox, version: <version>

Anslut sedan verktygslådan till en värdbaserad agent. Det arbetsflödet använder den värdbaserade körningsintegrering för att bevara den begärandekontext som krävs för användardelegering av arbets-IQ-anrop. En fullständig Python implementering finns i aktivitetsexemplet för Agent Framework Teams.

Det rekommenderade sättet att lägga till Arbets-IQ är genom en verktygslåda och bifoga sedan verktygslådan till din agent som ett MCP-verktyg. Se Vad är en verktygslåda?

Steg 1: Skapa en verktygslåda som innehåller verktyget Work IQ:

curl --request POST \
  --url "{project_endpoint}/toolboxes/work-iq-toolbox/versions?api-version=v1" \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  --data '{
    "description": "Toolbox with the Work IQ tool",
    "tools": [
      {
        "type": "work_iq_preview",
        "project_connection_id": "/subscriptions/{sub}/resourceGroups/{rg}/providers/Microsoft.CognitiveServices/accounts/{account}/projects/{project}/connections/{connection-name}"
      }
    ]
  }'

Verktygslådan exponerar en MCP-kompatibel slutpunkt på {project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1, där <version> returneras den version som returnerades av föregående anrop.

Steg 2: Skapa en fjärrverktygsprojektanslutning som pekar på verktygslådans slutpunkt med hjälp av en entra-token för användare så att anroparens identitet skickas igenom (målgrupp https://ai.azure.com):

azd ai connection create work-iq-toolbox-conn \
  --kind remote-tool \
  --target "{project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1" \
  --auth-type user-entra-token \
  --audience https://ai.azure.com

Steg 3: Skapa agenten med verktygslådan ansluten som ett MCP-verktyg:

POST {project_endpoint}/agents/{agent_name}/versions?api-version=v1
Authorization: Bearer {token}
Content-Type: application/json

{
  "model": "gpt-4o-mini",
  "instructions": "You are a helpful assistant with access to the user's Microsoft 365 work context through Work IQ.",
  "tools": [
    {
      "type": "mcp",
      "server_label": "toolbox",
      "server_url": "{project_endpoint}/toolboxes/work-iq-toolbox/versions/<version>/mcp?api-version=v1",
      "require_approval": "never",
      "project_connection_id": "work-iq-toolbox-conn"
    }
  ]
}

Steg 4: Skapa en konversationssession:

POST {project_endpoint}/openai/v1/conversations
Authorization: Bearer {token}
Content-Type: application/json

{}

Svaret innehåller ett id fält. Använd den i nästa steg.

Steg 5: Skicka en begäran till agenten:

POST {project_endpoint}/openai/v1/responses
Authorization: Bearer {token}
Content-Type: application/json

{
  "conversation": "{conversation_id}",
  "input": "Summarize my recent emails about Project Contoso.",
  "agent_reference": {
    "type": "agent_reference",
    "name": "{agent_name}"
  }
}

Svaret innehåller metadata om agentkörningen och ett text fält i content med det syntetiserade svaret.

Välj Fråga agenter om du vill använda Azure AI Projects SDK för att skapa en agent på serversidan eller värdbaserade agenter för att använda Microsoft Agent Framework för att skapa en tillfällig, processbaserad agent som ansluter till verktyget via en verktygslåda.

Aktivera agenter

using Azure.AI.Projects;
using Azure.Identity;

var projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT");
var workIQConnectionName = Environment.GetEnvironmentVariable("WORKIQ_CONNECTION_NAME");

AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());

AIProjectConnection workIQConnection = projectClient.Connections.GetConnection(workIQConnectionName);
DeclarativeAgentDefinition agentDefinition = new(model: "gpt-5-mini")
{
    Instructions = "You are a helpful assistant that can access Microsoft 365 data through Work IQ. "
                 + "Use the Work IQ tool to search and retrieve information from emails, calendar events, "
                 + "Teams messages, and other Microsoft 365 content.",
    Tools = { new WorkIQPreviewTool(workIQConnection.Id) }
};

ProjectsAgentVersion agentVersion = projectClient.AgentAdministrationClient.CreateAgentVersion(
    agentName: "myWorkIQAgent",
    options: new(agentDefinition));
Console.WriteLine($"Agent created (name: {agentVersion.Name}, version: {agentVersion.Version})");

ProjectResponsesClient responseClient =
    projectClient.ProjectOpenAIClient.GetProjectResponsesClientForAgent(agentVersion.Name);
CreateResponseOptions responseOptions = new()
{
    ToolChoice = ResponseToolChoice.CreateRequiredChoice(),
    InputItems = { ResponseItem.CreateUserMessageItem("What meetings do I have scheduled today?") },
};
ResponseResult response = responseClient.CreateResponse(responseOptions);
Console.WriteLine(response.GetOutputText());

// Clean up
projectClient.AgentAdministrationClient.DeleteAgentVersion(
    agentName: agentVersion.Name, agentVersion: agentVersion.Version);

Hostade agenter

Skapa en verktygslåda med WorkIQPreviewToolboxTool. Den verktygslådespecifika typen skiljer sig från WorkIQPreviewTool, vilket lägger till Arbets-IQ direkt till en promptagent.

using Azure.AI.Projects;
using Azure.AI.Projects.Agents;
using Azure.Identity;

string projectEndpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string workIQConnectionName = Environment.GetEnvironmentVariable("WORKIQ_CONNECTION_NAME")
    ?? throw new InvalidOperationException("WORKIQ_CONNECTION_NAME is not set.");

DefaultAzureCredential credential = new();
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: credential);
AIProjectConnection workIQConnection = projectClient.Connections.GetConnection(workIQConnectionName);
ToolboxVersion toolboxVersion = projectClient.AgentAdministrationClient
    .GetAgentToolboxes().CreateVersion(
        name: "work-iq-toolbox",
        tools: [new WorkIQPreviewToolboxTool(workIQConnection.Id)],
        description: "Toolbox with the Work IQ tool");

Console.WriteLine(
    $"Created toolbox: {toolboxVersion.Name}, version: {toolboxVersion.Version}");

Exemplet returnerar den nya verktygslådans version:

Created toolbox: work-iq-toolbox, version: <version>

Anslut sedan verktygslådan till en värdbaserad agent. En fullständig C#-implementering som registrerar verktyg för Arbets-IQ-verktyg med Agent Framework finns i teams-aktivitetsexemplet.

const { DefaultAzureCredential } = require("@azure/identity");
const { AIProjectClient } = require("@azure/ai-projects");

const projectEndpoint = process.env["FOUNDRY_PROJECT_ENDPOINT"];
const workIqProjectConnectionId = process.env["WORKIQ_CONNECTION_ID"];

async function main() {
  const project = new AIProjectClient(projectEndpoint, new DefaultAzureCredential());
  const openai = project.getOpenAIClient();

  console.log("Creating a toolbox with the Work IQ tool...");

  // 1. Add the Work IQ tool to a toolbox. Using a toolbox is the recommended
  //    way to give agents tools. See /azure/foundry/agents/concepts/toolbox-overview
  const toolbox = await project.toolboxes.createVersion(
    "work-iq-toolbox",
    [
      {
        type: "work_iq_preview",
        project_connection_id: workIqProjectConnectionId,
      },
    ],
    { description: "Toolbox with the Work IQ tool" },
  );

  // 2. The toolbox exposes an MCP-compatible endpoint.
  const toolboxMcpUrl =
    `${projectEndpoint}/toolboxes/${toolbox.name}` +
    `/versions/${toolbox.version}/mcp?api-version=v1`;

  // 3. Create a remote-tool project connection that points at the toolbox endpoint.
  //    Use a user Entra token so the caller's identity is passed through
  //    (audience https://ai.azure.com). Create the connection once, for example
  //    with the Azure Developer CLI:
  //
  //    azd ai connection create work-iq-toolbox-conn \
  //      --kind remote-tool \
  //      --target "<toolboxMcpUrl>" \
  //      --auth-type user-entra-token \
  //      --audience https://ai.azure.com
  const toolboxConnectionName = "work-iq-toolbox-conn";

  // 4. Attach the toolbox to a prompt agent as an MCP tool.
  const agent = await project.agents.createVersion("MyWorkIQAgent", {
    kind: "prompt",
    model: "gpt-5-mini",
    instructions: "Use the available Work IQ tools to answer questions and perform tasks.",
    tools: [
      {
        type: "mcp",
        server_label: "toolbox",
        server_url: toolboxMcpUrl,
        require_approval: "never",
        project_connection_id: toolboxConnectionName,
      },
    ],
  });
  console.log(`Agent created (id: ${agent.id}, name: ${agent.name}, version: ${agent.version})`);

  const userInput = "What meetings do I have scheduled today?";
  const response = await openai.responses.create(
    { input: userInput },
    { body: { agent_reference: { name: agent.name, version: agent.version, type: "agent_reference" } } },
  );
  console.log(`Agent response: ${response.output_text}`);

  // Clean up the agent version so unused versions don't accumulate in the project.
  await project.agents.deleteVersion(agent.name, agent.version);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});