API 플러그 인을 사용하여 선언적 에이전트에 대한 효과적인 지침 작성

선언적 에이전트는 organization의 특정 요구 사항에 맞게 Microsoft 365 Copilot 조정합니다. API 플러그 인을 통해 사용자 지정 작업을 추가할 수 있습니다. 지원되는 프로 코드 시나리오의 경우 Work IQ Dev Tools 를 사용하는 것이 좋습니다. 이러한 통합을 통해 상담원은 API를 통해 organization의 데이터를 쿼리하고 상호 작용할 수 있습니다. 기술에서 플러그인 기능으로 설명하는 재사용 가능한 지침 파일이 아닙니다.

이 문서에서는 에이전트 아키텍처를 설명하고 API 플러그 인을 포함하는 선언적 에이전트에 대한 지침을 작성하기 위한 모범 사례를 제공합니다.

API 플러그 인이 있는 선언적 에이전트의 주요 구성 요소

API 플러그 인을 호출하는 선언적 에이전트에는 효과적인 통합 및 기능을 보장하는 여러 구성 요소가 포함되어 있습니다. 이 아키텍처를 이해하면 에이전트를 효과적으로 디자인하는 데 도움이 됩니다. 아키텍처에는 다음 구성 요소가 포함되어 있습니다.

  • 애플리케이션 매니페스트 - 앱이 어떻게 구성되고 선언적 에이전트 매니페스트를 참조하는지 설명합니다.
  • 선언적 에이전트 매니페스트 - 지침, 기능, 대화 시작 및 작업을 포함하여 에이전트의 구성을 정의합니다. 플러그인 매니페스트를 참조합니다.
  • 플러그인 매니페스트 - 사용 가능한 함수 및 OpenAPI 사양에 대한 참조를 포함하여 플러그인 구성을 설명합니다.
  • OpenAPI 사양 - 경로, 매개 변수, 요청 및 응답 형식, 인증을 포함하여 API 엔드포인트에 대한 자세한 정의를 제공합니다.

이러한 파일은 함께 에이전트의 동작 및 에이전트가 기본 API와 상호 작용하는 방식을 정의합니다.

서로를 참조하는 네 개의 매니페스트 파일을 보여주는 다이어그램

API 플러그인에 대한 자세한 내용은 다음을 참조하세요.

플러그 인 매니페스트의 함수 매핑

플러그 인 매니페스트에서 각 함수는 OpenAPI 사양의 해당 operationId 에 매핑되어야 합니다. 이렇게 하면 에이전트가 함수( 예: createTask)를 호출할 때 에이전트가 호출할 API 엔드포인트를 알 수 있습니다.

다음 예제에서는 플러그인 매니페스트의 매핑과 OpenAPI 사양의 매핑된 함수를 보여 줍니다.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]
paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

에이전트 지침에 대한 모범 사례

API 플러그인이 있는 선언적 에이전트가 성공하도록 하려면 효과적인 지침을 작성하는 것이 필수적입니다. 에이전트를 최적화하려면 올바른 함수 매핑을 적용하고, 체인을 사용하여 더 풍부한 상호 작용을 가능하게 하고, 에이전트의 동작을 반복적으로 테스트하고 개선합니다.

API 플러그 인을 사용하여 선언적 에이전트에 대한 지침을 작성할 때 다음 모범 사례를 적용합니다.

  • 모호하거나 부정적인 지시는 피합니다. 대조적이거나 부정적인 명령은 모호성을 유발하고 모델에 혼란을 줄 수 있습니다. 긍정적인 사례를 통해 유효한 사용 사례를 정의하는 데 중점을 둡니다. 유효한 쿼리와 유효하지 않은 쿼리를 구별하는 것이 중요한 경우 각각에 대한 예상 에이전트 응답을 정의하는 명확한 기준과 예제를 제공합니다.
  • 사용 예제 에이전트 동작을 안내하는 명확한 예제를 제공합니다. 예를 들면 다음과 같습니다.

사용자 입력: 프라하의 날씨는 어떤가요? 에이전트 호출: getWeather(location="Prague") 사용자 입력: "내일 우산이 필요한가요?" 에이전트 호출: getWeather(location=user_location, forecast="tomorrow")

  • 지침을 검토하고 테스트합니다. 다양한 시나리오에서 테스트 지침을 수행하여 에이전트가 올바른 함수 호출을 하는지 확인합니다. 테스트 중 에이전트가 예기치 않게 함수를 호출하는 경우 OpenAPI 사양의 함수 설명을 수정하고 에이전트 명령을 명확히 하여 의도 매핑을 개선합니다.

  • 다중 전환 대화에 대한 디자인 지침입니다. API 플러그인을 통합할 때 에이전트가 다중 전환 대화를 처리하도록 지침을 설계합니다.

예를 들어 함수에 여러 매개 변수가 필요한 경우 OpenAPI 사양에서 필수 매개 변수를 정의하는 것 외에도 API 호출을 수행하기 전에 모든 매개 변수를 수집하도록 에이전트에 지시합니다. 이렇게 하면 에이전트가 필요한 모든 정보를 논리적 순서로 수집할 수 있습니다.

다음 예에서는 다중 전환 대화에 대해 날씨 에이전트에게 지시하는 방법과 그로 인한 에이전트 흐름을 보여줍니다.

에이전트에 대한 지침 에이전트 흐름
사용자가 날씨에 대해 묻는 경우:

