에이전트 지역화

에이전트는 본질적으로 Microsoft 365용 앱입니다. 공통 매니페스트 스키마, 앱 패키징, 배포 및 관리 프로세스를 공유합니다. 앱 매니페스트는 개체의 선언적 에이전트에 대한 정의 파일을 참조합니다.copilotAgents

에이전트를 지역화하는 방법은 Microsoft 365 앱 매니페스트에서 다른 기능(예: 탭, 봇 및 메시지 확장)을 지역화하는 방법과 약간 다릅니다.

Teams 앱 기능과 에이전트 모두에 대해 동일한 지역화 파일(언어별)을 사용합니다. 그러나 다른 모든 앱 매니페스트 필드는 언어 파일에서 JSONPath 식을 사용하여 참조되지만 에이전트 관련 필드는 사전 키를 사용하여 참조됩니다. 앱 매니페스트 자체에서 기본 언어 문자열을 사용하는 클래식 Teams 앱 기능과 달리 지역화된 에이전트에는 기본 언어 및 각 추가 언어에 대한 언어 파일이 필요합니다.

에이전트 지역화를 위한 앱 매니페스트, 선언적 에이전트 매니페스트 및 언어 파일 간의 관계를 보여주는 다이어그램

이 문서에서는 에이전트에 다른 언어(기본 언어 외)에 대한 지원을 추가하는 방법을 설명합니다.

토큰화된 키로 에이전트 매니페스트 업데이트

지역화하려는 필드 값에 대해 토큰화된 키(예: [[PLUGIN_NAME]]이중 대괄호로 표시됨)를 사용하여 선언적 에이전트 및/또는 API 플러그인 매니페스트를 업데이트합니다. 지역화 키는 다음 정규식과 일치해야 합니다. ^[a-zA-Z_][a-zA-Z0-9_]*$

다음 예제에서는 이름 및 설명에 토큰화된 값이 있는 선언적 에이전트 매니페스트를 보여 줍니다.

{
    "$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
    "name": "[[DA_Name]]",
    "description": "[[DA_Description]]",
    "instructions": "# You are an assistant..."
}

앱 매니페스트에 추가 localizationInfo

언어 태그와 앱 패키지 내에서 지원되는 각 언어 파일에 대한 상대 경로가 포함된 섹션을 앱 매니페스트에 추가합니다localizationInfo.

에이전트가 둘 이상의 언어를 지원하는 경우 기본 언어를 포함하여 지원되는 모든 언어에 대해 독립 실행형 언어 파일을 지정해야 합니다.

다음 예제에서는 앱 매니페스트의 섹션을 보여 줍니다 localizationInfo .

"localizationInfo": {
    "defaultLanguageTag": "en",
    "defaultLanguageFile": "en.json",
    "additionalLanguages": [
        {
            "languageTag": "fr",
            "file": "fr.json"
        }
    ]
},

에이전트가 다른 언어를 지원하지 않는 경우 기본 언어 문자열은 앱 매니페스트 파일 자체 내에 표시됩니다. 단일 언어 앱 패키지에는 기본 언어에 대한 별도의 언어 파일이 필요하지 않습니다.

각 추가 언어에 대한 지역화 파일 만들기

이전 단계에서 앱 매니페스트에서 지정한 파일 이름( defaultLanguageFile 및 file 속성)을 사용하여 토큰화된 키 값으로 지원되는 각 언어에 대한 지역화 파일을 만듭니다.

다음 예제에서는 에이전트 및 개인 탭 모두에 대해 지역화된 문자열이 포함된 언어 파일을 fr.json보여 줍니다.

{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json",
    "name.short": "Agent de Communications",
    "name.full": "Agent pour les Communications",
    "description.short": "Outils pour les professionnels de la communication",
    "description.full": "Outils pour les professionnels de la communication Contoso, y compris la galerie de ressources et les assistants personnels",
    "localizationKeys": {
        "DA_Name": "Agent de Communications",
        "DA_Description": "Un assistant pour les professionnels de la communication et des relations publiques chez Contoso."
    },
    "staticTabs[0].name": "Accueil",
    "staticTabs[1].name": "Galerie de ressources",
    "staticTabs[2].name": "À propos de Contoso"
}

