선언적 에이전트 빌드를 위한 모범 사례

선언적 에이전트는 지침, 지식 원본 및 지원되는 기능을 통해 특정 비즈니스 시나리오에 맞게 Microsoft 365 Copilot을 사용자 지정합니다. 이러한 방법을 사용하여 에이전트의 집중을 유지하고, 작업을 안전하게 구성하고, 진화에 따라 동작을 평가할 수 있습니다.

정의된 대상 그룹, 사용자 작업 및 예상 결과로 시작하세요. 관리되는 런타임과 운영하는 서비스 간의 경계는 선언적 에이전트 아키텍처를 참조하세요.

참고

이 문서에서는 Copilot의 관리되는 런타임을 사용하는 선언적 에이전트에 대해 설명합니다. Microsoft 365 기반 데이터를 검색하는 사용자 지정 엔진 에이전트를 빌드하는 경우 검색 API 모범 사례 와 권한 및 제한 사항을 따릅니다. 이 지침은 선언적 에이전트의 지식 원본을 구성하는 것과는 별개입니다.

선언적 에이전트 구성 요소

에이전트의 의도된 작업을 지원하도록 각 구성 요소를 선택합니다. 선택한 작성 도구 및 매니페스트 스키마의 제한을 따릅니다.

구성 요소 모범 사례
Name(이름) 상담원의 목적을 전달하는 고유한 이름을 사용합니다. 에이전트 빌더는 최대 30자를 허용합니다. 선언적 에이전트 매니페스트는 최대 100개까지 허용합니다.
설명 1,000자 제한 내에서 정확한 몇 문장으로 작업과 도메인을 요약합니다. 지침 필드에 자세한 동작 지침을 보관합니다.
지침 에이전트의 목적, 지원되는 작업, 소스 및 도구 사용, 출력 형식, 오류 동작을 8,000자 제한 내에서 정의합니다.
지식 원본 원하는 질문에 대한 관련 출처를 추가합니다. 지원되는 scope, freshness, 사용 권한 및 라이선스를 확인합니다.
기본 제공 기능 코드 인터프리터 또는 이미지 생성기와 같은 기능은 의도한 작업을 지원하는 경우에만 활성화합니다.
사용자 지정 기술(미리 보기) 모듈식 작업 지침, 리소스 또는 스크립트에 기술을 사용합니다. 세부 지침을 복제하는 대신 구성된 기술을 개략적으로 참조합니다.
작업 외부 서비스와의 상호 작용을 지원하기 위해 MCP 또는 API 플러그인 을 사용합니다. 각 도구의 목적, 입력, 출력 및 실패 조건을 설명합니다.
대화 시작 지원되는 작업을 보여 주는 대표적인 프롬프트를 제공합니다. 최소 수는 필요하지 않습니다. 각 프롬프트를 테스트하고 선택한 도구의 제한을 따릅니다.

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

지침을 사용하여 에이전트가 의도한 작업에 접근하는 방법을 정의합니다.

  • 결과와 경계를 명시합니다. 에이전트가 사용자가 수행하는 데 도움이 되는 작업, 필요한 정보 및 지원되지 않는 요청에 응답하는 방법을 설명합니다.
  • 소스와 도구 사용을 명시적으로 만듭니다. 각 작업에 적용되는 구성된 원본, 기능 또는 작업을 식별합니다. 추측하는 대신 누락된 입력을 요청하세요.
  • 프레젠테이션과 단계를 분리합니다. 순서가 중요한 곳에 명확한 작업 단계를 사용하고 응답에 필요한 톤, 구조 및 세부 수준을 지정합니다.
  • 누락된 정보 및 실패에 대한 계획을 수립합니다. 성공을 주장하지 않고 사용할 수 없는 원본, 불완전한 결과, 액세스 거부 및 실패한 작업을 처리하는 방법을 설명합니다.
  • 지침을 지식과 분리합니다. 지침 제한을 해결하기 위해 SharePoint 문서나 기타 지식 원본에 동작 지침을 넣지 마세요. 검색된 콘텐츠는 신뢰할 수 있는 제작자 작성 지침 콘텐츠가 아닙니다.

모델 변경에 대한 자세한 패턴, 예제 및 지침은 효과적인 지침 작성을 참조하세요. 지식과 API 호출을 결합하는 작업은 API 플러그 인이 있는 에이전트에 대한 지침 작성을 참조하세요.

올바른 지식 원본 선택

