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

이 빠른 시작에서는 보내는 메시지와 함께 다시 회신하는 사용자 지정 엔진 에이전트 를 만드는 방법을 안내합니다.

필수 조건

Python 3.9 이상.
- Python을 설치하려면 다음으로 https://www.python.org/downloads/이동하여 운영 체제에 대한 지침을 따릅니다.
- 버전을 확인하려면 터미널 창에서 .python --version
선택한 코드 편집기입니다. 이러한 지침은 Visual Studio Code를 사용합니다.

Visual Studio Code를 사용하는 경우 Python 확장을 설치합니다.

프로젝트 초기화 및 SDK 설치

Python 프로젝트를 만들고 필요한 종속성을 설치합니다.

터미널을 열고 새 폴더 만들기
```
mkdir echo
cd echo
```
다음 명령을 사용하여 Visual Studio Code를 사용하여 폴더를 엽니다.
```
code .
```
선택한 방법으로 가상 환경을 만들고 Visual Studio Code 또는 터미널에서 활성화합니다.

Visual Studio Code를 사용하는 경우 Python 확장 이 설치된 상태에서 이러한 단계를 사용할 수 있습니다.
1. F1 키를 누르고 입력Python: Create environment한 다음 Enter 키를 누릅니다.
  1. 현재 작업 영역에서 가상 환경을 만들 려면 .venv를 선택합니다.
  2. Python 설치를 선택하여 가상 환경을 만듭니다.
    
    값은 다음과 같을 수 있습니다.
    
    Python 1.13.6 ~\AppData\Local\Programs\Python\Python313\python.exe
에이전트 SDK 설치

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

서버 애플리케이션 만들기 및 필요한 라이브러리 가져오기

이름이 지정된 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 다음 파일에서 사용할 함수를 정의합니다.

동일한 디렉터리에서 다음 코드로 명명된 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)

에이전트를 로컬 환경에서 테스트

다른 터미널에서(에이전트를 계속 실행하려면) 다음 명령을 사용하여 Microsoft 365 에이전트 플레이그라운드 를 설치합니다.
```
npm install -g @microsoft/teams-app-test-tool
```
비고

이 명령은 pip를 사용하여 Microsoft 365 에이전트 플레이그라운드를 사용할 수 없으므로 npm을 사용합니다.

터미널은 다음과 같은 항목을 반환해야 합니다.
```
added 1 package, and audited 130 packages in 1s

19 packages are looking for funding
run `npm fund` for details

found 0 vulnerabilities
```

테스트 도구를 실행하여 다음 명령을 사용하여 에이전트와 상호 작용합니다.

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 설치

package.json 만들고 필요한 종속성을 설치하여 node.js 프로젝트를 초기화하는 데 사용합니다 npm .

터미널을 열고 새 폴더 만들기
```
mkdir echo
cd echo
```
node.js 프로젝트 초기화
```
npm init -y
```

에이전트 SDK 설치

npm install @microsoft/agents-hosting-express

다음 명령을 사용하여 Visual Studio Code를 사용하여 폴더를 엽니다.
```
code .
```

필수 라이브러리 가져오기

파일을 index.mjs 만들고 다음 NPM 패키지를 애플리케이션 코드로 가져옵니다.

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

AgentApplication으로 EchoAgent 구현

에서 index.mjs다음 코드를 EchoAgent 추가하여 AgentApplication을 확장하고 세 가지 이벤트에 응답하는 세 가지 경로를 구현합니다.

대화 업데이트
메시지 /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.mjsstartServer를 사용하여 웹 서버를 시작하고, Express를 기반으로 MemoryStorage를 턴 상태 스토리지로 사용합니다.

startServer(new EchoAgent(new MemoryStorage()))

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

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

node index.mjs

터미널은 다음을 반환해야 합니다.

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

에이전트를 로컬 환경에서 테스트

다른 터미널에서(에이전트를 계속 실행하려면) 다음 명령을 사용하여 Microsoft 365 에이전트 플레이그라운드 를 설치합니다.
```
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
```

테스트 도구를 실행하여 다음 명령을 사용하여 에이전트와 상호 작용합니다.

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 .

터미널을 열고 새 폴더 만들기
```
mkdir echo
cd echo
```
.NET 프로젝트 초기화
```
dotnet new web
```

에이전트 SDK 설치

dotnet add package Microsoft.Agents.Hosting.AspNetCore

다음 명령을 사용하여 Visual Studio Code를 사용하여 폴더를 엽니다.
```
code .
```

필수 라이브러리 가져오기

에서 Program.cs기존 콘텐츠를 바꾸고 다음 using 문을 추가하여 SDK 패키지를 애플리케이션 코드로 가져옵니다.

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

AgentApplication으로 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

에이전트를 로컬 환경에서 테스트

다른 터미널에서(에이전트를 계속 실행하려면) 다음 명령을 사용하여 Microsoft 365 에이전트 플레이그라운드 를 설치합니다.
```
npm install -g @microsoft/teams-app-test-tool
```
비고

이 명령은 Microsoft 365 에이전트 플레이그라운드가 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
```

테스트 도구를 실행하여 다음 명령을 사용하여 에이전트와 상호 작용합니다.

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 명령은 기본 브라우저를 열고 에이전트에 연결합니다.

에이전트 플레이그라운드에 있는 내 에이전트

텍스트 입력란에 메시지를 입력하고 보내면 에코 회신을 볼 수 있습니다.

다음 단계

이미 Microsoft 365 에이전트 도구 키트를 사용하고 있는 경우 에이전트 플레이그라운드를 기본적으로 사용할 수 있습니다. 도구 키트를 시작하려면 다음 가이드 중 하나를 사용할 수 있습니다.

피드백

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

Last updated on 2026-03-14

다음을 통해 공유

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

필수 조건

프로젝트 초기화 및 SDK 설치

서버 애플리케이션 만들기 및 필요한 라이브러리 가져오기

에이전트 인스턴스를 AgentApplication으로 만들기

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

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

에이전트를 로컬 환경에서 테스트

필수 조건

프로젝트 초기화 및 SDK 설치

필수 라이브러리 가져오기

AgentApplication으로 EchoAgent 구현

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

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

에이전트를 로컬 환경에서 테스트

필수 조건

프로젝트 초기화 및 SDK 설치

필수 라이브러리 가져오기

AgentApplication으로 EchoAgent 구현

웹 서버 설정 및 에이전트 애플리케이션 등록

localhost:3978에서 수신 대기하도록 웹 서버 설정

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

에이전트를 로컬 환경에서 테스트

다음 단계

피드백

추가 리소스