Share via

Quickstart: Set up and run the JavaScript Claude Agent SDK sample agent

In this Quickstart, walk through setting up a working JavaScript Claude agent using Agent 365 tooling, notifications, observability, and testing the agent using Agents Playground and Teams.

Prerequisites

Set up the Claude + Node.js sample from the Microsoft 365 Agents Toolkit

To get everything ready, install the Microsoft 365 Agents Toolkit in VS Code, open the sample gallery, and scaffold the Claude + Node.js sample locally so you can configure and run it later. The screenshots below show what to expect as you move through the flow.

  1. In Visual Studio Code, open the Extensions panel (Ctrl+Shift+X), search for Microsoft 365 Agents Toolkit, and select Install.

    Screenshot of Extensions Marketplace search for Agents Toolkit.

  2. Open the M365 Agents Toolkit view from the VS Code Activity Bar and choose View Samples.

    Screenshot of Toolkit Welcome View with Build a Declarative Agent, Create a New Agent or App, and View Samples options.

  3. Select the Claude + Node.js sample, choose Create, and pick (or create) the folder where the project should be scaffolded (for example, C:\A365-Ignite-Demo). The toolkit creates a subfolder (such as sample_agent) and opens it in VS Code.

    Screenshot of Agent toolkit samples. Claude sample focused.

Once scaffolding completes you have a runnable project. The next steps happen inside the new sample folder.

Install dependencies and configure the environment

The generated package.json already lists the packages the sample needs, so install everything in one pass:

npm install

After installation, verify the project builds and runs by starting the dev server

npm run dev

The dev server listens on the port configured in the sample (localhost:3978 by default) and is ready to accept requests from Agents Playground or the CLI.

Add Microsoft 365 tools (MCP servers)

You can explore and manage MCP servers using the a365 develop commands in the CLI. The @microsoft/agents-a365-tooling-extensions-claude package wires these MCP servers into your Claude orchestrator so the Agent SDK can call Microsoft 365 tools inline with the skills defined in your Claude agent plan.

When working with MCP servers, you can:

  • Discover which MCP servers are available for use
  • Add one or more MCP servers to your agent's configuration
  • Review the MCP servers currently configured
  • Remove MCP servers you no longer need

After MCP servers are added, your agent's tooling manifest expands to include entries similar to:

{
  "mcpServers": [
    {
      "mcpServerName": "mcp_MailTools",
      "mcpServerUniqueName": "mcp_MailTools",
      "scope": "McpServers.Mail.All",
      "audience": "api://00001111-aaaa-2222-bbbb-3333cccc4444"
    }
  ]
}

Learn how to add and manage tools

Notification subscription and handling

The sample agent subscribes to all Agent 365 notifications using onAgentNotification("*") and routes them to a single handler. This handler allows the agent to react to background or system events, not just direct user messages.

Learn how to notify agents

The following code shows how notification is configured in the agent.ts file.

constructor() {
  super();

  this.onAgentNotification("agents:*", async (context, state, activity) => {
    await this.handleAgentNotificationActivity(context, state, activity);
  });
}

async handleAgentNotificationActivity(context, state, activity) {
  await context.sendActivity("Received an AgentNotification!");

  // Add custom handling here
}

Observability

This snippet shows the minimal changes needed to enable observability in the sample. Update src/client.ts to initialize the Agent 365 Observability SDK and wrap each agent invocation in an InferenceScope so inputs, outputs, and metadata can be captured automatically.

import {
  InferenceOperationType,
  InferenceScope,
  ObservabilityManager
} from '@microsoft/agents-a365-observability';

const sdk = ObservabilityManager.configure(b =>
  b.withService('<service-name>', '<version>')
);

sdk.start();

async invokeAgentWithScope(prompt: string) {
  const scope = InferenceScope.start(
    {
      operationName: InferenceOperationType.CHAT,
      model: '<llm-name>'
    },
    {
      agentId: '<agent-id>',
      agentName: '<agent-name>',
      conversationId: '<conv-id>'
    },
    { tenantId: '<tenant-id>' }
  );

  const response = await this.invokeAgent(prompt);
  scope?.recordInputMessages([prompt]);
  scope?.recordOutputMessages([response]);
  scope?.recordResponseId(`resp-${Date.now()}`);
  return response;
}

This code is the full observability setup required for the Node.js + Claude sample. Replace the placeholder metadata with the values you already configured for the agent. Learn more about observability

Test your agent

Set the required environment variables, select an authentication mode, and start the agent locally. You can test everything end-to-end with Agents Playground without needing a Microsoft 365 tenant unless you want to publish the agent and use it in apps like Teams or Outlook.

Testing steps overview

  • Add your ANTHROPIC_API_KEY and model settings to a .env file so the sample can talk to Claude.
  • Choose your authentication mode. For local development, the sample supports Agentic Authentication using values created from your Agent Blueprint.
  • Start the agent locally, which exposes it to tools like the Agents Playground.
  • Use Agents Playground to test messages, tools, and notifications without setting up a tenant or deploying anything.
  • When you're ready for real-world behavior, publish a Microsoft 365 tenant and test the agent inside Teams, Outlook, or other Microsoft 365 surfaces.

Learn more about testing

Publish your agent

When your agent is ready for actual Microsoft 365 experiences like Teams chats, Outlook messages, or Word @mentions, you publish it to a Microsoft 365 tenant. The Agent 365 CLI publish command handles the packaging: it updates your manifest, bundles everything, and uploads the agent to the Microsoft Admin Center.

During publishing, review and customize the agent's name, description, icons, and version before completing the upload. Once published, your agent becomes discoverable and installable inside the tenant.

You can view published agents here: https://admin.cloud.microsoft/#/agents/all

Learn more about the full workflow and step-by-step instructions

  • Last updated on