가상 에이전트 API에서 지원되는 기능
를 가상 에이전트 API 사용하여 채팅 환경에서 사용할 수 가상 에이전트에이전트 채팅 있는 동일한 기능을 여러 개 통합할 수 있습니다. 기능 지원은 릴리스 및 스토어 앱의 가상 에이전트 API버전 번호에 따라 ServiceNow 다릅니다.
API의 가상 에이전트 요청 및 응답 템플릿에 대한 자세한 내용과 일반적인 사용 사례의 예는 가상 에이전트 봇 통합 API를 참조하십시오.
버전 4.3.0
가상 에이전트 API에서 프리미엄 채팅 지원버전 4.1.1
가상 에이전트 API에서 합성된 응답 지원
- 경험을 가상 에이전트 API 통해 Now Assist 합성된 응답이 활성화되면 인용이 포함된 응답을 기본 봇에 보냅니다. 인용은 별도의 인용 링크와 함께 매개변수에 citations 포함됩니다.
- 다음은 인용 및 인용 링크가 포함된 합성된 응답에 대한 JSON 예입니다.
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "0dce3e37ffe1f610f71affffffffff8a", "requestId": "1765195564288", "streamActive": false, "streamState": "END", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "feedback": { "messageId": "dcde7a7739e1f610beed69f9e5960355", "feedbackEnabled": true }, "maskType": "NONE", "citations": [ { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33", "sysId": "24d9243187032100deddb882a2e3ec33", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What is Spam?", "index": 0, "source": "internal", "category": "kb", "citationLabel": "What is Spam?", "table": "kb_knowledge", "citationRef": "[1]" }, { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2", "sysId": "0b48fd75474321009db4b5b08b9a71c2", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "How to Deal with Spam", "index": 1, "source": "internal", "category": "kb", "citationLabel": "How to Deal with Spam", "table": "kb_knowledge", "citationRef": "[2]" }, { "citationHref": "http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d", "sysId": "3020c9b1474321009db4b5b08b9a712d", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What are phishing scams and how can I avoid them?\n\t\t", "index": 2, "source": "internal", "category": "kb", "citationLabel": "What are phishing scams and how can I avoid them?\n\t\t", "table": "kb_knowledge", "citationRef": "[3]" } ], "streamId": "4fcef677ffe1f610f71affffffffffee", "uiType": "OutputText", "messageId": "dcde7a7739e1f610beed69f9e5960355", "relatedList": [], "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, quack health products, pornographic site ads, offers for bulk emailing services, chain letters, and pirated software. Most reputable marketers do not use spam for advertising. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes.\n- Use judgment when unsubscribing or responding to unfamiliar sources \u200b[1]\u200b\u200b[2]\u200b.\n\nPhishing scams, a dangerous form of spam, attempt to trick you into revealing personal information by pretending to be legitimate organizations. Always verify requests for sensitive information and avoid clicking suspicious links \u200b[3]\u200b.\n\n[1] [What is Spam?](http://10.160.66.170:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://10.160.66.170:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)\n[3] [What are phishing scams and how can I avoid them?\n\t\t](http://10.160.66.170:8080/sp?id=kb_article&sys_id=3020c9b1474321009db4b5b08b9a712d)", "group": "DefaultText" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - 자세한 내용은 가상 에이전트 API에서 합성된 응답 사용 문서를 참조하십시오.
가상 에이전트 API에서 에이전틱 응답 지원
- 가상 에이전트 API 경험을 통해 Now Assist 에이전틱 응답을 지원합니다. 에서 에이전틱 응답이 활성화되면 가상 에이전트 API출력 메시지가 사용자에게 로드 또는 처리 중으로 표시됩니다.
- 가상 에이전트 API 새 DynamicLoader 매개변수를 통해 기본 봇에 메시지를 보냅니다.
- 다음은 에이전틱 응답에 대한 JSON 예입니다.
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "0dce3e37ffe1f610f71affffffffff8a", "requestId": "1765195564288", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "progressMessages": [ { "message": "Searched for relevant documents and actions", "status": "COMPLETED" }, { "message": "Generated the response", "status": "COMPLETED" } ], "actionType": "DynamicLoader", "defaultHeader": "View AI Steps", "uiType": "ActionMsg", "parentMessageId": "87cef677ffe1f610f71affffffffff4d", "header": "View AI Steps", "messageId": "87cef677ffe1f610f71affffffffff4d", "shouldUpdateParentMessage": true } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } }
가상 에이전트 API에서 응답 스트리밍 지원
- 가상 에이전트 API 경험을 통한 Now Assist 응답 스트리밍을 지원합니다. 자세한 내용은 Now Assist가상 에이전트 API 에서 경험 활성화 문서를 참조하십시오. 주:기본 봇은 스트리밍 응답을 최종 사용자에게 전달해야 합니다. 자세한 내용은 채팅 스트리밍 응답 문서를 참조하십시오.
- 가상 에이전트 API 는 응답 스트리밍에 대해 다음과 같은 상태를 지원합니다.
- 시작
{ "clientSessionId": "va_api_conv_16875", "requestId": "1762864530268", "streamActive": true, "streamState": "START", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "StreamStart", "streamSequence": 1, "value": "Looking into your request" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - 진행 중
{ "clientSessionId": "va_api_conv_16875", "requestId": "1762864530268", "streamActive": true, "streamState": "INPROGRESS", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "StreamChunk", "streamSequence": 2, "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } } - 종료
{ "clientSessionId": "va_api_conv_16875", "score": 1, "interactionId": "d592c89f53097e10f71a6dc230e5e68c", "requestId": "1762864530268", "streamActive": false, "streamState": "END", "message": { "typed": true, "text": "what is spam?" }, "body": [ { "feedback": { "messageId": "6f92cc9f34097e108001c582b67b2a1f", "feedbackEnabled": true }, "maskType": "NONE", "citations": [ { "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33", "sysId": "24d9243187032100deddb882a2e3ec33", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "What is Spam?", "index": 0, "source": "internal", "category": "kb", "citationLabel": "What is Spam?", "table": "kb_knowledge", "citationRef": "[1]" }, { "citationHref": "http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2", "sysId": "0b48fd75474321009db4b5b08b9a71c2", "icon": "sn_nowassist_va.source-kb-article.png", "header": "KB article", "description": "How to Deal with Spam", "index": 1, "source": "internal", "category": "kb", "citationLabel": "How to Deal with Spam", "table": "kb_knowledge", "citationRef": "[2]" } ], "streamId": "cb928c9f53097e10f71a6dc230e5e639", "uiType": "OutputText", "messageId": "6f92cc9f34097e108001c582b67b2a1f", "relatedList": [], "value": "Spam refers to unsolicited commercial email (UCE) or unsolicited bulk email (UBE), commonly known as junk email. It often includes phishing scams, foreign bank scams, pyramid schemes, \"get rich quick\" offers, quack health products, ads for pornographic sites, offers for bulk emailing services, chain letters, and pirated software. To reduce spam:\n\n- Do not reply to spam, as it confirms your address to spammers.\n- Be cautious when sharing your email address online or with companies.\n- Adjust browser security settings to limit personal information exposure.\n- Avoid forwarding chain mail, as most are hoaxes \u200b[1]\u200b\u200b[2]\u200b.\n\n[1] [What is Spam?](http://192.168.29.27:8080/sp?id=kb_article&sys_id=24d9243187032100deddb882a2e3ec33)\n[2] [How to Deal with Spam](http://192.168.29.27:8080/sp?id=kb_article&sys_id=0b48fd75474321009db4b5b08b9a71c2)", "group": "DefaultText" } ], "userId": "admin", "clientVariables": { "bot": { "id": "va-bot-12345" }, "channelId": "postman" } }
- 시작
- 다음 구성으로 스트리밍 가상 에이전트 API 을 활성화합니다.
- 에서 응답 스트리밍 허용이 선택 Now Assist가상 에이전트되어 있는지 확인합니다. 자세한 내용은 추가 채팅 기능 사용 문서를 참조하십시오.
- 모두로 이동하여 탐색 필터에 sys_now_assist_channel_config.list를 입력합니다.
- 채널 구성 [now_assist_channel_config] 테이블에서 Now Assist 봇-봇 장치에 대해 스트리밍 준비 필드 값을 true 로 설정합니다.
그림 1. Now Assist 채널 구성 테이블
새 아웃바운드 인증 지원
- 가상 에이전트 API은(는) 이제 이전 ServiceNow AI Platform REST 메시지 대신 REST 단계를 사용하도록 워크플로우 스튜디오 구성되었습니다.
- 자세한 내용은 API에 대한 가상 에이전트 출력 응답 REST 엔드포인트 및 아웃바운드 인증 구성(v4.1 이상) 문서를 참조하십시오.
버전 4.0.0
- 가상 에이전트 API 라이브 에이전트와 기본 봇 간의 메시지에 대한 메시지 텍스트와 배달 상태를 업데이트합니다.
-
가상 에이전트 API 는 기본 봇에 대한 응답으로 상호작용 ID 및 메시지 ID(라이브 에이전트와의 대화를 위한 에이전트 ID)를 보냅니다.
상호작용 기록은 clientSessionId 최종 사용자와의 각 대화에 대해 지원되는 타사 채팅 애플리케이션(또는 기본 봇)에서 보낸 매개변수를 저장합니다. 자세한 내용은 clientSessionId를 저장할 상호작용 기록 구성 가상 에이전트 API 문서를 참조하십시오.
- 기본 봇과 최종 사용자의 대화에 대한 채팅 기록에는 개별 메시지의 타임스탬프가 포함됩니다. 이제 라이브 에이전트는 개별 메시지 또는 단일 블록에서 이 채팅 기록을 볼 수 있습니다. 자세한 내용은 가상 에이전트 API에서 채팅 기록을 지원하도록 구성 문서를 참조하십시오. 채팅 기록에 나타나는 기본 봇의 로고를 설정하여 에이전트 채팅 인터페이스를 사용자 지정할 수 있습니다. 자세한 내용은 가상 에이전트 API에서 기본 봇의 로고 설정 문서를 참조하십시오.
버전 3.0.x
버전 3.14.3의 에이전트 채팅 개선 사항
- 기본 봇이 라이브 에이전트 가상 에이전트 API 에게 채팅을 전송할 때 에이전트 이름과 아바타 외에도 에이전트 ID를 기본 봇으로 보냅니다.
- 가상 에이전트 API 는 진행 중인 대화 중에 요청의 어느 곳에서나 기본 봇의 채팅 기록을 라이브 에이전트로 보냅니다. 이 동작은 allow_storing_history_in_ongoing-대화 시스템 속성에 의해 제어됩니다. 속성 값을 예로 설정하면 요청 중 어디로나 채팅 기록을 전송할 수 있습니다.
- 상호작용 기록에는 개별 메시지의 타임스탬프와 함께 채팅 기록의 기록이 포함됩니다.
Now Assist 경험 지원
- Now Assist 의 경험 가상 에이전트 API 은 여러 제공자 채널에서 생성 AI 기술을 제공합니다.
- 자세한 내용은 Now Assist가상 에이전트 API 에서 경험 활성화 문서를 참조하십시오.
여러 제공자 애플리케이션 구성 지원
- 가상 에이전트 API 여러 기본 봇을 사용하고 가상 에이전트 API 이들을 구별해야 하는 사용 사례를 지원하도록 여러 제공자 애플리케이션을 구성할 수 있습니다.
- 자세한 내용은 여러 제공자 애플리케이션 구성 문서를 참조하십시오.
가상 에이전트 API 요청 및 응답의 변환 지원
- 가상 에이전트 API 는 요청 및 응답 페이로드 가상 에이전트 API의 변환을 지원합니다. 이는 기본 봇에 모든 보조 봇에 공통 응답 템플릿이 있는 경우에 유용합니다.
- 자세한 내용은 요청 및 응답 변환 가상 에이전트 API 문서를 참조하십시오.
개인 URL에서 보안 파일 업로드
- 가상 에이전트 API 는 개인 URL에서 최대 1GB 크기의 파일 업로드를 지원합니다. 기본 봇은 사용자 ID, 선택적 제공자 애플리케이션 ID 및 파일 이름을 전달해야 합니다. 다음 가이드라인을 준수하십시오.
- 제공자 애플리케이션 ID는 선택 사항입니다.
- 사용자 ID 및 제공자 애플리케이션 ID는 페이로드의 파일 이름 앞에 보내야 합니다.
- 최종 사용자에게는 속성에 glide.attachment.role 지정된 역할이 있어야 합니다. 자세한 내용은 파일을 첨부하는 역할 필요를 참조하세요.
- 기본 또는 OAuth 인증은 지원되지만 메시지 인증은 지원되지 않습니다.
- 기본 봇의 메시지 페이로드 예:
curl -X POST \ https://instance.service-now.com/api/now/v1/cccif/media/upload \ -H 'authorization: Basic YWRtaW46YWRtaW4=' \ -H 'content-type: multipart/form-data; \ -F user_id=xxxxxx \ -F provider_application_id=optionalId \ -F 'file=@SomeFile.png' - 가상 에이전트 API 는 다음 예제 JSON을 보냅니다.
{ "result": { "mediaUrl": "http://123.456.7.8:8080//api/now/v1/cs/media/string", "name":"imagefile.png", "state":"pending", "attachmentId":"abcdefghijklmno12345" } }
silentMessage 플래그 지원
- 자동 메시지는 응답이 필요하지 않은 메시지입니다. 가상 에이전트 로 요청을 silentMessage=true받으면 자동 모드(silentMessage=false)를 끄라는 요청을 받을 때까지 가상 에이전트 모든 후속 봇 메시지가 억제됩니다.
- 기본 봇의 메시지 페이로드 예:
{ "token": "BOT_TOKEN", "botToBot": true, "clientSessionId": "884502214730301027f83ee4070f589a", "clientVariables": {}, "requestId": "48450221d23030107300b7756770bc9b", "silentMessage": "true", "timestamp": 1623916324820, "timezone": "GMT", "userId": "abel.tuter", "emailId": "abel.tuter@example.com" }주:이 경우 silentMessage=true알림이 전달되지 않습니다.
작업 메시지 지원
- 보조 봇에 ServiceNow® 가상 에이전트 메시지를 전달하는 것 외에도 기본 봇 또는 채팅 클라이언트는 를 통해 에이전트 채팅에이전트에게 메시지를 전달할 수 있습니다. 요청 본문에 전달된 매개변수를 사용하여 action 콘텐츠 처리 방법을 지정합니다.
- 가상 에이전트 API 는 다음 작업 메시지 유형을 지원합니다.
표 1. 지원되는 작업 메시지 유형 actionType 값 설명 ChatSubHeader 다음 중 하나가 발생했음을 나타내는 아웃바운드 메시지: - 동적 변환에 실패했습니다.
- 라이브 에이전트 자동 파일럿이 시작되고 완료되었습니다.
시작 스피너 비속어 필터와 같은 AI 검색 비동기 프로세스로 인해 메시지가 보류 중 상태일 때 스피너를 시작하는 아웃바운드 메시지입니다. 엔드 스피너 이전에 전송된 스피너를 중지하는 아웃바운드 메시지입니다. StartTypingIndicatorActionMsg (에이전트가 채팅을 수락한 후) 사용자 또는 에이전트가 입력을 시작했음을 나타내는 아웃바운드 메시지입니다. EndTypingIndicatorActionMsg 사용자 또는 에이전트가 입력을 중지했음을 나타내는 아웃바운드 메시지입니다. SubscribeToSupportQueue 대화가 지원 큐로 설정되었음을 나타냅니다. SubscribeToChatPresence 라이브 에이전트 대화가 시작되었음을 알리는 아웃바운드 메시지입니다. SwitchToLiveAgent 라이브 에이전트가 대화를 수락했음을 나타내는 아웃바운드 메시지입니다. SwitchToVirtualAgent 라이브 에이전트 세션이 종료되었고 대화가 반환됨을 나타내는 아웃바운드 메시지입니다.가상 에이전트 대화 전환 알림이 전송되었음을 나타내는 아웃바운드 메시지입니다. 이렇게 하면 새 대화가 생성되므로 가상 에이전트 새 대화로 전환됩니다. 시스템 다음 중 하나를 나타내는 아웃바운드 메시지입니다. - 라이브 에이전트가 고양이에 들어왔습니다.
- 라이브 에이전트 또는 사용자가 채팅을 종결했습니다.
- 라이브 에이전트와의 대화 시간이 초과되었습니다.
동기식 핸드셰이크 개선 사항
- 가상 에이전트 API 라이브 에이전트로 동기적으로 전송할 수 있습니다. 사용자나 에이전트가 대화를 마치면 다시 전송도 가상 에이전트 동기식으로 수행됩니다. 일부 시스템 메시지 및 대기 시간 메시지도 동기적으로 전송됩니다.
- 라이브 에이전트에 대한 동기 전송을 사용하려면 다음 가이드라인에 유의하십시오.
- 응답 엔드포인트를 구성합니다 가상 에이전트 . 에이전트 채팅 지정한 엔드포인트로 메시지가 전달됩니다.
- 인스턴스에 대한 알림을 수동으로 꺼야 합니다.
- 라이브 에이전트 가상 에이전트 API 로 동기 전송을 사용하는 경우 활성화된 경우 입력 표시기를 보냅니다.
{ "uiType": "ActionMsg", "actionType": "StartTypingIndicator", } - 동기 모드에서 파일 업로드, 작업 유틸리티, 및 일시 중지 주제 블록 기능을 사용하는 주제는 지원되지 않습니다.
- 이러한 기능을 비활성화하고 동기 지원을 활성화하려면 다음 문서를 참조하십시오 가상 에이전트 API에서 동기식 지원 사용.
주제 전환 오류 및 문제 해결 개선
- 다음과 같은 이유로 주제 전환에 실패할 수 있습니다.
- 요청에는 주제 이름과 주제 ID(키워드 주제 디스커버리) 또는 주제 의도 이름과 주제 의도 ID(NLU 주제 디스커버리)가 모두 포함됩니다. 둘 중 하나를 지정합니다.
- 요청에 잘못된 주제 또는 의도 이름 또는 ID가 포함되어 있습니다.
- 주제/의도 이름 또는 ID는 유효하지만 가상 에이전트 비활성 상태이거나 주제가 아니기 때문에 실행할 수 없습니다. 예를 들어 이름 또는 ID가 주제 블록 또는 사용자 지정 통제 자산을 참조하는 경우입니다.
- 요청한 토픽이 이미 실행 중입니다.
- 요청한 토픽은 유효하지만 보안 조건으로 인해 액세스할 수 없습니다. 예를 들어, 주제가 채널에서 실행되지 않거나 다른 접근 제어 조건이 적용될 수 있습니다.
- 주제 전환에 실패하면 가상 에이전트 API 동기식으로 사용하든 비동기적으로 사용하든 다음과 같은 방식으로 응답합니다.
- 주제 전환에 실패하면 대화를 계속할 수 없다는 메시지와 함께 대화가 종료됩니다. 대화가 더 이상 열림 상태로 유지되지 않습니다.
- 이전 요청은 처리된 것으로 표시되므로 시간 초과를 기다리지 않고 새 요청을 만들 수 있습니다.
- 실패의 원인이 시스템 로그 테이블().
가상 에이전트 API 응답시간 향상
- 가상 에이전트 API 응답에는 통제 가져오기 및 NLU 점수와 같은 매개변수가 포함됩니다. 이러한 매개변수는 응답을 준비하는 동안 처리됩니다.
- 버전 3.9.0부터는 응답에서 통제 및/또는 NLU 점수 매개변수를 가상 에이전트 API 제외하여 응답시간을 개선할 수 있습니다.
- 응답에서 통제 및 NLU 점수 매개변수를 가상 에이전트 API 제외하려면 다음 단계를 완료하십시오.
- 다음으로 이동 .
- 및 send_nlu_score 속성을 검색합니다enable_take_control.
- 통제권 가져오기 설정을 제외하려면 속성 값을 enable_take_control 아니오로 설정하고, send_nlu_score 응답을 처리하는 동안 NLU 점수 계산을 제외하려면 속성을 아니오로 설정합니다. 이러한 속성은 기본적으로 true로 설정됩니다.
중단된 가상 에이전트 대화 종료
- 오류 가상 에이전트 로 인해 대화가 완료되지 않은 경우 기본 봇에게 제어를 요청할 수 있습니다. takeControl 플래그가 ( 가상 에이전트 보조 봇으로)이면 true대화가 자동으로 종료됩니다. 기본 봇이 대화를 시작하려는 경우
"hi"/START_CONVERSATION작업 메시지를 보낼 수 있습니다. - 다음과 같은 상황에서 기본 봇에게 제어권을 사용하도록 요청할 수 있습니다.
- 유휴 시간 제한: 상호작용 상태가 중단 종결입니다. 상태 이유가 활동 없음입니다.
- 기술적 문제: 상호작용 상태가 중단 종결입니다. 상태 이유는 봇 문제입니다.
- 잘못된 사용자 입력: 상호작용 상태가 중단 종결입니다. 상태 이유가 잘못된 사용자 입력입니다.
- 기본 봇이 제어하도록 요청하려면 페이로드 본문의 플래그를 takeControl 값이 지정된 기본 봇 true에 보냅니다.
- 예시 메시지 페이로드:
{ "requestId": "xxxx-xxxx-xxxx-xxxx", "clientSessionId": "xxx-xxx-xxx-xxx", "message": { "text":"invalid3", "typed":true } "body":[{ "uiType":"OutputText", "group":"DefaultText", "value":"Sorry, I didn't get that. Could you help me by answering this?" }, { "uiType":"Boolean", "group":"DefaultPicker", "required":true, "nluTextEnabled": false, "label":"Choose a value", "options":[ {"label":"Yes"}, {"label":"No"} ] }], "takeControl":true, "score":0 }