통합 도구 추상화
FIM One의 핵심 설계 통찰력은 에이전트가 할 수 있는 모든 것이 도구라는 것입니다. 계산기, 지식 기반 쿼리, ERP API 호출, 그리고 타사 MCP 서버 모두 동일한Tool 프로토콜을 구현합니다: name, description, parameters_schema, category, 그리고 run(). 에이전트는 로컬 Python 함수를 호출하는지, 벡터 데이터베이스를 쿼리하는지, 레거시 시스템으로 프록시하는지, 또는 커뮤니티 MCP 서버를 호출하는지 알거나 신경 쓰지 않습니다. 이는 ToolRegistry에서 호출 가능한 도구의 평면 목록을 봅니다.
이는 의도적인 아키텍처 선택이며, 우연한 단순화가 아닙니다. 이는 새로운 기능 소스를 추가할 때 에이전트, 실행 엔진, 또는 컨텍스트 관리 계층을 변경할 필요가 없다는 의미입니다. 도구를 등록하면 에이전트가 이를 사용합니다.
6개의 기능 소스가 하나의 레지스트리로 수렴됩니다. 에이전트는 모두에서 동등하게 가져옵니다. 마지막 두 개는 일치하는 쌍입니다: Skill은 동적 레시피(LLM이 단계별로 해석하는 SOP)이고, Workflow는 정적 레시피(매번 동일하게 실행되는 결정론적 그래프)입니다. 둘 다 도구(read_skill 및 run_workflow 각각)를 통해 끌어오며, 어느 것도 다른 것을 포함하지 않습니다. 이들은 동일한 런타임에서 소비되는 동료입니다.
여섯 가지 기능 소스
기본 제공 도구
discover_builtin_tools()를 통해 시작 시 자동으로 발견됩니다. core/tool/builtin/ 디렉토리에 BaseTool 서브클래스를 추가하면 별도의 설정 없이 등록됩니다. 카테고리에는 계산(calculator, python_exec), 웹(web_search, web_fetch), 파일시스템(file_ops), 일반(email_send, json_transform, template_render, text_utils)이 포함됩니다. 이들은 에이전트의 기본 능력입니다 — 항상 사용 가능하며 설정이 필요 없습니다.
지식 기반
조건부. 에이전트가kb_ids를 바인딩했을 때, 일반 kb_retrieve 도구는 특화된 검색 도구로 교체됩니다. 단순 모드에서 KBRetrieveTool은 기본 RAG 검색을 수행합니다. 근거 모드에서 GroundedRetrieveTool은 5단계 파이프라인을 실행합니다: 다중-KB 검색, 인용 추출, 정렬 점수 계산, 충돌 감지, 신뢰도 계산. 지식 기반은 에이전트 옆에 있는 별도의 하위 시스템이 아닙니다. 에이전트에 특화된 도구로 진입하며, 다른 모든 것과 동일한 Tool 프로토콜의 적용을 받습니다.
커넥터
ConnectorToolAdapter는 엔터프라이즈 시스템 작업을 도구로 래핑합니다. 각 작업은 {connector}__{action} 형식으로 명명된 도구가 되며, connector 카테고리로 분류됩니다. 어댑터는 인증 주입(bearer, API 키, 기본)이 포함된 HTTP 프록시, 작업 수준 액세스 제어(읽기/쓰기/관리자), 응답 잘라내기 및 감사 로깅을 추가합니다. 직접 데이터베이스 액세스의 경우, DatabaseToolAdapter는 선택적 읽기 전용 적용과 함께 스키마 인식 SQL 실행을 제공합니다. 커넥터는 AI와 레거시 시스템 간의 다리입니다 — 핵심 차별화 요소입니다. 전체 설계는 커넥터 아키텍처를 참조하세요.
MCP
외부 MCP 서버는 표준 프로토콜을 통해 제3자 도구를 제공합니다. 각 서버는 자체 프로세스(stdio 또는 HTTP 전송)에서 실행되며 플랫폼으로부터 완전히 격리됩니다. 도구는Tool 프로토콜로 적응되고 mcp 카테고리 아래에 등록됩니다. 관리자는 모든 사용자에 대해 자동으로 로드되는 전역 MCP 서버를 프로비저닝할 수 있습니다. MCP는 생태계 전략입니다 — 모든 MCP 호환 서버는 사용자 정의 통합 없이 작동합니다.
스킬
스킬은 재사용 가능한 표준 운영 절차(SOP)입니다 — 회사 정책, 처리 절차, 단계별 워크플로우 — 선택된 에이전트와 관계없이 전역적으로 적용됩니다. 커넥터 및 지식 베이스(특정 에이전트로 범위를 지정할 수 있음)와 달리 스킬은 가시성(개인, 조직 공유 또는 마켓 구독)에 따라 모든 사용자에 대해 항상 로드됩니다. 스킬은 두 가지 주입 모드를 지원합니다 — 점진적(기본값) 및 인라인 —SKILL_TOOL_MODE로 제어됩니다. 점진적 모드에서는 컴팩트한 스텁이 시스템 프롬프트에 나타나고 LLM은 필요에 따라 read_skill(name)을 호출합니다. 이는 스킬, 커넥터, 데이터베이스 및 MCP 서버 전체에 동일한 스텁 우선, 요청 시 세부 정보 패턴을 적용하는 더 광범위한 점진적 공개 아키텍처의 일부입니다.
스킬이 전역적(에이전트에 바인딩되지 않음)인 이유와 이중 모드 리소스 검색과 상호 작용하는 방식에 대한 더 자세한 내용은 에이전트 및 리소스 검색을 참조하세요.
Workflows
Workflow는 Skill의 정적 레시피입니다: 에이전트가 서브태스크를 매번 동일하게 실행하고 감사 추적을 남겨야 할 때 도달하는 결정론적 DAG입니다(예약된 조정, 다단계 승인 불필요 파이프라인). Skill과 마찬가지로 실행 가능한 Workflow는 가시성에 따라 사용자별로 전역적으로 로드되며 — 에이전트 선택과 무관하게 — 단일run_workflow(name, inputs) 도구를 통해 노출됩니다. 각 workflow의 입력 필드는 컴팩트한 시스템 프롬프트 스텁으로 광고되며, LLM은 태스크가 이에 매핑될 때 이름으로 하나를 가져옵니다.
활성 상태이고 인간 승인(HUMAN_INTERVENTION) 노드가 없는 Workflow만 인라인 실행 가능합니다 — 수 분 또는 수 시간 동안 차단되는 게이트는 에이전트 턴 내부에 있을 수 없으므로 이러한 Workflow는 Workflows 페이지에서만 트리거됩니다. 인라인 실행은 workflow 소유자로 실행되며(구독된 Workflow는 게시자의 바인딩된 자격증명 사용), 감사 추적을 위해 WorkflowRun을 유지하고, 재진입 가드 및 중첩 깊이 상한선으로 보호되어 Workflow의 AGENT 노드가 무한 호출 사이클을 시작할 수 없습니다.
요청별 도구 어셈블리
모든 채팅 요청은_resolve_tools()의 필터링 파이프라인을 통해 신선한 도구 세트를 어셈블합니다. 이는 정적 구성이 아니라 에이전트의 설정, 사용자의 신원, 그리고 사용 가능한 커넥터와 MCP 서버를 기반으로 요청별로 계산됩니다.
8가지 단계:
- 기본 검색.
discover_builtin_tools()는 모든 기본 제공 도구를 로드하며, 대화의 샌드박스로 범위가 지정됩니다. - 에이전트 카테고리 필터.
filter_by_category(*agent.tool_categories)는 에이전트가 사용할 수 있는 카테고리만으로 제한합니다. - KB 주입. 에이전트가
kb_ids를 가지고 있으면, 일반 검색 도구는 검색 모드에 따라KBRetrieveTool또는GroundedRetrieveTool로 대체됩니다. - 커넥터 로딩. 에이전트 제약 모드에서는 에이전트의 바인딩된 커넥터만 로드됩니다. 자동 검색 모드(에이전트 미선택)에서는 사용자에게 표시되는 모든 커넥터가 로드됩니다. API 커넥터(
ConnectorMetaTool)와 데이터베이스 커넥터(DatabaseMetaTool) 모두 기본적으로 점진적 공개를 사용합니다 — 시스템 프롬프트의 경량 스텁, 필요 시 전체 스키마 로드. - MCP 로딩. 사용자의 개인 MCP 서버와 관리자가 프로비저닝한 글로벌 MCP 서버가 로드되고 연결됩니다. 점진적 모드(기본값)에서는 단일
MCPServerMetaTool이 모든 서버를 통합합니다. LLM은 필요에 따라discover및call서브명령을 호출합니다. 점진적 공개를 참조하세요. - Skills + Workflows 주입. 사용자에게 표시되는 모든 활성 Skills는 에이전트 선택과 관계없이 로드됩니다. 점진적 모드에서는
ReadSkillTool이 시스템 프롬프트의 컴팩트 스텁으로 등록됩니다. 인라인 모드에서는 전체 Skill 콘텐츠가 직접 임베딩됩니다. 같은 단계에서 모든 활성이고 인라인 실행 가능한 Workflows를 로드하고RunWorkflowTool을 워크플로우당 하나의 스텁(이름, 설명, 입력 필드)으로 등록합니다. 인간 승인 노드를 포함하는 Workflows는 여기서 건너뜁니다. - CallAgent 등록(자동 모드만). 특정 에이전트가 선택되지 않으면, 모든 활성이고 표시되는 에이전트가 카탈로그로 어셈블되고
CallAgentTool을 통해 노출되어 LLM이 전문 에이전트에게 작업을 위임할 수 있도록 합니다. 위임된 에이전트는 자신의 구성에서 빌드된 전체ToolRegistry를 받지만 무한 재귀를 방지하기 위해call_agent는 제외합니다. 특정 에이전트가 선택되면CallAgentTool은 등록되지 않습니다 — 에이전트는 특화되어 있으며 다른 에이전트에게 위임하지 않습니다. 이는 마켓플레이스 에이전트가 다른 에이전트의 개인 프롬프트에 접근하는 것을 방지합니다. - 런타임 선택. 총 도구 수가 12를 초과하면, 경량 LLM 호출이 이 특정 쿼리에 가장 관련성 높은 부분 집합(최대 6개)을 선택합니다.
request_tools메타 도구가 자동으로 등록되어 LLM이 초기 선택에서 필요한 도구를 놓친 경우 대화 중에 추가 도구를 동적으로 로드할 수 있도록 합니다. 선택 실패는 치명적이지 않습니다 — 에이전트는 전체 세트로 폴백합니다. 점진적 공개를 참조하세요. - 훅 등록. 에이전트의 선언된 훅(
model_config_json.hooks에서)이 인스턴스화되고HookRegistry에 연결됩니다. 선택된 각 도구 호출은 래핑됩니다:PreToolUse훅은 실행 전에 인자를 차단하거나 다시 쓸 수 있습니다.PostToolUse훅은 관찰을 LLM으로 반환하기 전에 다시 쓸 수 있습니다. 훅은 LLM 루프 외부에서 실행되며 에이전트 지시사항으로 우회할 수 없습니다 — 훅 시스템을 참조하세요.
언제 무엇을 사용할지
이 범주들은 상호 배타적이지 않습니다. 단일 에이전트는 한 번의 대화에서 다섯 가지 기능 소스를 모두 사용할 수 있습니다 — 불만 처리 SOP를 위해 Skill을 로드하고, 정책 문서를 위해 지식 베이스를 쿼리하고, ERP를 확인하기 위해 커넥터를 호출하고, 전문 에이전트에 분석을 위임하고 (자동 모드), built-in 도구를 사용하여 결과를 포맷합니다.
실행 엔진은 직교한다
도구 시스템과 실행 엔진은 독립적인 관심사이다. LLM 기반 엔진(ReAct 및 DAG)은 동일한ToolRegistry에서 도구를 사용한다. 엔진의 선택은 도구가 어떻게 조율되는지에 영향을 미치며, 사용 가능한 도구에는 영향을 미치지 않는다.
ReAct는 반복적인 도구 루프이다. 에이전트가 추론하고, 도구를 선택하고, 결과를 관찰하고, 완료될 때까지 반복한다. 다음 단계가 이전 결과에 따라 달라지는 탐색적이고 대화형인 작업에 탁월하다. 루프는 최대 50회 반복 실행되며 ContextGuard를 통한 반복별 컨텍스트 관리가 이루어진다. 구현 세부 사항은 ReAct 엔진을 참조하라.
DAG는 목표를 2-6개의 병렬 단계로 분해한다. 각 단계는 독립적인 ReAct 에이전트를 실행한다. PlanAnalyzer는 목표가 달성되었는지 평가하고, 그렇지 않으면 파이프라인이 자동으로 재계획한다(최대 3라운드). DAG는 동시에 실행할 수 있는 명확한 하위 작업이 있는 작업에 탁월하다 — “세 가지 소스를 검색하고 결과를 비교”하는 작업이 세 번의 검색 시간이 아닌 한 번의 검색 시간에 완료된다. 전체 파이프라인은 DAG 엔진을 참조하라.
두 엔진은 인프라를 공유한다: 신뢰할 수 있는 구조화된 출력을 위한 structured_llm_call, 토큰 예산 강제를 위한 ContextGuard, 도구 해석을 위한 ToolRegistry. 새로운 도구를 추가하려면 두 엔진 모두에 대한 변경이 필요 없다. 새로운 엔진을 추가하려면(필요한 경우) 도구 시스템에 대한 변경이 필요 없다.
두 엔진은 또한 자동 모드(에이전트 미선택)에서 CallAgentTool을 통한 에이전트 위임을 지원한다. 기본 함수 호출 모드에서 LLM은 단일 턴에서 여러 call_agent 호출을 호출할 수 있으며, 이는 asyncio.gather를 통해 동시에 실행된다. 각 위임된 에이전트는 자신의 ToolRegistry를 받고 완전한 실행 단위로 실행된다. 에이전트 발견, 글로벌 SOP로서의 스킬, 에이전트 위임의 상세한 설계는 에이전트 및 리소스 발견을 참조하라.
Workflow Engine — 세 번째 패러다임
LLM 기반 ReAct 및 DAG 엔진과 함께 FIM One은 Workflow Engine을 포함합니다. 이는 9가지 핵심 노드 유형(Start, End, LLM, Condition Branch, Agent, Knowledge Retrieval, Connector, MCP, Human Intervention)을 갖춘 시각적 DAG 편집기로, 고정 프로세스 자동화를 위해 설계되었습니다. 유연하고 탐색적인 작업에는 Agents를 사용하고, 결정론적이고 반복 가능한 프로세스에는 Workflows를 사용하세요. 자세한 내용은 Execution Modes를 참조하세요. 두 가지는 양방향으로 구성되지만, 각 방향은 단일 런타임인 에이전트 루프를 통해 라우팅됩니다. 두 번째 실행 엔진을 통하지 않습니다:- Workflow → Agent. Workflow의
AGENT노드는 에이전트를 하나의 결정론적 단계로 실행합니다. - Agent → Workflow. 에이전트(또는 이를 따르는 Skill)는
run_workflow를 호출하여 결정론적으로 실행되어야 하는 하위 작업을 위임합니다.
run_workflow를 호출하는 것을 의미합니다. 모든 호출은 에이전트를 통과하므로 호출 그래프는 별 모양이지 메시입니다. 역간선은 제한됩니다(read_skill은 텍스트만 반환하고, call_agent와 run_workflow는 깊이 상한과 재진입 보호를 수행합니다).
같은 그림의 두 가지 해석: 도구는 푸시되지 않고 풀링됩니다(LLM이 선택하지 않은 Skill이나 Workflow는 절대 실행되지 않습니다. 이것이 동적 기능이 쿼리가 하나와 일치할 때까지 보이지 않는 것처럼 느껴질 수 있는 이유입니다), 그리고 Skills와 Workflows는 피어로서 서로 중첩되지 않고 하나의 런타임을 통해 라우팅됩니다.
라이프사이클 개요
시작.start.sh는 Alembic 마이그레이션을 실행하고, FastAPI 서버를 시작하며, 내장 도구를 발견하고, 사전 구성된 글로벌 서버에 대한 MCP 서버 연결을 설정합니다.
요청별. JWT 인증, 에이전트 구성 조회, 도구 조립(위의 8단계 파이프라인), 엔진 선택(에이전트 구성에 따른 ReAct 또는 DAG), SSE 스트리밍을 통한 실행 및 결과 지속성.
횡단 관심사. 컨텍스트 관리(5계층 토큰 예산)는 모든 LLM 호출을 오버플로우로부터 보호합니다. Hook 시스템은 모든 도구 호출을 플랫폼 제어 PreToolUse / PostToolUse 로직으로 래핑합니다 — 인간 개입 승인(FeishuGateHook), 감사 로깅 및 읽기 전용 모드 적용 뒤의 메커니즘입니다. 감사 로깅은 모든 커넥터 도구 호출을 추적합니다. 샌드박스 격리는 코드 실행 도구를 포함합니다. 2-LLM 아키텍처(스마트 + 빠름)는 계획, 실행 및 합성 전반에서 비용을 최적화합니다.
아키텍처는 각 관심사 — 도구 등록, 실행 오케스트레이션, 컨텍스트 관리, 보안 — 이 독립적으로 진화할 수 있도록 설계되었습니다. 새로운 커넥터 유형, 새로운 실행 엔진 또는 새로운 컨텍스트 전략을 시스템 전체에 걸친 연쇄 변경 없이 추가할 수 있습니다.