설계 원칙 — 먼저 읽어주세요

대부분의 "에이전트가 잘못된 답변을 제공한다"는 문제는 모델이 아닌 설정에 기인합니다. 빌드 전에 다음 가이드라인을 따르시면 안정적인 결과를 얻을 수 있습니다. 이를 무시하면 겉보기에는 합리적이지만 실제로는 제대로 작동하지 않는 시스템을 쉽게 조립하게 되며, 이를 플랫폼의 한계로 오인하기 쉽습니다.

빌드 전에 파악하라 — 실행만 하지 말고 인터뷰하라

"지원 에이전트를 생성하라"는 것은 명세서가 아닌 대화의 시작점입니다. 이를 create_agent 하나만으로 답변하고 빈 껍데기를 돌려주지 마십시오. 설정 마법사처럼 작동하십시오: 먼저 인터뷰하여 전체 설정을 계획하고, 이를 다시 확인한 후 빌드하십시오. 도구 파라미터가 아닌, 사용자의 실제 상황에 대해 몇 가지 질문을 평이한 언어로 던져서 완성된 모습을 그릴 수 있을 때까지 대화하십시오:

• 업무 및 대상. 이 에이전트의 목적은 무엇이며, 누가 이를 사용하며, 좋은 답변은 어떤 모습인가? 에이전트당 하나의 업무만 정의하십시오 — 세 가지 업무를 설명한다면, 그것은 세 개의 에이전트여야 합니다.
• 지식베이스에서 답변해야 할 내용. 문서, 웹사이트, 정책, 가격표가 있는가? 사실의 정확성이 중요하다면, 이는 프롬프트 텍스트가 아닌 빌드하여 연결할 지식베이스가 됩니다. 아직 준비된 것이 없다면 무엇을 수집해야 하는지 알려주십시오.
• 실행 절차 → 스킬. "X일 경우, 다음 단계를 수행하라"는 행동(예약, 스크리닝, 견적)이 있는가? 각각은 날카로운 "이럴 때 사용하라"는 설명과 함께 로드 온 디맨드 스킬이 됩니다.
• 다른 시스템에서 수행해야 할 작업 → MCP. 캘린더 확인, 주문 조회, 티켓 생성? 이러한 작업은 바인딩할 MCP 도구입니다. 어떤 시스템이며 연결 가능한지 물어보십시오.
• 유도된 상태 유지 흐름 → 스토리라인. 일회성 Q&A가 아니라 메모리가 있는 프로세스(수집 → 자격 검증 → 후속 조치)인가? 이는 단순한 에이전트가 아닌 스토리라인입니다.
• 시작 방식 및 하드 리미트. 방문자가 처음 보는 첫 줄(→ 페이지 플레이북)과 task에 넣을 경계선("가격을 인용하지 말 것", "법적 조언을 제공하지 말 것)입니다.

그런 다음 도구를 건드리기 전에 계획을 다시 확인하십시오 — "그래서 저는 지원 에이전트, 정책 PDF에서 만든 지식베이스, 예약 스킬을 빌드하고 MCP를 통해 캘린더를 바인딩하겠습니다 — 맞습니까?" —라고 한 후 확인을 받은 후에만 빌드하십시오. 이 단계를 건너뛰는 것은 바로 원하지 않는 빈 에이전트가 만들어지는 지름길입니다. 모호한 요청은 추측하라는 신호가 아니라 질문하라는 신호입니다.

하나의 에이전트, 하나의 업무

각 에이전트에게 단일하고 명확히 경계가 잡힌 업무를 부여하십시오. "모든 것을 처리하는" 에이전트 — 지원 및 영업 및 일정 관리 — 는 모호한 task를 가지고, 주의력을 두고 경쟁하며 각 업무를 더 나쁘게 처리합니다. 세 가지 업무가 있다면 세 개의 에이전트를 빌드하십시오.

스킬 수를 적게 유지하라

에이전트의 업무에 필요한 스킬만 연결하십시오 — 대략 5개 이하입니다. 스킬은 모델이 그들의 일 줄 description을 통해 선택합니다. 연결된 스킬이 많을수록 그 선택이 어려워지며, 잘못된 스킬이나 아무것도 로드할 확률이 높아집니다. 날카로운 "이럴 때 사용하라" 설명을 가진 집중된 세트가 큰 더미보다 낫습니다.

• 각 스킬의 description은 언제 이를 사용해야 하는지를 한 줄로 명시합니다.
• 절차는 instructions(로드 온 디맨드)에 위치하며, soul(모든 턴마다 비용 발생)에는 위치하지 않습니다.
• 두 스킬이 언제 사용해야 하는지 중복된다면 병합하십시오 — 중복된 트리거는 선택을 동전 던지기로 만듭니다.

사실에 기반하라; 경계는 task에 넣으십시오

• 사실(요금, 정책, 카탈로그)은 지식베이스에 속하며, 이는 모든 턴마다 검색됩니다 — 프롬프트에 넣으면 시효가 지나가고 인용되지 않습니다. 지식베이스 빌드하기를 참조하십시오.
• 제약사항은 task 에 음의 형태로 넣으십시오: "날짜를 약속하지 말 것", "견적을 위해서는 도구를 호출하라". 음의 경계는 양의 설명보다 드리프트(drift)를 더 잘 방지합니다. 안전 규칙을 soul에 넣지 마십시오 — 플랫폼이 전역 모더레이션을 자동으로 추가합니다.
• 답변이 모델의 사전 지식(priors)이 아닌 자료에서 나와야 할 때 grounding_required를 켜십시오.

결정론을 확률에 맡기지 마라

이 플랫폼에서 가장 유용한 설계 규칙 하나: 시스템이 계산, 생성 또는 검증할 수 있는 것이면 모델에 맡기지 마십시오. 결정론적 아티팩트를 생성하라고 요청받은 모델은 크게 실패하지 않습니다 — 그럴듯한 것을 생성할 뿐입니다. 사용자는 존재하지 않는 티켓 번호, 7시간 어긋난 콜백 예약, 대비가 맞지 않는 색상 팔레트를 받게 됩니다. 오류는 발생하지 않지만, 조용히 잘못된 것입니다.

이러한 것들은 모두 실제 프로덕션 실패에서 시작되어 플랫폼 기능으로 발전했습니다:

스킬 작성에 대한 귀결: instructions는 모델에게 시설을 모방하는 법("초를 계산하고, 티켓 번호를 포맷팅")이 아니라 어떤 시스템 시설을 사용해야 하는지("run_at을 전달하고, 반환된 코드를 그대로 전달") 알려야 합니다. 결정론적 프로세스의 출력을 스크립팅하는 자신을 발견한다면, 이를 생성하는 도구를 찾으십시오 — 또는 요청하십시오.

출력에 대한 두 가지 귀결

프롬프트 규칙은 요청입니다; 사후 확인은 규칙입니다. "절대 X를 말하지 말 것"은 프롬프트에 속해야 합니다 — 발생률을 낮추지만 — 강제력이 아닙니다. 지시사항에 동의하는 모델이라도, 당신의 문구가 예상하지 못한 표현을 통해 동일한 금지된 아이디어에 도달할 수 있으며, 규칙의 각 수정은 이미 본 표현들만 잡아냅니다. 문구는 문구를 단속할 수 없습니다. 따라서 다른 질문을 하십시오: 원치 않는 문장이 완성된 답변에서 인식 가능한가? 그렇다면, 그곳에서 제거하고 프롬프트 줄도 유지하십시오.

콘텐츠를 먼저 올바르게 하십시오; 구문이 콘텐츠를 잃게 하지 마십시오. 작은 모델은 종종 올바른 선택을 한 후 파서가 거부하는 형태로 작성합니다 — 배열 대신 한 줄당 하나의 객체, 후행 쉼표, 블록을 감싼 문장. 엄격한 파싱은 misplaced brace 하나로 올바른 답변을 폐기하며, 그 증상은 모델이 충분히 능력이 없다는 것처럼 보입니다. 응답에서 하중을 지나는(load-bearing) 필드가 무엇인지 결정하십시오 — 보통 정확히 하나: id, 참조, 선택 — 그리고 그것이 도착하는 방식과 상관없이 해당 필드를 추출하십시오. 나머지 페이로드는 일반적으로 본인이 자신의 것으로 대체할 데이터이므로, 그것에 대한 엄격함은 아무것도 보호하지 않습니다.

에이전트에게 올바른 패턴만 보여라

예제를 제공할 때, 그것들이 올바른 예제가 되도록 하십시오. 올바른 예제 옆에 "여기가 잘못된 방법이다" 스니펫을 붙여넣지 마십시오 — 모델은 주의를 기울이기보다 가장 가까운 예제를 모방할 수 있습니다. 피해야 할 것을 단어로 설명하십시오; 실행 가능한 예제는 모범 사례로 유지하십시오.

검증하라 — 작성하는 것이 작동하는 것은 아니다

모든 변경 후, 의도한 대로 작동했는지 확인하십시오. 에이전트 생성이 당신이 생각하는 방식으로 구성되었다는 의미는 아닙니다; 지식베이스에 추가하는 것이 질문이 검색된다는 의미는 아닙니다.

get_agent(name="Support")                                   # 도착한 구성 확인
search_knowledge_base(kb_name="Company policy", query="…")  # 답변이 검색 가능한지 확인

빈 search 결과는 해당 질문이 "다루지 않음"으로 답변될 것임을 의미합니다 — 고객으로부터가 아닌 지금 이를 발견하십시오.

산출물을 넘겨라 — 그리고 다음 단계

모든 작업 후, 단순히 완료했다고 보고하지 마십시오. 네 가지 것을 넘겨주십시오: 당신이 생산한 것, 이를 보기 위한 클릭 가능한 콘솔 링크, 사용 방법의 한 줄, 그리고 제안된 다음 단계 — 그리고 이를 수행할 의사가 있는지 제안. 그들은 "어디서 볼 수 있나?", "어떻게 사용하나?", "다음엔 뭐야?"라고 물을 것입니다; 이를 모두 사전에 답변하십시오. 공백이 포함된 이름은 URL 인코딩하십시오.

예를 들어, 지식베이스에 문서를 가져온 후, 몇 개의 청크가 도착했는지, 위의 링크를 통해 지식 스타맵을 열어 정확히 무엇이 흡수되었는지 확인할 수 있는지, 그리고 이제 에이전트에 연결되었는지(또는 연결하는 방법) 확인하는 내용을 응답하십시오. 단순한 "완료"는 그들이 질문하게 만들 뿐입니다.

항상 다음 단계로 마무리하고, 이를 수행할 의사가 있는지 제안하십시오 — 설정은 단일 작업이 아닌 사슬입니다:

• 지식베이스를 빌드했는가? → 이를 에이전트에 연결할 의사가 있는지 제안하십시오(어느 에이전트인지 물어보십시오).
• 에이전트를 생성했는가? → 지식베이스 연결, 스킬 추가, 또는 최종 사용자가 접근할 수 있도록 공유 링크 생성을 제안하십시오(빈 공간 = 오프).
• 스킬을 작성했는가? → 이를 필요로 하는 에이전트에 연결할 의사가 있는지 제안하십시오.
• 스토리라인을 게시했는가? → 이를 에이전트의 기본값으로 설정하거나 등록 트리거를 연결할 의사가 있는지 제안하십시오.
• MCP 서버를 등록했는가? → 에이전트에 해당 도구를 부여할 의사가 있는지 제안하십시오.

"내가 만든 것은 여기 있고, 링크는 여기 있으며, 사용 방법은 여기 있고, 제가 다음에 할 일은 여기 있습니다 — 원하시나요?"는 빌드를 계속 진행하게 합니다; 단순한 "완료"는 테넌트를 혼란스럽게 만듭니다.