- 사용자에게 위치를 묻습니다.
- 사용자에게 예측 날짜를 요청합니다.
- 사용자에게 단위 시스템을 요청하십시오.
- 모든 값을 수집할 때만 getWeather 를 호출합니다.
사용자: "날씨가 어때?"
에이전트: "위치는 어디인가요?"
사용자: "London"
에이전트: "미터법과 영국식 중 어떤 날씨 정보를 선호하십니까?"
사용자: "메트릭"
에이전트: "오늘 날씨가 필요한가요, 아니면 내일 날씨 예보가 필요하신가요?"
사용자: "오늘"
에이전트: "오늘 런던 날씨를 검사하겠습니다"
에이전트 호출: getWeather(location="London", forecast="today", system="Metric")

에이전트 지침에 대한 일반적인 모범 사례는 효과적인 지침 작성을 참조하세요.

API 플러그인에서 함수 호출 연결

함수 호출을 연결하면 선언적 에이전트가 여러 API 작업을 하나의 원활한 흐름으로 결합할 수 있습니다. 다음 섹션에서는 일반적인 패턴과 각 패턴에 대한 지침을 작성하는 방법을 설명합니다.

출력을 입력 매개 변수로 사용하여 함수 호출 연결

한 API 호출의 결과를 다른 API 호출에 대한 입력으로 사용합니다. 이는 두 번째 함수를 수행하기 위해 첫 번째 함수의 결과가 필요한 경우에 유용합니다. 이는 여러 플러그 인에서 작동할 수 있습니다.

다음 예제에서는 날씨 API 및 To-do API를 사용하는 선언적 에이전트가 일기 예보의 데이터를 사용하여 할 일 작업을 만듭니다.

에이전트에 대한 지침 에이전트 흐름
날씨를 가져오려면 항상 getWeather 작업을 사용한 다음 "temperature in"이라는 제목의 작업을 만들고 날씨에 언급된 위치와 온도를 작업 제목에 추가합니다. 사용자: "프라하 날씨 받기"
에이전트:getWeather (location="Prague", forecast="today")를 호출합니다.
에이전트: 첫 번째 호출의 데이터를 사용하여 할 일 작업을 만듭니다. createTask (title ="{weather output}")

한 에이전트 내에서 대화 기록을 기반으로 연결

대화 기록을 기반으로 연결하는 기능을 사용하면 에이전트는 이전 응답을 사용하여 후속 조치를 처리합니다. 이 접근 방식에서는 대화 기록을 사용하여 컨텍스트를 유지합니다.

다음 예제에서 에이전트는 이름으로 할 일을 삭제합니다.

에이전트에 대한 지침 에이전트 흐름
1. 사용자가 모든 할 일 목록을 요청하면 getTasks 를 호출하여 제목과 ID가 있는 할 일 목록을 검색합니다.
2. 할 일을 나열한 후 사용자가 할 일 삭제를 요청하면 응답의 ID를 사용하여 deleteTask를 호출합니다.
사용자: "작업 폴더의 할 일을 모두 표시해 줄래?"
Agent: alls getTasks (folderId="Tasks") ID가 있는 모든 할 일을 표시합니다.
사용자: "Delete TaskMaster Pro to-do"
Agent: 대화 기록의 정보를 사용하여 할 일의 ID를 찾고, deleteTask를 호출하여 할 일을 삭제합니다.

SharePoint 지식으로 연결

API 호출을 연결하면 에이전트가 지식 원본과 작업을 결합하여 더 복잡한 워크플로를 디자인할 수 있습니다.

다음 예제에서 에이전트는 SharePoint에서 프로젝트 상태 데이터를 검색하고 추적을 위해 Microsoft To-Do에서 해당 작업을 만듭니다.

에이전트에 대한 지침 에이전트 흐름
- 프로젝트 상태를 얻으려면 SharePoint 지식 ProjectDeadlines를 사용합니다.
- 항상 타이틀의 상태 업데이트를 사용하여 각 프로젝트에 대한 할 일을 만듭니다.
사용자: "모든 프로젝트의 상태에 대한 업데이트를 제공할 수 있나요?"
에이전트: SharePoint에서 프로젝트 상태 데이터를 가져온 다음 createTask를 사용하여 각 프로젝트에 대한 할 일 작업을 생성합니다.

코드 인터프리터를 사용하여 연결

API 호출을 연결하고 코드 인터프리터와 같은 추가 기능을 통합할 수도 있습니다. 이를 통해 에이전트는 API 출력을 동적으로 처리하여 고급 워크플로를 지원할 수 있습니다.

다음 예에서 에이전트는 할 일의 데이터를 기반으로 차트를 만듭니다.

에이전트에 대한 지침 에이전트 흐름
사용자가 모든 할 일을 나열하도록 요청하면 getTasks 를 호출하여 제목과 ID가 있는 할 일 목록을 검색하고 출력에 대한 차트도 그립니다. 사용자: "작업의 모든 작업 검색"
에이전트:getTasks (folderId="Tasks")를 호출하고 ID가 있는 모든 할 일을 표시합니다.
에이전트: 코드 인터프리터를 호출하여 첫 번째 호출의 출력에 따라 차트 생성을 시작합니다.

또한 이 예에서는 한 번에 여러 작업을 실행합니다. 이는 여러 사용자 입력이 필요하지 않은 일련의 관련 작업을 시작하는 데 유용합니다.

코드 인터프리터가 파일(예: 차트 이미지 또는 스프레드시트)을 생성하면 Copilot은 응답에 다운로드 링크를 자동으로 표시하여 사용자가 파일을 로컬에 저장할 수 있도록 합니다. 자세한 내용은 다운로드 가능한 파일 생성을 참조하세요.