빠른 시작: JavaScript Claude 에이전트 SDK 샘플 에이전트 설정 및 실행

이 빠른 시작에서는 에이전트 365 도구, 알림, 관찰 가능성을 사용하여 작동하는 JavaScript Claude 에이전트를 설정하고 에이전트 플레이그라운드 및 Teams를 사용하여 에이전트를 테스트하는 방법을 안내합니다.

필수 구성 요소

Visual Studio Code를 사용하려는 경우 .NET이 설치되어 있어야 합니다. (.NET 8.0을 사용하는 것이 좋습니다.)
Node.js 버전 16 이상
Claude 에이전트 SDK 패키지 및 Anthropic API 키
에이전트 놀이터
NPM(노드 패키지 관리자)을 사용하여 패키지 설치
GitHub에 대한 액세스
기존 AI 에이전트 프로젝트입니다. 이 빠른 시작에서는 Microsoft 365 에이전트 도구 키트 갤러리(VS Code의 ATK)의 Claude 샘플 에이전트를 사용합니다.
A365 CLI
에이전트 ID 인증

Microsoft 365 에이전트 도구 키트에서 Claude + Node.js 샘플 설정

모든 것을 준비하려면 VS Code에 Microsoft 365 에이전트 도구 키트를 설치하고, 샘플 갤러리를 열고, 나중에 구성하고 실행할 수 있도록 Claude + Node.js 샘플을 로컬로 스캐폴드합니다. 아래 스크린샷은 흐름을 통해 이동할 때 예상되는 항목을 보여 줍니다.

Visual Studio Code에서 확장 패널(Ctrl+Shift+X)을 열고 Microsoft 365 에이전트 도구 키트를 검색한 다음 설치를 선택합니다.
VS Code 작업 모음에서 M365 에이전트 도구 키트 보기를 열고 샘플 보기를 선택합니다.
Claude + Node.js 샘플을 선택하고 만들기를 선택하고 프로젝트를 스캐폴드해야 하는 폴더(예C:\A365-Ignite-Demo: )를 선택하거나 만듭니다. 도구 키트는 하위 폴더(예: sample_agent)를 만들고 VS Code에서 엽니다.

스캐폴딩이 완료되면 실행 가능한 프로젝트가 있습니다. 다음 단계는 새 샘플 폴더 내에서 수행됩니다.

개발 환경 설치 및 구성

생성된 package.json 패키지에는 샘플에 필요한 패키지가 이미 나열되어 있으므로 모든 항목을 한 패스로 설치합니다.

npm install

설치 후 개발 서버를 시작하여 프로젝트가 빌드되고 실행되는지 확인합니다.

npm run dev

개발 서버는 샘플에 구성된 포트에서 수신 대기하며(localhost:3978 기본적으로) 에이전트 플레이그라운드 또는 CLI의 요청을 수락할 준비가 된 것입니다.

Microsoft 365 도구 추가(MCP 서버)

CLI에서 a365 개발 명령을 사용하여 MCP 서버를 탐색하고 관리할 수 있습니다 . 패키지는 @microsoft/agents-a365-tooling-extensions-claude 이러한 MCP 서버를 Claude 오케스트레이터에 연결하므로 에이전트 SDK는 Claude 에이전트 계획에 정의된 기술과 함께 Microsoft 365 도구를 인라인으로 호출할 수 있습니다.

MCP 서버를 사용하는 경우 다음을 수행할 수 있습니다.

사용할 수 있는 MCP 서버 검색
에이전트 구성에 하나 이상의 MCP 서버 추가
현재 구성된 MCP 서버 검토
더 이상 필요하지 않은 MCP 서버 제거

MCP 서버가 추가되면 에이전트의 도구 매니페스트가 확장되어 다음과 유사한 항목이 포함됩니다.

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

도구를 추가하고 관리하는 방법 알아보기

알림 구독 및 처리

샘플 에이전트는 모든 에이전트 365 알림을 사용하여 onAgentNotification("*") 구독하고 단일 처리기로 라우팅합니다. 이 처리기를 사용하면 에이전트가 직접 사용자 메시지뿐만 아니라 백그라운드 또는 시스템 이벤트에 반응할 수 있습니다.

에이전트에 알리는 방법 알아보기

다음 코드는 파일에서 알림을 구성하는 방법을 보여 있습니다 agent.ts .

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
}

가시성

이 코드 조각은 샘플에서 관찰 가능성을 사용하도록 설정하는 데 필요한 최소한의 변경 내용을 보여 줍니다. 에이전트 365 Observability SDK를 초기화하고 각 에이전트 호출 InferenceScope 을 래핑하도록 업데이트 src/client.ts 하여 입력, 출력 및 메타데이터를 자동으로 캡처할 수 있습니다.

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;
}

이 코드는 Node.js + Claude 샘플에 필요한 전체 관찰 가능성 설정입니다. 자리 표시자 메타데이터를 에이전트에 대해 이미 구성한 값으로 바꿉다. 관찰 가능성에 대해 자세히 알아보기

에이전트 테스트

필요한 환경 변수를 설정하고, 인증 모드를 선택하고, 에이전트를 로컬로 시작합니다. 에이전트를 게시하고 Teams 또는 Outlook과 같은 앱에서 사용하지 않으려면 Microsoft 365 테넌트를 사용하지 않고도 에이전트 플레이그라운드를 사용하여 모든 것을 엔드 투 엔드(end-to-end)로 테스트할 수 있습니다.

테스트 단계 개요

ANTHROPIC_API_KEY 샘플이 Claude와 통신할 .env 수 있도록 파일에 사용자 및 모델 설정을 추가합니다.
인증 방법 선택 로컬 개발의 경우 샘플은 에이전트 청사진에서 만든 값을 사용하여 에이전트 인증을 지원합니다.
에이전트를 로컬로 시작하여 에이전트 플레이그라운드와 같은 도구에 노출합니다.
에이전트 플레이그라운드를 사용하여 테넌트를 설정하거나 아무것도 배포하지 않고 메시지, 도구 및 알림을 테스트합니다.
실제 동작에 대한 준비가 되면 Microsoft 365 테넌트를 게시하고 Teams, Outlook 또는 기타 Microsoft 365 화면 내에서 에이전트를 테스트합니다.

테스트에 대해 자세히 알아보기

에이전트 게시

에이전트가 Teams 채팅, Outlook 메시지 또는 Word @mentions와 같은 실제 Microsoft 365 환경을 사용할 준비가 되면 Microsoft 365 테넌트에 게시합니다. 에이전트 365 CLI publish 명령은 패키징을 처리합니다. 매니페스트를 업데이트하고, 모든 항목을 번들로 묶고, 에이전트를 Microsoft 관리 센터에 업로드합니다.

게시하는 동안 업로드를 완료하기 전에 에이전트의 이름, 설명, 아이콘 및 버전을 검토하고 사용자 지정합니다. 게시되면 에이전트가 테넌트 내에서 검색 가능하고 설치 가능해집니다.

게시된 에이전트는 여기에서 볼 수 있습니다. https://admin.cloud.microsoft/#/agents/all

전체 워크플로 및 단계별 지침에 대해 자세히 알아보기

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-12-02