Sample clients for the Work IQ API — Microsoft's AI-native interface to Microsoft 365 work intelligence.
| Sample | Language | Platform | Protocol | Description |
|---|---|---|---|---|
| dotnet/a2a/ | C# | Windows, macOS, Linux | A2A | Interactive agent session using the A2A protocol over JSON-RPC |
| dotnet/a2a-raw/ | C# | Windows, macOS, Linux | A2A | Same, but with raw HttpClient + JSON (no A2A SDK) |
| dotnet/rest/ | C# | Windows, macOS, Linux | REST | Interactive chat using the Copilot Chat API |
| rust/a2a/ | Rust | Windows, macOS, Linux | A2A | Interactive agent session with MSAL auth and token caching |
| swift/a2a/ | Swift | iOS/iPadOS (macOS to build) | A2A | SwiftUI chat app for Work IQ |
All samples target the Work IQ Gateway (workiq.svc.cloud.microsoft) — the dedicated entry point for Work IQ. Token audience: api://workiq.svc.cloud.microsoft; delegated scope: WorkIQAgent.Ask.
- Microsoft 365 Copilot license on the test user (license propagation can take 15–30 minutes after assignment).
- Entra app registration configured in your tenant — this is a one-time setup per tenant. Details below.
- Your language toolchain:
- dotnet/ samples: .NET 8.0 SDK or later
- rust/ samples: Rust toolchain (stable)
- swift/ samples: Xcode 26+ (macOS only)
You (or your tenant admin) must create an Entra app registration with specific permissions, redirect URIs, and consent. This is a ~5-minute task.
-
If you're the admin — from the repo root:
# Bash / WSL / macOS / Linux scripts/admin-setup.sh# PowerShell scripts\admin-setup.ps1
See
ADMIN_SETUP.mdfor all flags and the manual CLI / portal paths. -
If you're not the admin — hand
ADMIN_SETUP.mdto them. They'll give you back an App ID and Tenant ID.
After setup you'll have two values: APP_ID and TENANT_ID. Pass them to any sample via --appid and --tenant.
All samples support multiple authentication methods. Choose the one that fits your platform.
Uses the Windows broker for silent SSO. A browser-less sign-in popup appears on first use; subsequent calls in the same process are silent. Across dotnet run invocations you'll be re-prompted (the samples don't persist MSAL state across processes by default).
cd dotnet/a2a
dotnet run -- --token WAM --appid <APP_ID> --tenant <TENANT_ID>Note: WAM is only available on Windows. On macOS and Linux, MSAL falls back to an interactive browser sign-in using the
http://localhostredirect URI — same command works.
The Rust CLI tries silent → broker (macOS Enterprise SSO / Windows WAM) → browser PKCE → device code, in that order. The Swift app uses MSAL silent + interactive (system browser) on iOS.
cd rust/a2a
cargo run -- --appid <APP_ID>Acquire a token externally (e.g. via your own MSAL code) and pass it directly:
dotnet run -- --token "<SOME_TOKEN>"| Symptom | Likely cause | Fix |
|---|---|---|
MsalClientException: window_handle_required |
Running dotnet run from a context where the console window handle can't be resolved (e.g., piped stdin, some non-interactive shells) |
Run from an interactive terminal, or use --token <jwt> with a pre-obtained token |
WAM_provider_error 3399614466 / IncorrectConfiguration |
App registration missing the WAM broker redirect URI ms-appx-web://microsoft.aad.brokerplugin/{appId} |
Ask admin to re-run setup (or add that redirect URI manually). See ADMIN_SETUP.md. |
| Same error, but redirect URI is present | Single-tenant app + /common authority mismatch |
Pass --tenant <TENANT_ID> so MSAL uses the tenant-specific authority |
403 Forbidden without a scope message |
User is missing the Microsoft 365 Copilot license | Assign the license; wait 15–30 min for propagation |
400 AuthenticationError: Error authenticating with resource |
Gateway rejected the downstream auth exchange (e.g., OBO against an unconfigured downstream service) | Check the request-id in the response headers against the gateway's logs |
WAM re-prompts for password on every dotnet run |
MSAL in-process cache doesn't persist across processes | Expected today. A future update may add an opt-in persistent cache. |
AADSTS65001: consent required |
Admin hasn't consented to the required permissions | Ask admin to run admin-consent (step 6 of the setup) |
401 Unauthorized |
Token audience mismatch | Ensure the token aud is fdcc1f02-... / api://workiq.svc.cloud.microsoft |
| Empty or degraded responses | License just assigned, index not ready | Wait 15–30 minutes after license assignment |
- Work IQ overview
- A2A protocol specification
- MSAL.NET documentation
ADMIN_SETUP.md— detailed admin setup guidescripts/admin-setup.sh/scripts/admin-setup.ps1— unified app-registration scripts
