빠른 시작: 기본 에이전트 만들기 및 테스트

이 빠른 시작 가이드에서는 사용자가 보낸 메시지를 그대로 반환하는 사용자 지정 엔진 에이전트를 만드는 방법을 안내합니다.

필수 구성 요소

• Python 3.9 이상

  • Python을 설치하려면 https://www.python.org/downloads/ 페이지로 이동하여 사용 중인 운영 체제에 맞는 지침을 따르세요.
  • 버전을 확인하려면 터미널 창에서 python --version을 입력합니다.

• 원하는 코드 편집기. 이러한 지침은 Visual Studio Code를 사용합니다.

  Visual Studio Code를 사용하는 경우 Python 확장 프로그램을 설치해야 합니다

프로젝트를 초기화하고 SDK를 설치합니다

Python 프로젝트를 생성하고 요구 사항에 맞는 종속성을 설치합니다

1. 터미널을 열고 새 폴더를 생성합니다

   mkdir echo
   cd echo
   

2. 다음 명령을 사용하여 Visual Studio Code에서 해당 폴더를 엽니다.

   code .
   

3. 원하는 방법으로 가상 환경을 생성하고, Visual Studio Code 또는 터미널을 통해 이를 활성화하세요.

   Visual Studio Code를 사용하는 경우, Python 확장 프로그램이 설치된 상태에서 다음 단계를 따를 수 있습니다.

   1. F1을 누르고 Python: Create environment를 입력한 다음 Enter를 누릅니다.

      1. Venv환경를 선택하여 현재 작업 공간에서 .venv 가상 환경을 만듭니다.

      2. 가상 환경을 만들기 위해 Python 설치를 선택합니다.

         값은 다음과 같습니다.

         Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe

4. 에이전트 SDK 설치

   pip을 사용하여 다음 명령어로 microsoft-agents-hosting-aiohttp 패키지를 설치합니다.

   pip install microsoft-agents-hosting-aiohttp
   

서버 애플리케이션을 생성하고 요구 사항에 맞는 라이브러리를 가져옵니다

1. start_server.py라는 이름의 파일을 생성하고, 다음 코드를 복사하여 붙여넣습니다.

   # start_server.py
   from os import environ
   from microsoft_agents.hosting.core import AgentApplication, AgentAuthConfiguration
   from microsoft_agents.hosting.aiohttp import (
      start_agent_process,
      jwt_authorization_middleware,
      CloudAdapter,
   )
   from aiohttp.web import Request, Response, Application, run_app
   
   
   def start_server(
      agent_application: AgentApplication, auth_configuration: AgentAuthConfiguration
   ):
      async def entry_point(req: Request) -> Response:
         agent: AgentApplication = req.app["agent_app"]
         adapter: CloudAdapter = req.app["adapter"]
         return await start_agent_process(
               req,
               agent,
               adapter,
         )
   
      APP = Application(middlewares=[jwt_authorization_middleware])
      APP.router.add_post("/api/messages", entry_point)
      APP.router.add_get("/api/messages", lambda _: Response(status=200))
      APP["agent_configuration"] = auth_configuration
      APP["agent_app"] = agent_application
      APP["adapter"] = agent_application.adapter
   
      try:
         run_app(APP, host="localhost", port=environ.get("PORT", 3978))
      except Exception as error:
         raise error
   

   이 코드는 다음 파일에서 사용할 start_server 함수를 정의합니다.

2. 동일한 디렉터리에서 app.py라는 이름의 파일을 생성하고 다음 코드를 입력합니다.

   # app.py
   from microsoft_agents.hosting.core import (
      AgentApplication,
      TurnState,
      TurnContext,
      MemoryStorage,
   )
   from microsoft_agents.hosting.aiohttp import CloudAdapter
   from start_server import start_server
   

AgentApplication으로 에이전트 인스턴스를 생성합니다.

app.py에서 다음 코드를 추가하여 AGENT_APP를 AgentApplication의 인스턴스로 생성하고, 세 가지 이벤트에 응답하기 위한 세 가지 경로를 구현합니다.

• 대화 업데이트
• 메시지 /help
• 기타 활동

AGENT_APP = AgentApplication[TurnState](
    storage=MemoryStorage(), adapter=CloudAdapter()
)

