견고한 지원 에이전트 생성

빌드하기 전에 — 발견하십시오. 무작정 실행하지 마십시오. 테넌트에게 그들의 업무, 사용하는 자료, 해당 업무가 실행하는 절차, 그리고 반드시 연결해야 하는 시스템에 대해 인터뷰하십시오. 전체 설정(에이전트 + 지식 베이스 + 스킬 + 필요시 MCP)을 계획하고, 아무것도 생성하기 전에 시뮬레이션해 보십시오. 아래 단계는 그 이후에 실행하는 것입니다 — 빌드 전 발견을 참조하십시오.

원칙 — 에이전트 하나당 하나의 업무. 이 에이전트에게 단일하고 명확히 경계가 정해진 작업을 부여하십시오. 비즈니스에 세 가지 업무(고객 지원 및 영업 및 일정 관리)가 있다면, 세 개의 에이전트를 구축하십시오. "모든 것을 처리하는" 에이전트는 각 작업을 더 나쁘게 처리합니다. 자세한 내용은 디자인 원칙을 참조하십시오.

에이전트는 soul + task + tools + skills + knowledge_bases입니다. soul은 정체성과 목소리이며, task는 업무와 그 경계입니다. 둘 다 시스템 프롬프트의 고정 접두사(fixed prefix)에 포함됩니다.

1. 연결할 수 있는 항목 확인

list_tools()             # tools available to this tenant (including connected MCP tools)
list_knowledge_bases()   # knowledge bases you can mount

2. 생성하기

기본값으로 켜져 있으므로 요청할 필요가 없습니다. 새 에이전트는 답변하기 전에 두세 가지 사실을 필요로 할 때 탭 가능한 단일/다중 선택 양식(form)(ask_forms)을 이미 응답할 수 있으며, 차트(chart)(compute_chart는 기본 도구 목록에 있음)를 이미 그릴 수 있습니다. 2026-08-03 이전까지는 둘 다 기본값이 꺼져 있었고, 생성 호출에는 첫 번째 항목에 대한 매개변수가 없었습니다. 따라서 그 이전에 구축된 에이전트는 둘 다 없으며, update_agent(ask_forms=True, add_tools=["compute_chart"])를 사용하여 최신 상태로 업데이트할 수 있습니다.

tools=[...]를 전달하면 기본 목록에 추가하는 것이 아니라 바꾸므로, 도구 목록을 전달할 때는 compute_chart를 직접 포함해야 합니다.

이름은 소문자입니다. 이름은 보이는 것뿐만 아니라 11개의 테이블이 에이전트를 참조하는 데 사용합니다(공유, 세션, 스토리라인, 채널 바인딩, 사용량). 따라서 Pip와 pip는 모든 테이블에서 서로 다른 에이전트이며, 사용자에게는 동일한 에이전트입니다. 새 이름은 저장 시 소문자로 변환됩니다. 그 방식으로 작성하면 조정할 사항이 없습니다. 또한 이는 공개 URL이 아닙니다. 공개 URL은 alias입니다.

create_agent(
  name="support",                  # lower-case; the platform lower-cases it anyway
  alias="support",                 # public human-readable URL slug — set one (url-safe, lowercase)
  soul="You are the support assistant for Acme Loans. Professional and warm.",
  task="Answer questions about mortgage products and the application process. "
       "Never promise a disbursement date; never give legal or tax advice; "
       "for any specific quote, call a tool — do not answer from memory.",
  tools=["web_search"],
  knowledge_bases=["company-policy"],   # use the KB's returned slug name (see below)
  published=True,
)

• **alias**는 에이전트의 공개 가독 주소 세그먼트({public_base}/t/<tenant>/<alias>)입니다. 기억하기 쉬운 링크를 제공할 수 있도록 설정하십시오. url-safe 슬러그로 정규화되며, 충돌이 발생하면 alias_result에서 반환됩니다.
• 시스템 도구는 기본값으로 켜져 있습니다. 새 에이전트는 자동으로 current_time, ip_geo 및 weather(내장 system MCP)를 받습니다. 나열할 필요가 없습니다. tools는 추가 도구를 위한 것입니다.
• URL의 이름은 슬러그화됩니다. 지식 베이스 이름은 생성 시 url-safe 슬러그가 됩니다("Company Policy" → company-policy). 입력한 이름이 아닌 반환된 이름으로 연결하십시오.

3. 적용된 내용 확인

get_agent(name="Support")   # writing it doesn't mean it looks the way you intended

경계는 task에 속합니다. 부정적 제약("절대 약속하지 마십시오…")은 긍정적 설명보다 유동성을 더 잘 방지합니다. 안전 규칙을 soul에 넣지 마십시오. 플랫폼은 전역 모더레이션을 자동으로 추가합니다. 나중에 하나의 필드를 변경하려면 update_agent(name, field=…)를 사용하십시오. 병합되므로 나머지 필드는 비워지지 않습니다.

4. 게시 — 방법을 묻고, 그 후 접근 가능하게 만들기

"완료"라고 말하기 전에, 테넌트에게 고객이 에이전트에 어떻게 접근해야 하는지 물어본 후, create_share로 해당 채널을 연결하십시오(실제 열 수 있는 링크를 반환합니다. "게시되었습니다"가 아닌 링크를 제공하십시오).

create_share(agent_name="Support", label="Website widget")
# → { token, chat_url, qr_url, embed_snippet, pretty_url, … }

응답에 pretty_url(…/t/<tenant-alias>/<agent-alias>)이 포함되어 있으면, 그것이 인간을 위한 링크입니다. 가독성이 뛰어나며 토큰 회전 동안 안정적입니다. null인 경우, 토큰 링크를 배송하기 전에 누락된 alias를 설정하십시오(create_agent(alias=…) / PUT /agents/{name}/alias; 테넌트 alias는 콘솔 → 설정에서 확인). chat_url은 임베드 및 QR 코드에 여전히 적합합니다.

• 웹사이트 없음 — 링크 또는 QR만 필요(프리랜서, 상점, 전단지, 명함): chat_url(전체 화면 호스팅 채팅 페이지 — 사이트 불필요)과 qr_url(인쇄할 수 있는 QR)을 제공하십시오. 익명입니다: 로그인이 필요 없으며, 각 방문자는 브라우저로 기억되므로 정기 방문자는 인식됩니다.
• 자사 웹사이트: 플로팅 위젯을 위해 </body> 앞에 한 줄을 넣는 embed_snippet을 제공하거나, 링크/iframe용 chat_url을 제공하십시오.
• Telegram / WhatsApp: 콘솔에서 채널별로 설정하십시오(Agent → 통합 → Telegram / WhatsApp). 해당 위치로 안내하십시오.

보고하십시오. 실제 링크(chat_url, 사이트가 없는 경우 qr_url)를 제공하여 지금 바로 열고 테스트할 수 있게 하십시오. 또한 에이전트의 콘솔 페이지를 제공하여 검토하게 하십시오 — https://console.agent4.io/#/agents/Support. "게시되었습니다"가 아닌 링크입니다.