Edit

Work IQ API overview (preview)

The Work IQ API enables developers to build agentic and AI-powered applications that securely reason over Microsoft 365 data while preserving existing permissions, compliance, and governance controls.

Work IQ provides multiple protocols to interact with agents - Agent-to-Agent (A2A), Model Context Protocol (MCP), and REST - so you can choose the protocol that best fits your application or agent architecture.

By accessing or using the Microsoft Work IQ APIs, you're agreeing to the Microsoft Work IQ APIs Terms of Use (preview).

What is Work IQ?

Work IQ is a workplace intelligence layer that combines Microsoft 365 data with contextual understanding so agents can reason over work and take action. For a full overview of Work IQ capabilities, see Work IQ overview.

Why use Work IQ?

Traditional AI integrations often require building custom pipelines to extract, index, and secure enterprise data. Work IQ eliminates this complexity by providing:

  • Secure enterprise grounding: Access to Microsoft 365 data is automatically permission-trimmed and policy-enforced.
  • Flexible interaction models: Choose from conversational APIs, agent delegation, or tool-based access.
  • Reduced operational overhead: No need to manage vector stores, data sync jobs, or custom compliance enforcement.

Supported protocols

Work IQ supports the following protocols:

Protocol Description Typical scenarios
A2A Structured agent-to-agent communication Multi-agent systems, delegation
Local MCP Tool-based context access IDEs, CLIs, AI coding assistants
Remote MCP Tool-based context access IDEs, CLIs, AI coding assistants
REST Conversational, request/response API Service-hosted agents, orchestrators

Supported functionality

Work IQ can reason over:

  • Email messages
  • Meetings and calendar data
  • Documents in OneDrive and SharePoint
  • Microsoft Teams messages
  • People and organizational context
  • Enterprise search results

Choose a protocol

Use the guide below to select the right protocol.

Note

The following table contains recommendations for the best suited protocol for specific scenarios, not strict rules. Use the protocol that works best for you.

A2A REST API (coming soon) MCP
Use when Another agent needs to delegate a task to Work IQ and get results back You're building an app or service that calls Work IQ programmatically An AI assistant needs to invoke Work IQ as a tool for the user
Caller Another agent Your app or backend An LLM-based client
Example "Our ops agent asks Work IQ to investigate a regression." "My web app sends a question to Work IQ and renders the reply." "A user asks Copilot a question and it calls Work IQ to answer."

API examples

Agent-to-Agent (A2A) protocol

Use A2A for agent collaboration and delegation, where agents operate autonomously and exchange structured tasks instead of simple API calls. Work IQ supports both A2A v1.0 and v0.3, dispatched via the A2A-Version request header.

Example request — sync (SendMessage)

POST https://workiq.svc.cloud.microsoft/a2a/
Authorization: Bearer {access-token}
Content-Type: application/json
A2A-Version: 1.0

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid>",
      "parts": [
        {
          "text": "What meetings do I have today?"
        }
      ],
      "metadata": {
        "Location": {
          "timeZoneOffset": -480,
          "timeZone": "America/Los_Angeles"
        }
      }
    }
  }
}

Note

The A2A-Version: 1.0 header is required to use v1.0 method names (SendMessage). Omitting it defaults to v0.3.

Example response

{
  "jsonrpc": "2.0",
  "id": "<request-guid>",
  "result": {
    "task": {
      "id": "<task-id>",
      "contextId": "ctx-1",
      "status": {
        "state": "TASK_STATE_COMPLETED"
      },
      "artifacts": [
        {
          "artifactId": "<artifact-id>",
          "name": "Answer",
          "parts": [
            {
              "text": "Today you have: 9 AM standup, 11 AM review with Dana, 2 PM customer call."
            }
          ]
        }
      ]
    }
  }
}

Multi-turn conversations

Pass the contextId from the previous response in the next message:

{
  "jsonrpc": "2.0",
  "id": "<request-guid-2>",
  "method": "SendMessage",
  "params": {
    "message": {
      "role": "ROLE_USER",
      "messageId": "<message-guid-2>",
      "contextId": "ctx-1",
      "parts": [
        {
          "text": "Tell me more about the 2 PM customer call."
        }
      ]
    }
  }
}

Key characteristics

  • JSON-RPC envelope required (jsonrpc, id, method, params)
  • POST to base URL — method name is inside the body, not the URL path
  • Supports synchronous (SendMessage)
  • Multi-turn via contextId
  • Location metadata required for time-sensitive queries

Remote Model Context Protocol (MCP)

Use remote MCP to expose Microsoft 365 work context as tools for AI assistants running in developer environments.

Local MCP

Install the Microsoft Work IQ CLI (preview) and configure it as a local MCP server.

▶ See it in action in the Interactive Demo (preview)

▶ See it in action in the Interactive Demo (preview)

Example MCP server configuration

{
  "workiq": {
    "type": "stdio",
    "command": "workiq",
    "args": ["mcp"]
  }
}

Example agent-based query

Prompt

Summarize recent discussions about project risks.

Conceptual MCP invocation
{
  "tool": "workiq.search",
  "arguments": {
    "query": "project risks",
    "source": "teams"
  }
}
Result
{
  "results": [
    {
      "summary": "Recent discussions highlighted timeline and dependency risks."
    }
  ]
}

Key characteristics

  • Optimized for IDEs and CLIs
  • Context pulled dynamically when needed
  • Reduces manual prompt construction
  • Single server with consolidated tools (coming soon)

Authentication and security

Work IQ uses Microsoft Entra ID delegated authentication.

  • Requests run in the context of the signed-in user
  • On-behalf-of (OBO) flows are supported
  • Application-only authentication is not supported
  • Microsoft 365 permissions, sensitivity labels, and compliance policies are enforced automatically

Path forward for new development

Work IQ is the recommended foundation for new agentic and AI-powered applications on Microsoft 365 data. Build new development on Work IQ APIs to take advantage of unified protocols, integrated governance, and continued investment.

Related content

  • Last updated on