Documentation Index
Fetch the complete documentation index at: https://docs.fim.ai/llms.txt
Use this file to discover all available pages before exploring further.
통합 도구 추상화
FIM One의 핵심 설계 통찰력은 에이전트가 할 수 있는 모든 것이 도구라는 것입니다. 계산기, 지식 기반 쿼리, ERP API 호출, 그리고 타사 MCP 서버 모두 동일한Tool 프로토콜을 구현합니다: name, description, parameters_schema, category, 그리고 run(). 에이전트는 로컬 Python 함수를 호출하는지, 벡터 데이터베이스를 쿼리하는지, 레거시 시스템으로 프록시하는지, 또는 커뮤니티 MCP 서버를 호출하는지 알거나 신경 쓰지 않습니다. ToolRegistry에서 호출 가능한 도구의 평면 목록을 봅니다.
이는 의도적인 아키텍처 선택이며, 우연한 단순화가 아닙니다. 이는 새로운 기능 소스를 추가할 때 에이전트, 실행 엔진, 또는 컨텍스트 관리 계층을 변경할 필요가 없다는 의미입니다. 도구를 등록하면 에이전트가 사용합니다.
5가지 기능 소스가 하나의 레지스트리로 수렴합니다. 에이전트는 모두 동등하게 사용합니다.
다섯 가지 기능 소스
기본 제공 도구
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 서버 전체에 동일한 스텁 우선, 요청 시 세부 정보 패턴을 적용하는 더 광범위한 점진적 공개 아키텍처의 일부입니다.
스킬이 전역적(에이전트에 바인딩되지 않음)인 이유와 이중 모드 리소스 검색과 상호 작용하는 방식에 대한 더 자세한 내용은 에이전트 및 리소스 검색을 참조하세요.
요청별 도구 어셈블리
모든 채팅 요청은_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서브명령을 호출합니다. 점진적 공개를 참조하세요. - 스킬 주입. 사용자에게 표시되는 모든 활성 스킬이 로드됩니다 — 에이전트 선택과 관계없이. 점진적 모드에서는
ReadSkillTool이 시스템 프롬프트의 간결한 스텁으로 등록됩니다. 인라인 모드에서는 전체 스킬 콘텐츠가 직접 임베드됩니다. - CallAgent 등록(자동 모드만). 특정 에이전트가 선택되지 않으면, 모든 활성이고 표시되는 에이전트가 카탈로그로 어셈블되고
CallAgentTool을 통해 노출되어 LLM이 전문 에이전트에 작업을 위임할 수 있습니다. 위임된 에이전트는 자신의 구성에서 빌드된 전체ToolRegistry를 받지만 무한 재귀를 방지하기 위해call_agent는 제외됩니다. 특정 에이전트가 선택되면CallAgentTool은 등록되지 않습니다 — 에이전트는 전문화되어 있으며 다른 에이전트에 위임하지 않습니다. 이는 마켓플레이스 에이전트가 다른 에이전트의 개인 프롬프트에 액세스하는 것을 방지합니다. - 런타임 선택. 총 도구 수가 12개를 초과하면, 경량 LLM 호출이 이 특정 쿼리에 가장 관련성 높은 부분 집합(최대 6개)을 선택합니다.
request_tools메타 도구가 자동으로 등록되어 LLM이 초기 선택에서 필요한 도구를 놓친 경우 대화 중에 추가 도구를 동적으로 로드할 수 있습니다. 선택 실패는 치명적이지 않습니다 — 에이전트는 전체 세트로 폴백합니다. 점진적 공개를 참조하세요. - 훅 등록. 에이전트의 선언된 훅(
model_config_json.hooks에서)이 인스턴스화되고HookRegistry에 연결됩니다. 선택된 각 도구 호출은 래핑됩니다:PreToolUse훅은 실행 전에 인자를 차단하거나 다시 쓸 수 있습니다.PostToolUse훅은 관찰을 LLM으로 반환하기 전에 다시 쓸 수 있습니다. 훅은 LLM 루프 외부에서 실행되며 에이전트 지시사항으로 우회할 수 없습니다 — 훅 시스템을 참조하세요.
언제 무엇을 사용할지
| 필요 사항 | 사용 | 이유 |
|---|---|---|
| 일반 계산, 코드 실행, 텍스트 변환 | 기본 제공 도구 | 항상 사용 가능, 설정 불필요 |
| 엔터프라이즈 시스템 통합 (ERP, CRM, OA) | 커넥터 | 인증 거버넌스, 감사 추적, 작업 수준 접근 제어 |
| 인용 및 증거를 포함한 지식 검색 | 지식 베이스 | RAG 파이프라인, 근거 기반 생성, 신뢰도 점수 |
| 타사 도구 생태계 | MCP | 표준 프로토콜, 프로세스 격리, 커뮤니티 서버 |
| 조직 정책, SOP, 처리 절차 | 스킬 | 기본적으로 전역, 점진적 로딩, 가시성 범위 |
| 전문 에이전트에 작업 위임 | 에이전트 호출 | 의미론적 에이전트 라우팅, 전체 도구 상속, 병렬 실행 |
| 직접 데이터베이스 접근 | 데이터베이스 커넥터 | 스키마 인식 SQL, 선택적 읽기 전용 강제 |
| 사용자 정의 내부 도구 | MCP 또는 기본 제공 | MCP는 프로세스 격리용, 기본 제공은 긴밀한 통합용 |
실행 엔진은 직교한다
도구 시스템과 실행 엔진은 독립적인 관심사이다. 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로서의 스킬, 에이전트 위임의 상세한 설계는 에이전트 및 리소스 발견을 참조하라.
워크플로우 엔진 — 세 번째 패러다임
LLM 기반 ReAct 및 DAG 엔진과 함께 FIM One은 워크플로우 엔진을 포함합니다. 이는 고정 프로세스 자동화(승인 체인, 예약된 ETL, 다단계 파이프라인)를 위한 26가지 노드 타입을 갖춘 시각적 DAG 편집기입니다. 워크플로우는 에이전트, 커넥터, 지식 베이스, MCP 서버, LLM 호출, HTTP 요청, Python 코드 및 인간 승인 게이트를 호출할 수 있습니다. 관계는 비대칭적입니다: 워크플로우는 에이전트를 조율할 수 있지만(AGENT 노드를 통해), 에이전트는 워크플로우를 직접 호출할 수 없습니다. 유연하고 탐색적인 작업에는 에이전트를 사용하고, 결정론적이고 반복 가능한 프로세스에는 워크플로우를 사용하세요. 자세한 내용은 실행 모드를 참조하세요.라이프사이클 개요
시작.start.sh는 Alembic 마이그레이션을 실행하고, FastAPI 서버를 시작하며, 내장 도구를 발견하고, 사전 구성된 글로벌 서버에 대한 MCP 서버 연결을 설정합니다.
요청별. JWT 인증, 에이전트 구성 조회, 도구 조립(위의 8단계 파이프라인), 엔진 선택(에이전트 구성에 따른 ReAct 또는 DAG), SSE 스트리밍을 통한 실행 및 결과 지속성.
횡단 관심사. 컨텍스트 관리(5계층 토큰 예산)는 모든 LLM 호출을 오버플로우로부터 보호합니다. Hook 시스템은 모든 도구 호출을 플랫폼 제어 PreToolUse / PostToolUse 로직으로 래핑합니다 — 인간 개입 승인(FeishuGateHook), 감사 로깅 및 읽기 전용 모드 적용 뒤의 메커니즘입니다. 감사 로깅은 모든 커넥터 도구 호출을 추적합니다. 샌드박스 격리는 코드 실행 도구를 포함합니다. 2-LLM 아키텍처(스마트 + 빠름)는 계획, 실행 및 합성 전반에서 비용을 최적화합니다.
아키텍처는 각 관심사 — 도구 등록, 실행 오케스트레이션, 컨텍스트 관리, 보안 — 이 독립적으로 진화할 수 있도록 설계되었습니다. 새로운 커넥터 유형, 새로운 실행 엔진 또는 새로운 컨텍스트 전략을 시스템 전체에 걸친 연쇄 변경 없이 추가할 수 있습니다.