AI 에이전트

AI 에이전트는 여러 단계로 작업하는 어시스턴트입니다. 대화를 읽고, 계획을 세우고, 도구(AI 도구, MCP 도구, 지식 베이스 검색)를 호출하고, 결과를 확인한 다음, 답변을 얻을 때까지 모델을 다시 호출합니다. AI 채팅 완성 생성 노드는 모델을 한 번 호출하고 응답하지만, AI 에이전트 노드는 설정한 한도 안에서 여러 번의 모델 및 도구 호출을 계속한 뒤 답변할 수 있습니다.

요청에 여러 단계가 필요할 때 에이전트를 사용하세요. 예를 들어 "고객의 주문을 찾아 배송 상태를 확인하고 새 날짜를 제안하기" 같은 경우입니다. 지침과 지식 베이스만으로 바로 답변하는 경우에는 AI 노드가 더 간단하고 저렴합니다.

구성 요소

구성 요소	설명	설정 위치
AI 하니스	에이전트 루프를 실행하는 엔진입니다. MonoChat 자체 엔진, 에이전트 SDK 또는 호스팅된 에이전트 서비스가 있습니다.	설정 › 자동화 › AI 하네스
모델	에이전트가 사고하는 데 사용하는 AI 모델로, 메인 모델, 선택 사항인 대체 모델, 선택 사항인 빠른 모델이 있습니다. 호스팅 하니스는 대신 해당 제공업체의 모델을 사용합니다.	AI 에이전트 노드
도구	AI 범위, AI 도구 함수, MCP 도구.	AI 에이전트 노드
실행 예산	각 실행의 모델 호출, 도구 호출, 토큰, 소요 시간, 재시도에 대한 한도입니다.	AI 에이전트 노드
실행	에이전트의 한 번의 실행입니다. 모든 실행은 AI 에이전트 실행 내역에 기록됩니다.	노드 또는 API로 생성

AI 하네스

설정 › 자동화 › AI 하네스에는 에이전트를 실행할 수 있는 하니스가 나열됩니다. MonoChat이 모든 워크스페이스에 제공하는 하니스와 자체 자격 증명으로 추가한 하니스입니다.

하니스	실행 위치	사용하는 모델	추가하는 주체
MonoChat Native	MonoChat 내부	사용자의 AI 모델	MonoChat
OpenAI Agents SDK	MonoChat 내부	사용자의 AI 모델	MonoChat
Claude Agent SDK	MonoChat 에이전트 러너	사용자의 AI 모델	MonoChat
pi	MonoChat 에이전트 러너	사용자의 AI 모델	MonoChat
OpenAI Agents API	OpenAI 클라우드	하니스의 허용된 모델	사용자, OpenAI API 키 사용(MonoChat이 하나 제공할 수도 있음)
Claude Managed Agents	Anthropic 클라우드	하니스의 허용된 모델	사용자, Anthropic API 키 사용(MonoChat이 하나 제공할 수도 있음)
커스텀 엔드포인트	사용자의 자체 서버	사용자의 AI 모델(선택 사항)	사용자, 엔드포인트와 시크릿 사용

MonoChat에서 실행되는 하니스는 MonoChat이 제공하며, 워크스페이스에서는 자체 자격 증명을 사용하는 하니스만 추가할 수 있습니다. Claude Agent SDK와 pi는 MonoChat의 에이전트 러너가 필요합니다. 에이전트 러너가 설정되지 않은 곳에서는 이 하니스로 실행하면 "이 서버에서는 이 하니스를 사용할 수 없습니다."라는 메시지와 함께 실패합니다.

하니스와 관계없이 MonoChat이 제어권을 유지합니다. 사용자의 AI 모델을 사용하는 하니스의 모든 모델 호출은 MonoChat을 거치며(따라서 청구와 예산이 적용됩니다), 모든 도구 호출은 워크스페이스의 함수, MCP 도구, AI 범위를 실행하고, 예산은 모든 하니스에서 적용됩니다.

하니스 추가

설정 › 자동화 › AI 하네스로 이동하여 +(만들기)를 클릭합니다.
이름을 입력하고, 원하면 설명도 입력합니다.
하니스를 선택합니다. 각 옵션에 실행 위치가 표시됩니다.
자격 증명에서 하니스에 필요한 정보를 입력합니다.
- OpenAI Agents API, Claude Managed Agents: API 키.
- 커스텀 엔드포인트: 엔드포인트와 API 키.
호스팅 하니스의 경우 허용된 모델을 입력합니다. 제공업체의 모델 이름(예: OpenAI 또는 Anthropic 모델 ID)을 입력하세요. 모델 추가로 최대 10개까지 모델을 추가할 수 있습니다. 이 하니스의 에이전트는 이 목록에서만 선택할 수 있습니다.
저장을 클릭합니다.