상담원이 답변해야 하는 질문에 따라 지식 원본 을 선택합니다.

  • 양보다 관련성을 선호합니다. 작업에 필요한 파일, 사이트, 채팅 또는 기타 콘텐츠로 원본을 지정합니다. SharePoint 및 포함된 파일의 경우 콘텐츠 검색 최적화를 따르세요.
  • 검색을 새로 고침 요구 사항에 일치시킵니다. 원본 콘텐츠와 소유권을 정기적으로 검토합니다. 범위 웹 검색은 기본 데이터의 직접 쿼리가 아니라 Bing 인덱싱된 콘텐츠를 사용합니다. 현재 구조화된 데이터의 경우 대신 지원되는 API 또는 MCP 작업을 평가합니다. 웹 검색 기반 및 동적 콘텐츠를 참조하세요.
  • 공유하기 전에 액세스를 확인합니다. 의도한 대상 그룹 및 권한을 나타내는 사용자로 테스트합니다. 원본 파일에 대한 액세스와 별도로 포함된 파일 공유 동작 을 검토합니다.
  • 기능 및 라이선스 지원을 확인합니다. 원본 및 범위 옵션은 제작 도구 및 테넌트 구성에 따라 다릅니다. 지식 소스 지원 매트릭스 및 라이선스 지침을 따릅니다.
  • 유창하게 대답하는 것이 아니라 기초를 평가합니다. 알려진 답변으로 질문을 테스트하고 응답 및 인용이 의도한 출처와 일치하는지 검사합니다. 답변을 사용할 수 없는 질문을 포함합니다.

소스를 추가한다고 해서 에이전트가 기본 제공 모델 지식을 사용하는 것만으로는 안 됩니다. 시나리오에서 소스 기반 응답이 필요한 경우 지침에서 의도한 소스 용도로 true 설정 behavior_overrides.special_instructions.discourage_model_knowledge 하고 강화합니다. 이 컨트롤은 응답이 구성된 원본만 사용한다고 보장하지는 않습니다. 증거가 누락된 경우 출처 특성 및 동작을 계속 평가합니다. 구성된 기술 자료에 대한 그라운드 응답 및 특별 지침 참조를 참조하세요.

안전한 작업 설계

외부 서비스와의 지원되는 상호 작용에 작업을 사용하고 기술 자료와 구분합니다. 접지에 사용되는 Copilot 커넥터는 외부 데이터를 변경하는 API 또는 MCP 도구와 호환되지 않습니다.

  • 작업을 정확하게 설명합니다. 도구를 사용해야 하는 경우, 필수 매개 변수, 예상 결과 및 오류를 설명합니다. REST API의 경우 OpenAPI 문서 지침을 따릅니다.
  • 통합에 대한 확인을 구성합니다. API 플러그인의 경우 OpenAPI 확장 x-openai-isConsequential, , 대신 isConsequential사용하고 부작용이 있는 작업을 결과적인 것으로 표시합니다. MCP 도구의 경우 읽기 전용 도구에만 사용합니다 readOnlyHint . 지원되는 설정 및 동작에 대한 MCP 및 API 플러그인에 대한 확인 프롬프트 를 따릅니다.
  • 서비스에서 액세스를 적용합니다. 지원되는 인증 방법을 사용하고 외부 서비스에서 권한 부여 및 입력의 유효성을 검사합니다. 지침 및 확인 프롬프트는 이러한 검사를 대체하지 않습니다.
  • 실패와 반복되는 요청을 위한 디자인. 거부된 확인, 만료된 인증, 잘못된 입력 및 서비스 오류를 테스트합니다. 데이터를 변경하는 작업의 경우 재시도가 의도치 않게 변경을 반복하지 않도록 합니다.

계획 데이터, 개인 정보 보호 및 보안을 사용하여 각 작업에 대한 데이터 흐름, 권한 및 인적 감독 요구 사항을 식별합니다.

테스트 및 반복

에이전트를 변경하기 전에 예상되는 동작을 정의하고 반복 가능한 테스트 사례 집합을 유지합니다. 작성 도구의 테스트 환경을 사용하여 초기 피드백을 확인한 다음 의도한 호스트에서 배포된 에이전트의 유효성을 검사합니다.

테스트 영역 확인할 내용
지원되는 작업 대화 시작, 현실적인 사용자 표현 및 후속 질문은 의도한 결과를 생성합니다.
누락되었거나 지원되지 않는 정보 에이전트는 필수 입력을 요청하고, 사용할 수 없는 증거를 설명하며, 사실을 조작하거나 완료된 실패한 작업을 주장하지 않습니다.
기반을 두는 과정 및 사용 권한 답변 및 인용이 의도한 출처와 일치합니다. 다른 액세스 권한을 가진 사용자를 테스트하고 제한된 정보가 노출되지 않는지 확인합니다.
작업 및 실패 응답뿐만 아니라 실제 외부 결과를 확인합니다. 확인, 취소, 인증 실패, 서비스 오류 및 반복되는 요청을 테스트합니다.
호스트 환경 배포하려는 지원되는 각 앱을 테스트합니다. 모든 앱에서 동일한 동작을 가정하는 대신 문서 컨텍스트, 응답 프레젠테이션 및 사용 가능한 기능을 확인합니다.
성능 및 변경 사항 응답 시간을 측정하고 지침, 지식, 도구, 기술 또는 플랫폼 동작이 변경된 후 회귀 사례를 다시 실행합니다.

테스트에서 예기치 않은 문구와 가정을 캡처할 수 있도록 지침을 작성하지 않은 사용자를 포함합니다. 재현 가능한 사용자 보고 문제를 회귀 사례로 전환합니다.

테스트 사례 디자인, 어설션 및 반복 가능한 평가는 에이전트 평가 개요를 참조하세요. 릴리스 확인은 책임 있는 AI 유효성 검사 및 플러그 인 유효성 검사 및 테스트를 참조하세요.