앱 매니페스트에서 지역화 가능한 필드

각 언어 파일에 대해 지역화해야 하는 앱 지역화 스키마에서 다음 속성을 지정합니다.

매니페스트 필드 설명 최대 길이 필수
$schema 지역화 스키마의 URL입니다. 에이전트의 경우 devPreview를 사용합니다. https://developer.microsoft.com/en-us/json-schemas/teams/vDevPreview/MicrosoftTeams.Localization.schema.json 매니페스트 스키마 버전은 앱 매니페스트와 지역화 파일 모두에서 동일해야 합니다. ✔️
name.short 앱 매니페스트의 짧은 이름을 제공된 값으로 바꿉니다. 30자 ✔️
name.full 앱 매니페스트의 전체 이름을 제공된 값으로 바꿉니다. 100자 ✔️
description.short 앱 매니페스트의 간단한 설명을 제공된 값으로 바꿉니다. 80자 ✔️
description.full 앱 매니페스트의 전체 설명을 제공된 값으로 바꿉니다. 4,000자 ✔️
에이전트의 지역화된 문자열에 대한 키/값 쌍 에이전트의 경우 현지화된 값과 함께 토큰화된 키(앱 manifest.json에 지정됨)를 사용합니다. 예를 들면 다음과 같습니다. "DA_Name": "Agent de Communications"
다른 앱 구성 요소의 지역화된 문자열에 대한 JSONPath/값 쌍 다른 모든(클래식 Teams) 앱 구성 요소의 경우 JSONPath 식을 지역화된 값의 키로 사용합니다. 예를 들면 다음과 같습니다. "staticTabs[0].name": "Accueil"

자세한 내용은 앱 지역화(Microsoft Teams) 및 지역화 스키마 참조를 참조하세요.

선언적 에이전트 매니페스트에서 지역화 가능한 필드

다음 필드는 선언적 에이전트 매니페스트 내에서 지역화할 수 있습니다.

매니페스트 필드 설명 최대 길이 필수
name 선언적 에이전트의 이름입니다. 공백이 아닌 문자를 하나 이상 포함해야 합니다. 100자 ✔️
description 선언적 에이전트에 대한 설명입니다. 공백이 아닌 문자를 하나 이상 포함해야 합니다. 1,000자 ✔️
conversation_starters 선언적 에이전트가 대답할 수 있는 질문의 예제 목록(배열). 여기서 각 예제는 와 가 text있는 title 개체이며, 둘 다 지역화할 수 있습니다. 배열의 개체 12개

자세한 내용은 선언적 에이전트 매니페스트 참조를 참조하세요.

API 플러그인 매니페스트에서 지역화 가능한 필드

다음 필드는 API 플러그인 매니페스트 내에서 지역화할 수 있습니다.

매니페스트 필드 설명 최대 길이 필수
name_for_human 사람이 읽을 수 있는 간단한 플러그 인 이름입니다. 공백이 아닌 문자를 하나 이상 포함해야 합니다. 20자 ✔️
description_for_model 모델에 제공되는 플러그인에 대한 설명으로, 플러그인의 용도 및 해당 기능이 관련되는 상황을 포함합니다. 2,048자
description_for_human 사람이 읽을 수 있는 플러그 인 설명입니다. 100자 ✔️
logo_url 오케스트레이터에서 사용할 수 있는 로고를 가져오는 데 사용되는 URL입니다.
legal_info_url 플러그인에 대한 서비스 약관이 포함된 문서를 찾는 절대 URL입니다.
privacy_policy_url 플러그 인에 대한 개인 정보 취급 방침이 포함된 문서를 찾는 절대 URL입니다.
conversation_starters 플러그 인이 답변할 수 있는 질문의 예제 목록(배열). 여기서 각 예제는 와 가 text있는 title 개체이며, 둘 다 지역화할 수 있습니다.

자세한 내용은 플러그인 매니페스트 참조를 참조하세요.