하니스를 수정할 때는 하니스 유형을 변경할 수 없으며, 키 필드에는 **API 키 (저장된 키를 유지하려면 비워 두세요)**라고 표시됩니다.

Claude Managed Agents

이 유형의 하니스를 처음 사용할 때 MonoChat은 해당 Anthropic 계정에 에이전트 하나와 환경 하나를 만들고 이후에 재사용합니다.

커스텀 엔드포인트

커스텀 엔드포인트 하니스는 자체 호스팅 에이전트 같은 사용자의 서비스로 실행을 보냅니다. 각 실행마다 MonoChat은 Authorization: Bearer <API Key>와 함께 <Endpoint>/runs로 POST를 보냅니다. 본문에는 실행 ID, 지침, 입력, 대화 메시지, 예산, 모델 별칭(agent-main, agent-fallback, agent-fast), 그리고 이 실행용 토큰이 포함된 URL 세 개가 들어 있습니다.

노드의 AI 모델을 호출하고 예산을 적용하는 모델 게이트웨이(OpenAI 호환 …/v1 및 Anthropic 호환 기본 URL),
실행의 도구를 제공하는 MCP 서버,
서비스가 결과를 보고하는 이벤트 URL(result와 함께 completed, 또는 error와 함께 failed).

실행이 끝나면 해당 실행의 토큰은 더 이상 작동하지 않습니다.

AI 에이전트 노드

플로우 디자이너의 하이브리드 노드 아래에 있는 AI 에이전트 노드로 플로우에 에이전트를 추가합니다. 노드를 추가하고 연결하는 방법은 플로우를 참조하세요.

필드

섹션	필드	설명
	이름	캔버스에 표시되는 노드 이름입니다.
	AI 하니스	필수입니다. 에이전트를 실행하는 하니스입니다.
	지침	에이전트의 시스템 지침으로, 역할, 어조, 규칙, 해도 되는 일과 하면 안 되는 일을 담습니다.
	작업 (에이전트 지침에 추가되며 태그를 사용할 수 있음)	이 노드가 에이전트에게 요청하는 작업입니다. 지침 뒤에 추가되며, 예를 들어 고객 데이터를 포함하기 위해 AI 노드의 프롬프트와 같은 태그를 사용할 수 있습니다.
모델	메인 모델	에이전트가 사용하는 모델입니다. 커스텀 엔드포인트를 제외한 모든 하니스에서 필수입니다.
	대체 모델 (소프트 한도 이후)	모델 호출이 소프트 한도에 도달하면 에이전트가 전환하는 모델로, 보통 더 저렴하거나 빠른 모델입니다.
	빠른 모델 (가벼운 백그라운드 작업)	하니스가 가벼운 백그라운드 호출에 사용할 수 있는 모델입니다.
	모델 (하니스의 허용된 모델 중 하나)	호스팅 하니스에서는 위의 세 필드 대신 표시됩니다.
에이전트 세션	대화	기존 에이전트 세션 이어서 진행(기본값) 또는 새 에이전트 세션 시작. 에이전트 세션을 참조하세요.
	작업 키 (작업별로 에이전트 세션 분리)	선택 사항입니다. 같은 대화 안에서 키마다 별도의 에이전트 세션을 유지합니다. 예: `booking`, `support`.
	메시지 기록 한도	에이전트가 받는 대화 메시지의 수입니다.
	음성-텍스트 변환 AI 모델	대본 기능이 있는 모델입니다. 대화의 음성 메시지가 텍스트로 에이전트에 전달됩니다.
도구 설정	AI 범위	에이전트가 검색할 수 있는 지식 베이스입니다. 지식 베이스 검색 도구로 에이전트에 제공됩니다.
	AI 도구	에이전트가 호출할 수 있는 AI 도구 유형의 함수입니다.
	AI MCP 클라이언트 콘텐츠 도구 설정하기	MCP 도구를 추가하는 패널을 엽니다. MCP 클라이언트를 참조하세요.
메시지	중간 메시지를 고객에게 전달	기본적으로 꺼져 있습니다. 켜면 에이전트가 작업 중에 작성하는 내용(예: "주문을 확인해 보겠습니다")이 고객에게 전송되고, 끄면 팀만 볼 수 있는 귓속말 메시지로 세션에만 추가됩니다.
	답변 보내기	기본적으로 켜져 있습니다. 에이전트의 최종 답변을 고객에게 보냅니다. 답변을 플로우 안에서만 사용하려면 끄세요.
