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

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

필수 조건

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 되는 방식을 확인할 수 있습니다.

다음 단계

에이전트 SDK와 함께 사용할 Azure Bot 리소스 프로비전

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

필수 조건

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 되는 방식을 확인할 수 있습니다.

다음 단계

에이전트 SDK와 함께 사용할 Azure Bot 리소스 프로비전

이 퀵스타트는 GitHub에서 QuickStart/Empty Agent 샘플을 다운로드하고 실행하는 방법을 보여줍니다.

Microsoft 365 에이전트 SDK를 시작하는 두 가지 주요 방법이 있습니다.

GitHub에서 사용할 수 있는 빠른 시작/빈 에이전트 에이전트 샘플 복제 및 실행
Microsoft 365 에이전트 도구 키트를 사용합니다. 에이전트 도구 키트에는 빠른 시작/빈 에이전트로 시작하는 데 Microsoft 365 에이전트 SDK를 사용하는 Visual Studio 및 Visual Studio Code용 두 개의 기본 제공 템플릿과 의미 체계 커널 또는 LangChain과 함께 Azure Foundry 또는 OpenAI 서비스를 사용하는 날씨 에이전트가 있습니다.

필수 조건

시작하기 전에 몇 가지 사항이 필요합니다. 이러한 단계는 .NET 퀵스타트에서 빈 에이전트 빠른 시작 샘플을 사용하지만, 에이전트 SDK 샘플을 사용할 수도 있습니다.

.NET 8.0 SDK
Visual Studio 또는 Visual Studio Code
Knowledge of ASP.NET Core 및 C#의 비동기 프로그래밍에 대한 지식
quickstart GitHub에서 샘플 다운로드

솔루션 열기

Visual Studio에서 솔루션 파일을 QuickStart.csproj 엽니다.
프로젝트를 실행합니다.

이 시점에서 에이전트는 포트 3978을 사용하여 로컬로 실행됩니다.

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

아직 설치하지 않은 경우 에이전트 플레이그라운드 를 설치합니다.
```
winget install agentsplayground
```
Visual Studio 또는 Visual Studio Code에서 에이전트 시작
Teams 앱 테스터를 시작합니다. 명령 프롬프트에서: agentsplayground
- 이 도구는 에이전트에 메시지를 보낼 준비가 된 Teams 앱 테스트 도구를 보여 주는 웹 브라우저를 엽니다.
포트 3978에서 실행 중인 에이전트는 브라우저의 에이전트 플레이그라운드에 자동으로 연결되어야 하며 로컬에서 실행되는 에이전트와 상호 작용할 수 있어야 합니다.

에이전트는 어떻게 작동하나요?

에이전트 SDK를 사용하여 에이전트는 AgentApplication 및 AgentApplicationOptions 클래스를 사용하여 빌드됩니다. 샘플의 Program.cs 파일에서 빌드됩니다.

에이전트 빌드

샘플에서 AgentApplicationOptions가 로드되고 에이전트가 빌드되는 동안 MyAgent.cs로부터 상속받는 사용자 지정 에이전트 클래스 AgentApplication를 볼 수 있습니다.

// Add AgentApplicationOptions from appsettings section "AgentApplication".
builder.AddAgentApplicationOptions();

// Add the AgentApplication, which contains the logic for responding to
// user messages.
builder.AddAgent<MyAgent>();

그런 다음 스토리지는 기본적으로 MemoryStorage 클래스를 사용하여 로드됩니다. 이렇게 하면 TurnState를 사용할 때 턴 간에 컨텍스트를 추적할 수 있습니다. 그러나 BlobsStorage 또는 CosmosDbPartitionedStorage와 같은 더 지속적인 스토리지를 위해 프로덕션 환경에서 전환해야 합니다.

builder.Services.AddSingleton<IStorage, MemoryStorage>();

나머지 에이전트 애플리케이션은 표준 .NET 호스팅 패턴을 사용하고 특정 엔드포인트에서 메시지를 수락하는 경로를 추가합니다. 이러한 경로는 IAgent 인터페이스를 사용하여 에이전트 활동을 수락하고, 채널/클라이언트에서 전달된 AgentApplication 페이로드를 사용할 개체를 개발자 에게 제공합니다. 활동 및 활동 사용 방법에 대해 자세히 알아보기

// This receives incoming messages from Azure Bot Service or other SDK Agents
var incomingRoute = app.MapPost("/api/messages", async (HttpRequest request, HttpResponse response, IAgentHttpAdapter adapter, IAgent agent, CancellationToken cancellationToken) =>
{
    await adapter.ProcessAsync(request, response, agent, cancellationToken);
});

메서드에 새 사용자 지정 논리 추가

개발자는 MyAgent.cs를 구현하는 AgentApplication 클래스에 사용자 지정 논리를 추가합니다. 이 클래스는 AgentApplicationOptions에서 설정한 특정 구성을 구성하며, Program.cs 및 에이전트 SDK에서 제공되는 AgentApplication 클래스에서 이벤트 수신기를 등록합니다. 이러한 이벤트가 클라이언트에서 트리거되면 해당 사용자 지정 메서드를 참조합니다.

다음 예제에서 OnConversationUpdate 는 메서드를 WelcomeMessageAsync 트리거하고 OnActivity 는 메서드 OnMessageAsync를 트리거합니다.

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

이러한 이벤트는 사용자 MyProgram.cs 에 구성된 엔드포인트를 통해 라우팅되며 사용할 수 있는 다양한 이벤트가 있습니다. 가장 일반적인 것은 .입니다 OnActivity. SDK가 구현하는 이벤트에 대해 더 알고 싶다면 활동 다루기 및 활동 프로토콜 사양에 대해 자세히 알아보세요.

예를 들어 OnMessageAsync 순서를 종료하기 위해 메서드가 트리거되면 다음 예제와 같이 메서드에서 매개 변수여야 하는 TurnContext 클래스 의 인스턴스 및 사용 가능한 메서드를 사용하여 클라이언트에 메시지를 다시 보내도록 응답하도록 사용자 지정 논리에서 선택할 수 있습니다.

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

팁 (조언)

클라이언트로 돌아갈 수 있는 다른 TurnContext 메서드 를 검토합니다.

이제 기본 사항을 알고 다음 단계를 확인하고 에이전트에 사용자 지정 처리기 논리를 추가하고 다른 이벤트를 다시 보내기 위해 작업합니다.

다음 단계

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

피드백

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

Last updated on 2025-11-18

다음을 통해 공유

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

필수 조건

프로젝트 초기화 및 SDK 설치

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

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

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

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

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

다음 단계

필수 조건

프로젝트 초기화 및 SDK 설치

필수 라이브러리 가져오기

AgentApplication으로 EchoAgent 구현

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

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

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

다음 단계

필수 조건

솔루션 열기

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

에이전트는 어떻게 작동하나요?

에이전트 빌드

메서드에 새 사용자 지정 논리 추가

다음 단계

피드백

추가 리소스