async def _help(context: TurnContext, _: TurnState):
    await context.send_activity(
        "Welcome to the Echo Agent sample 🚀. "
        "Type /help for help or send a message to see the echo feature in action."
    )

AGENT_APP.conversation_update("membersAdded")(_help)

AGENT_APP.message("/help")(_help)


@AGENT_APP.activity("message")
async def on_message(context: TurnContext, _):
    await context.send_activity(f"you said: {context.activity.text}")

localhost:3978에서 수신 대기하도록 웹 서버를 시작합니다

app.py 끝부분에서 start_server 명령을 사용하여 웹 서버를 시작합니다.

if __name__ == "__main__":
    try:
        start_server(AGENT_APP, None)
    except Exception as error:
        raise error

에이전트를 로컬에서 익명 모드로 실행하기

터미널에서 다음 명령을 실행합니다.

python app.py

터미널에 다음과 같은 결과가 표시되어야 합니다.

======== Running on http://localhost:3978 ========
(Press CTRL+C to quit)

로컬에서 에이전트 테스트하기

1. (에이전트를 계속 실행 상태로 유지하기 위해) 다른 터미널에서 다음 명령을 사용하여 Microsoft 365 Agents Playground를 설치합니다.

   npm install -g @microsoft/teams-app-test-tool
   

   참고

   Microsoft 365 Agents Playground는 pip를 통해 설치할 수 없으므로 이 명령은 npm을 사용합니다.

   터미널에 다음과 같은 출력이 나타납니다.

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 이 명령어로 테스트 도구를 실행하여 에이전트와 상호작용하세요.

   teamsapptester
   

   터미널에 다음과 같은 출력이 나타납니다.

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

teamsapptester 명령어는 기본 브라우저를 열어 에이전트에 연결합니다.

이제 임의의 메시지를 보내 에코 응답을 확인하거나, 메시지 /help를 보내 해당 메시지가 _help 핸들러로 어떻게 라우팅되는지 확인할 수 있습니다.

이 빠른 시작 가이드에서는 사용자가 보낸 메시지를 그대로 반환하는 사용자 지정 엔진 에이전트를 만드는 방법을 안내합니다.

필수 구성 요소

• Node.js v22 이상

  • Node.js 설치하려면 nodejs.org 이동하여 운영 체제에 대한 지침을 따릅니다.
  • 버전을 확인하려면 터미널 창에서 node --version을 입력합니다.

• 원하는 코드 편집기. 이러한 지침은 Visual Studio Code를 사용합니다.

프로젝트를 초기화하고 SDK를 설치합니다

npm를 사용하여 Node.js 프로젝트를 초기화하고 package.json을 생성하며 필요한 의존성을 설치합니다

1. 터미널을 열고 새 폴더를 생성합니다

   mkdir echo
   cd echo
   

2. node.js 프로젝트 초기화

   npm init -y
   

3. 에이전트 SDK 설치

   npm install @microsoft/agents-hosting-express
   

4. 다음 명령어로 Visual Studio Code에서 폴더를 엽니다.

   code .
   

필요한 라이브러리 가져오기

파일을 index.mjs 생성한 후, 아래 NPM 패키지들을 애플리케이션 코드에 임포트합니다.

• @microsoft/에이전트 호스팅
• @microsoft/agents-hosting-express

// index.mjs
import { startServer } from '@microsoft/agents-hosting-express'
import { AgentApplication, MemoryStorage } from '@microsoft/agents-hosting'

EchoAgent를 AgentApplication 클래스로 구현하세요

index.mjs에 아래 코드를 추가하여 EchoAgentAgentApplication를 확장한 것을 생성하고, 세 가지 이벤트에 반응하는 세 개의 라우트를 구현하세요.

• 대화 업데이트
• 메시지 /help
• 기타 활동

class EchoAgent extends AgentApplication {
  constructor (storage) {
    super({ storage })

    this.onConversationUpdate('membersAdded', this._help)
    this.onMessage('/help', this._help)
    this.onActivity('message', this._echo)
  }

  _help = async context => 
    await context.sendActivity(`Welcome to the Echo Agent sample 🚀. 
      Type /help for help or send a message to see the echo feature in action.`)

  _echo = async (context, state) => {
    let counter= state.getValue('conversation.counter') || 0
    await context.sendActivity(`[${counter++}]You said: ${context.activity.text}`)
    state.setValue('conversation.counter', counter)
  }
}