실행 예산	최대 모델 호출 수	기본값 4.
	소프트 한도: 모델 호출	선택 사항입니다. 모델 호출이 이 횟수에 도달하면 에이전트가 대체 모델로 전환합니다. 최대 모델 호출 수보다 낮아야 하며 대체 모델이 필요합니다.
	최대 도구 호출 수	기본값 6. `0`이면 에이전트가 도구를 호출하려는 즉시 실행이 예산 초과로 종료됩니다.
	최대 총 토큰 수	기본값 20000. 실행 중 모든 모델 호출의 입력 및 출력 토큰입니다.
	최대 실행 시간(초)	기본값 30.
	최대 재시도 횟수	기본값 2. 실패한 모델 호출을 재시도하는 횟수입니다.

팁

변하지 않는 규칙은 지침에, 이 단계의 구체적인 작업은 작업에 작성하세요. 그러면 플로우의 여러 AI 에이전트 노드가 같은 지침을 공유하고 작업만 다르게 할 수 있습니다.

경고

호스팅 하니스는 대체 모델로 전환할 수 없으므로 소프트 한도를 지원하지 않습니다. 호스팅 하니스에서는 소프트 한도: 모델 호출을 비워 두세요.

플로우가 노드에 도달하면

MonoChat이 잔액과 노드 설정을 확인하고 실행을 시작합니다. 실행은 대기 중이었다가 실행 중이 됩니다. 플로우 인스턴스는 노드에서 대기합니다.
에이전트는 지침과 작업을 받으며, 플로우가 대화에 속해 있으면 메시지 기록 한도까지의 대화 메시지도 받습니다. 음성 메시지는 텍스트로 변환됩니다.
에이전트는 답변을 얻거나 한도에 도달할 때까지 모델과 도구를 호출합니다. 도구 호출 사이에 작성한 텍스트는 중간 메시지로 처리됩니다.
실행이 끝나면 다음과 같이 처리됩니다.
- 완료됨 상태이고 답변 보내기가 켜져 있으면 답변이 고객에게 전송됩니다. 긴 답변이 채널의 제한(WhatsApp은 4096자)을 초과하면 여러 메시지로 나뉩니다.
- 그 외의 방식으로 종료되면 팀을 위해 "AI 에이전트 실행이 종료되었습니다: status. error"라는 귓속말 메시지가 세션에 추가됩니다.
플로우는 실행이 종료된 방식에 해당하는 출력으로 계속 진행합니다.

같은 에이전트 세션의 실행은 순서대로 하나씩 처리됩니다.

출력

출력	시점
완료됨	에이전트가 답변과 함께 완료했습니다.
예산 초과	실행이 최대 모델 호출 수, 최대 도구 호출 수 또는 최대 총 토큰 수를 모두 사용했습니다.
시간 초과	실행이 최대 실행 시간(초)에 도달했습니다.
혐오, 탈옥, 자해, 성적 콘텐츠, 폭력	모델 제공업체의 콘텐츠 필터가 이 카테고리 때문에 실행을 중단했습니다. AI 노드에 있는 출력과 같습니다.
실패 시	그 밖의 이유로 실행이 실패했거나 취소되었습니다. 이러한 출력이 생기기 전에 저장된 노드에서는 콘텐츠 필터 중단도 여기로 이동합니다. 이러한 노드는 열어서 저장하면 새 출력이 생깁니다.

최소한 완료됨과 실패 시를 연결하세요. 일반적인 패턴은 예산 초과, 시간 초과, 실패 시를 대화 할당 노드로 보내 팀원이 이어받도록 하는 것입니다.

에이전트 세션

에이전트 세션은 실행 간에 유지되는 에이전트의 기억입니다. MonoChat은 대화, 하니스, 작업 키마다 활성 에이전트 세션을 하나씩 유지합니다.

기존 에이전트 세션 이어서 진행은 기존 세션을 재사용하므로 에이전트가 이전에 하던 곳에서 이어서 진행합니다. 호스팅 하니스에서는 제공업체 자체의 세션도 이어집니다.
새 에이전트 세션 시작은 활성 세션을 닫고 새로 시작합니다. 예를 들어 새로운 주제를 시작할 때 사용합니다.
작업 키를 사용하면 같은 대화 안에서 독립된 세션을 나란히 유지할 수 있습니다.

청구

