Copilot Studio 에이전트와 함께 클라이언트 API 사용

$pages.agent 개체

Power Pages Client API $pages.agent 개체와 해당 SendActivity 메서드를 사용하여 메시지를 보내거나 현재 사용자가 사용할 수 있는 Microsoft Copilot Studio 에이전트에서 이벤트를 호출합니다. 응답 및 오류 콜백은 사이트에서 에이전트의 결과를 처리하는 데 도움이 됩니다.

SendActivity 메서드

이 메서드는 SendActivity 지정된 Copilot Studio 에이전트에서 메시지를 보내거나 이벤트를 호출하고 콜백 함수를 사용하여 응답 및 오류를 처리합니다.

SendActivity 메서드 구문

$pages.agent.SendActivity(
    agentSchemaName: string,
    inputActivity: object,
    responseSubscriber: function,
    errorSubscriber: function
);

SendActivity 메서드 매개 변수

매개 변수 이름	Type	Description
agentSchemaName	문자열	활동이 전송되는 봇의 스키마 이름입니다.
inputActivity	Object	봇에 보낼 텍스트 또는 이벤트를 포함하는 개체입니다.
responseSubscriber	기능	에이전트가 응답을 보낼 때 실행되는 콜백 함수입니다.
errorSubscriber	기능	오류를 처리하는 콜백 함수입니다.

메서드는 SendActivity .를 반환합니다 void. 에이전트에서 응답을 받으려면 콜백 함수를 responseSubscriber 전달합니다. 이 메서드는 에이전트가 응답을 보낼 때 이 콜백을 호출합니다. 콜백 함수를 errorSubscriber 전달하여 오류를 처리합니다.

SendActivity 응답 속성

다음 형식으로 받은 에이전트의 응답 개체입니다.

Name	Type	Description
type	문자열	메시지와 같은 활동의 형식입니다.
text	문자열	선택 사항으로, 에이전트의 메시지입니다.
textFormat	문자열	선택 사항으로, markdown, plain 또는 XML과 같은 메시지 텍스트의 형식입니다.
Id	문자열	활동을 고유하게 식별하는 ID입니다.
From	Object	활동의 보낸 사람(ID, 이름(선택 사항) 및 역할 정보 포함)을 지정합니다.
Conversation	Object	활동이 속한 대화의 ID를 포함합니다.
InputHint	문자열	선택 사항으로, 봇이 사용자 입력을 수락, 예상 또는 무시할지 여부를 나타냅니다.
replyToId	문자열	회신 메시지의 ID입니다.

Examples

다음 예제에서는 응답 및 오류 콜백을 정의하고 메시지를 보내거나 이벤트를 호출하는 데 사용하는 SendActivity 방법을 보여 줍니다.

예시	Description
응답 및 오류 콜백 정의	responseSubscriber 에이전트 응답 및 errorSubscriber 오류를 처리하는 콜백 함수와 콜백 함수를 정의합니다.
에이전트에 메시지 보내기	지정된 에이전트에 Hello! 텍스트 작업을 보내고 콜백 함수를 사용하여 응답 또는 오류를 처리합니다.
클라이언트 이벤트 호출	AgentEvent 클라이언트 이벤트를 호출하고 키-값 페이로드를 에이전트에 전달합니다.

응답 및 오류 콜백 정의

responseSubscriber 에이전트 응답 및 errorSubscriber 오류를 처리하는 콜백 함수와 콜백 함수를 정의합니다.

const responseSubscriber = (response) => {
    // Replace with your response handling.
    console.log('Agent response:', response);
};

const errorSubscriber = (error) => {
    // Replace with your error handling.
    console.error('Error:', error);
};

// Replace with your agent schema name.
const agentSchemaName = 'agent SchemaName';

에이전트에 메시지 보내기

다음은 지정된 에이전트에 Hello! 텍스트 작업을 보내고 콜백 함수를 사용하여 응답 또는 오류를 처리하는 예제입니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        text: 'Hello!' // Message to the agent.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

클라이언트 이벤트 호출

이 샘플은 AgentEvent 클라이언트 이벤트를 호출하고 키-값 페이로드를 에이전트에 전달합니다.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const inputActivity = {
        name: 'AgentEvent', // The name of the event to be invoked.
        value: { key1: 'value1', key2: 'value2' } // Open-ended value used to carry additional data or payloads necessary for specific agent operations or responses.
    };

    $pages.agent.SendActivity(agentSchemaName, inputActivity, responseSubscriber, errorSubscriber);
});

오류 메시지

다음은 사용자가 발생할 수 있는 오류 메시지와 잠재적인 원인입니다.

오류 유형	원인	사용자에 대한 오류 메시지
에이전트 스키마 유효성 검사	잘못된 봇 스키마 이름이 제공되었거나 사용자에게 에이전트에 대한 액세스 권한이 없습니다.	Invalid bot schema name or access denied. Check the bot schema name and try again.
토큰 가져오기 오류	직접 회선 토큰을 가져오는 동안 오류가 발생했습니다.	Something went wrong while fetching the token. Please try again.
게시 활동 오류(다시 시도)	활동을 게시하는 동안 오류가 발생하여 다시 시도해야 합니다.	Something went wrong while posting the activity: retry.
게시 활동 오류(시간 제한)	보내는 메시지 또는 postActivity를 기다리는 동안 시간이 초과되었습니다.	Timed out while posting activity: Please retry.
게시 활동 오류(잘못된 활동)	입력 활동에는 이벤트를 호출할 텍스트나 이름이 없습니다.	Invalid activity: At least one of text, name, or attachments must be provided.
게시 활동 오류(사용자 ID를 찾을 수 없거나 토큰을 찾을 수 없음)	세션 스토리지에서 토큰을 찾을 수 없거나 토큰에서 사용자 ID를 찾을 수 없습니다.	Error retrieving user ID: {error message}
게시 활동 오류(일반)	활동을 게시하는 동안 지정되지 않은 오류가 발생했습니다.	Something went wrong while posting the activity: Please try again.
직접 회선 연결 오류	봇과의 직접 회선 연결을 만드는 동안 오류가 발생했습니다.	Something went wrong while creating direct line connection: Please try again.
일반 오류	위의 범주에 속하지 않는 예기치 않은 오류	An unexpected error occurred while sending activity: Please try again.

관련 정보

• 클라이언트 API 개요
• 클라이언트 API 예제