localhost:3978에서 수신 대기하도록 웹 서버를 시작합니다

index.mjs의 마지막 부분에서 MemoryStorage를 턴 상태 저장소로 사용하는 Express 기반 startServer를 사용하여 웹 서버를 시작하세요.

startServer(new EchoAgent(new MemoryStorage()))

에이전트를 로컬에서 익명 모드로 실행하기

터미널에서 다음 명령을 실행합니다.

node index.mjs

터미널에서 다음과 같이 출력됩니다.

Server listening to port 3978 on sdk 0.6.18 for appId undefined debug undefined

로컬에서 에이전트 테스트하기

1. (에이전트를 계속 실행 상태로 유지하기 위해) 다른 터미널에서 다음 명령을 사용하여 Microsoft 365 Agents Playground를 설치합니다.

   npm install -D @microsoft/teams-app-test-tool
   

   터미널에 다음과 같은 출력이 나타납니다.

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 이 명령어로 테스트 도구를 실행하여 에이전트와 상호작용하세요.

   node_modules/.bin/teamsapptester
   

   터미널에 다음과 같은 출력이 나타납니다.

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

teamsapptester 명령어는 기본 브라우저를 열어 에이전트에 연결합니다.

이제 임의의 메시지를 보내 에코 응답을 확인하거나, 메시지 /help를 보내 해당 메시지가 _help 핸들러로 어떻게 라우팅되는지 확인할 수 있습니다.

이 빠른 시작 가이드에서는 사용자가 보낸 메시지를 그대로 반환하는 사용자 지정 엔진 에이전트를 만드는 방법을 안내합니다.

필수 구성 요소

• .NET 8.0 SDK 이상

  • .NET SDK를 설치하려면 dotnet.microsoft.com으로 이동하여 운영체제별 지침을 따르세요.
  • 버전을 확인하려면 터미널 창에서 dotnet --version을 입력합니다.

• 원하는 코드 편집기. 이러한 지침은 Visual Studio Code를 사용합니다.

프로젝트를 초기화하고 SDK를 설치합니다

dotnet를 사용하여 새 웹 프로젝트를 만들고 필요한 종속성을 설치합니다.

1. 터미널을 열고 새 폴더를 생성합니다

   mkdir echo
   cd echo
   

2. .NET 프로젝트 초기화

   dotnet new web
   

3. 에이전트 SDK 설치

   dotnet add package Microsoft.Agents.Hosting.AspNetCore
   

4. 다음 명령을 사용하여 Visual Studio Code에서 해당 폴더를 엽니다.

   code .
   

필요한 라이브러리 가져오기

Program.cs에서 기존 내용을 교체하고, SDK 패키지를 애플리케이션 코드에 임포트하기 위한 다음 using 구문을 추가합니다.

// Program.cs
using Microsoft.Agents.Builder;
using Microsoft.Agents.Builder.App;
using Microsoft.Agents.Builder.State;
using Microsoft.Agents.Core.Models;
using Microsoft.Agents.Hosting.AspNetCore;
using Microsoft.Agents.Storage;
using Microsoft.AspNetCore.Builder;

EchoAgent를 AgentApplication 클래스로 구현하세요

Program.cs에서 using 문 다음에, EchoAgent를 AgentApplication로 확장하여 생성하고, 이벤트에 응답할 경로를 구현하는 다음 코드를 추가하세요.

• 대화 업데이트
• 기타 모든 활동

public class EchoAgent : AgentApplication
{
   public EchoAgent(AgentApplicationOptions options) : base(options)
   {
      OnConversationUpdate(ConversationUpdateEvents.MembersAdded, WelcomeMessageAsync);
      OnActivity(ActivityTypes.Message, OnMessageAsync, rank: RouteRank.Last);
   }

   private async Task WelcomeMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
        foreach (ChannelAccount member in turnContext.Activity.MembersAdded)
        {
            if (member.Id != turnContext.Activity.Recipient.Id)
            {
                await turnContext.SendActivityAsync(MessageFactory.Text("Hello and Welcome!"), cancellationToken);
            }
        }
    }

   private async Task OnMessageAsync(ITurnContext turnContext, ITurnState turnState, CancellationToken cancellationToken)
   {
      await turnContext.SendActivityAsync($"You said: {turnContext.Activity.Text}", cancellationToken: cancellationToken);
   }
}