MonoChat이 제공하는 AI 모델의 모델 호출은 평소처럼 잔액에서 청구됩니다. 직접 만든 모델의 호출은 제공업체가 청구합니다.
MonoChat이 제공하는 하니스는 실행당, 분당, 도구 호출당 자체 요금을 추가할 수 있으며, 호스팅 하니스의 경우 제공업체가 보고하는 토큰도 청구됩니다. 이는 거래 내역에 AI 에이전트 실행, AI 에이전트 실행 시간, AI 에이전트 도구 호출, AI 토큰 카테고리로 표시됩니다.
자체 자격 증명으로 추가한 하니스에는 MonoChat 요금이 없으며, 제공업체가 사용자에게 청구합니다.
잔액이 부족하면 실행이 시작되지 않습니다.

AI 에이전트 실행 완료됨 이벤트

AI 에이전트 실행 완료됨은 이벤트 노드입니다. 고객과 연결된 실행이 플로우에서 시작되었든 대화와 함께 API로 시작되었든 종료되면 실행됩니다. 다른 이벤트 노드처럼 선택 사항인 조건과 시간 초과 설정이 있습니다. 에이전트 실행 후 결과를 기록하거나 팀에 알리는 등 별도의 플로우를 시작하는 데 사용하세요.

코드에서 에이전트 시작

커스텀 함수와 API 클라이언트는 다음 메서드로 에이전트를 실행할 수 있습니다(권한 자동화 AI 에이전트 실행 시작 / 조회 / 취소).

메서드	기능
`business.tenants.automation.ai.aiAgentRuns.create`	실행을 시작합니다. `aiAgentRunId`와 `aiAgentSessionId`를 반환합니다.
`business.tenants.automation.ai.aiAgentRuns.show`	상태, 사용량, 단계, 결과와 함께 실행(`_id`)을 반환합니다.
`business.tenants.automation.ai.aiAgentRuns.cancel`	대기 중이거나 실행 중인 실행(`_id`)을 취소합니다.

create는 aiHarnessClientId, input(작업), 선택적으로 sessionId(대화에서 작업하기 위해), aiAgentSessionId, taskKey, isNewSession, 그리고 노드와 같은 설정을 가진 options(instructions, aiModelClientId, fallbackAiModelClientId, fastAiModelClientId, harnessModel, toolCustomFunctionIds, aiScopeIds, aiMcpClientDatas, messageHistoryLimit, speechToTextAiModelClientId, forwardIntermediateMessages, willSendAnswer, 그리고 필수인 budget)를 받습니다. API에서는 forwardIntermediateMessages와 willSendAnswer의 기본값이 false입니다.

const { aiAgentRunId } = await sdk.method({ name: 'business.tenants.automation.ai.aiAgentRuns.create' }).callAsync({
  payload: {
    aiHarnessClientId: 'HARNESS_ID',
    input: 'Summarise the open orders of this customer.',
    sessionId: 'SESSION_ID',
    options: {
      instructions: 'You are the order assistant of our store.',
      aiModelClientId: 'MODEL_ID',
      toolCustomFunctionIds: ['FUNCTION_ID'],
      budget: { maxLlmCalls: 4, maxToolCalls: 6, maxTotalTokens: 20000, maxDurationSeconds: 30, maxRetries: 2 },
    },
  },
})

실행은 비동기로 처리됩니다. 나중에 show로 조회하거나 AI 에이전트 실행 완료됨 이벤트로 대응하세요. sessionId가 없으면 이전 호출이 반환한 aiAgentSessionId를 전달하지 않는 한 호출마다 새 에이전트 세션이 시작되며, 전달하면 에이전트는 해당 에이전트 세션의 이전에 완료된 실행을 기록으로 볼 수 있습니다. 함수에서 메서드를 호출하는 방법은 메서드를 참조하세요.

권한

권한	허용 범위
자동화 AI 하네스 조회 / 생성 / 수정 / 삭제	AI 하네스 관리
자동화 AI 에이전트 실행 조회	AI 에이전트 실행 내역 확인
자동화 AI 에이전트 실행 시작	`aiAgentRuns.create` 호출
자동화 AI 에이전트 실행 취소	`aiAgentRuns.cancel` 호출

역할을 참조하세요.

구성 요소​

AI 하네스​

하니스 추가​

커스텀 엔드포인트​

AI 에이전트 노드​

필드​

플로우가 노드에 도달하면​

출력​

에이전트 세션​

청구​

AI 에이전트 실행 완료됨 이벤트​

코드에서 에이전트 시작​

권한​

관련 문서​