웹 서버를 설정하고 에이전트 애플리케이션을 등록하세요

Program.cs에서 using 구문 다음에, 웹 호스트를 구성하고, 에이전트를 등록하며, /api/messages 엔드포인트를 매핑하는 다음 코드를 추가하세요.

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddHttpClient();
builder.AddAgentApplicationOptions();
builder.AddAgent<EchoAgent>();
builder.Services.AddSingleton<IStorage, MemoryStorage>();

var app = builder.Build();

app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

app.Run();

웹 서버가 localhost:3978에서 연결 요청을 수신하도록 설정하세요

launchSettings.json에서 applicationURL를 http://localhost:3978로 업데이트하여 앱이 올바른 포트에서 요청을 수신하도록 하세요.

에이전트를 로컬에서 익명 모드로 실행하기

터미널에서 다음 명령을 실행합니다.

dotnet run

터미널에 다음과 같은 출력이 나타납니다.

info: Microsoft.Hosting.Lifetime[14]
      Now listening on: http://localhost:3978

로컬에서 에이전트 테스트하기

1. 다른 터미널에서 (에이전트를 계속 실행하기 위해) 다음 명령어로 Microsoft 365 Agents Playground를 설치하세요.

   npm install -g @microsoft/teams-app-test-tool
   

   참고

   이 명령어는 Microsoft 365 Agent플레이그라운드가 npm 패키지로 배포되기 때문에 npm을 사용합니다.

   터미널에 다음과 같은 출력이 나타납니다.

   added 1 package, and audited 130 packages in 1s
   
   19 packages are looking for funding
   run `npm fund` for details
   
   found 0 vulnerabilities
   

2. 이 명령어로 테스트 도구를 실행하여 에이전트와 상호작용하세요.

   teamsapptester
   

   터미널에 다음과 같은 출력이 나타납니다.

   Telemetry: agents-playground-cli/serverStart {"cleanProperties":{"options":"{\"configFileOptions\":{\"path\":\"<REDACTED: user-file-path>\"},\"appConfig\":{},\"port\":56150,\"disableTelemetry\":false}"}}
   
   Telemetry: agents-playground-cli/cliStart {"cleanProperties":{"isExec":"false","argv":"<REDACTED: user-file-path>,<REDACTED: user-file-path>"}}
   
   Listening on 56150
   Microsoft 365 Agents Playground is being launched for you to debug the app: http://localhost:56150
   started web socket client
   started web socket client
   Waiting for connection of endpoint: http://127.0.0.1:3978/api/messages
   waiting for 1 resources: http://127.0.0.1:3978/api/messages
   wait-on(37568) complete
   Telemetry: agents-playground-server/getConfig {"cleanProperties":{"internalConfig":"{\"locale\":\"en-US\",\"localTimezone\":\"America/Los_Angeles\",\"channelId\":\"msteams\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"installationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   
   Telemetry: agents-playground-server/sendActivity {"cleanProperties":{"activityType":"conversationUpdate","conversationId":"5305bb42-59c9-4a4c-a2b6-e7a8f4162ede","headers":"{\"x-ms-agents-playground\":\"true\"}"}}
   

teamsapptester 명령어는 기본 브라우저를 열어 에이전트에 연결합니다.

텍스트 입력창에 아무 메시지나 입력하여 전송하면 에코 응답을 확인할 수 있습니다.

다음 단계

• GitHub에서 에이전트 SDK 샘플을 확인해보세요
• 활동과 활동 관련 작업에 대해 더 알아보세요
• 클라이언트 측에서 응답할 수 있는 AgentApplication 이벤트를 확인해 보세요
• 클라이언트에게 보낼 수 있는 TurnContext 이벤트를 검토하세요
• 에이전트 SDK와 함께 사용할 Azure Bot 리소스 프로비저닝
• OAuth를 사용하도록 .NET 에이전트 구성

이미 Microsoft 365 Agent 도구 키트를 사용 중이라면 에이전트 플레이그라운드는 기본적으로 이용하실 수 있습니다. 툴킷을 처음 사용하신다면 다음 가이드들 중 하나를 참조하시기 바랍니다.

• Microsoft 365 Agent 도구 키트를 사용하여 Visual Studio에서 .NET 에이전트 만들기
• Microsoft 365 Agent 도구 키트를 사용하여 Visual Studio Code에서 JavaScript 에이전트 만들기