<h1 align="center">Agentfootprint</h1>
<p align="center">
<strong>기록에 근거하여 검증할 수 있는 에이전트를 구축하세요.</strong>
</p>
<p align="center">
모델의 주장(claims)을 실제로 실행된 내용과 비교하는 에이전트 프레임워크입니다. 사용자가 검사 항목(checks)과 다음 동작을 직접 선택할 수 있습니다. 이는 세상에 대한 주장이 아니라 기록에 근거하여 주장을 검증합니다.
</p>
<p align="center">
FootprintJS 실행 출처(execution provenance)를 기반으로 구축되었습니다. 에이전트가 실행되는 동안 컨텍스트(context), 도구 호출(tool calls), 결과(results), 결정(decisions) 등이 연결된 기록(records)이 됩니다.<br/>도구(tools), 스킬(skills), 메모리(memory), RAG, 오케스트레이션(orchestration)을 사용하여 구축하고, 이 기록을 답변 검증, 디버깅 및 리뷰에 활용하세요.
</p>
<p align="center">
<a href="#evidence-and-limits">증거와 한계</a> ·
<a href="#checks-you-can-enable">검사 및 보증</a> ·
<a href="#how-this-compares-with-langchain-and-mastra">프레임워크 비교</a> ·
<a href="#quick-start--runs-offline-no-api-key">빠른 시작</a>
</p>
<p align="center">
<a href="https://github.com/footprintjs/agentfootprint/actions"><img src="https://github.com/footprintjs/agentfootprint/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
<!-- coverage-badge --><img src="https://img.shields.io/badge/coverage-87%25-green.svg" alt="coverage: 87%"><!-- /coverage-badge -->
<a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/v/agentfootprint.svg?style=flat" alt="npm version"></a>
<a href="https://bundlephobia.com/package/agentfootprint"><img src="https://img.shields.io/bundlephobia/minzip/agentfootprint?label=minzipped" alt="minzipped size"></a>
<a href="#tree-shakeable--esm-first"><img src="https://img.shields.io/badge/tree--shakeable-%E2%9C%93-success?style=flat" alt="tree-shakeable"></a>
<a href="https://www.npmjs.com/package/agentfootprint"><img src="https://img.shields.io/npm/dm/agentfootprint.svg" alt="Downloads"></a>
<a href="https://github.com/footprintjs/agentfootprint/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT"></a>
이 답변이 지원할 수 있는 것은 무엇인가요?
도구가 행을 반환하지 않았습니다. 에이전트가 **"사건이 없습니다(there are no incidents)"**라고 말하기 전에, 앱은 어떤 계정이 검색되었는지, 읽기가 어느 기간을 다루었는지, 완료되었는지 여부, 그리고 무엇에 접근할 수 없었는지를 알아야 합니다. 성공적인 빈 쿼리(query)와 실패한 쿼리는 서로 다른 답변을 지원합니다.
예를 들어, 범위가 제한된 주장은 다음과 같습니다: "이 계정과 시간 범위에 대해 일치하는 사건을 찾지 못했습니다. 이메일 보고서는 확인되지 않았습니다." 이는 어딘가에 사건이 존재하지 않는다는 주장이라기보다는, 범위 인식(scope-aware) 문구의 예시입니다. 증거가 요청된 결론을 뒷받침할 수 없을 때, 앱은 그 불확실성을 명시적으로 표시하거나 답변을 보류해야 합니다.
Agentfootprint는 해당 결정을 위한 실행 기록과 구성 가능한 검사 기능을 제공합니다. 사용자의 앱이 비교 및 전달 정책을 정의합니다. 도구 선언(Tool declarations)은 쿼리를 진실되게 설명해야 합니다: 출처의 주장을 기록하는 것이 그 출처가 정확하다는 것을 증명하지는 않습니다.
증거가 답변에 도달하는 방법
- 실행된 내용을 기록합니다. FootprintJS는 실행 단계와 데이터 종속성을 연결하며, Agentfootprint는 제공된 컨텍스트, 호출된 도구 및 반환된 결과를 기록합니다.
- 한계를 보존합니다. 도구는 부재(absence), 범위(coverage), 그리고 시간 경계(time boundaries)를 선언합니다. 모델이 이를 반복하도록 의존하기보다는, 이러한 한계가 답변과 함께 이동하도록 구성하십시오.
- 전달 전에 확인합니다. 옵트인(Opt-in) 답변 검증은 앱이 작성한 규칙에 따라 후보군을 증거와 비교합니다. 강제 모드(Enforce mode)는 실패했거나 검증되지 않은 후보군을 보류하며, 호스트가 사용자에게 거부 이유를 설명하는 방법을 결정합니다.
- 동일한 실행을 검사합니다. 기록된 입력(inputs), 결과(results), 결정(decisions) 및 검사 내용을 검토하거나, 실패를 조사하기 위해 실행을 재실행할 수 있습니다.
실행 출처(Execution provenance)는 무엇이 실행되었고 무엇이 제공되었는지 설명합니다. 이는 모델의 내부 추론 과정을 노출하거나 외부 사실이 참임을 독립적으로 확립하지는 못합니다. 답변을 보류하는 것이 이미 수행된 도구 동작을 되돌리지는 않습니다.
활성화할 수 있는 검사(Checks you can enable)
프레임워크를 설치한다고 해서 모든 답변이 검증되는 것은 아닙니다. 이 메커니즘들은 각각 다른 역할을 하며, 앱이 확인해야 하는 주장에 맞게 구성되어야 합니다.
LangChain 및 Mastra와의 비교
이 프레임워크들은 모두 에이전트 구축(agent building)과 런타임 제어(runtime controls)를 지원합니다. 유용한 차이점은 가드레일(guardrails)을 가지고 있느냐의 여부라기보다는, 각각 무엇을 강조하는가에 있습니다.
프레임워크 | 강조점 및 기존 런타임 제어 기능
| :--- | :--- |
| LangChain / LangGraph | 모델 및 도구 통합, 영속성(persistence)과 인간의 감독을 통한 에이전트 루프 및 상태 기반 오케스트레이션. LangGraph는 실행을 다루며; LangChain guardrails는 실행 중 입력, 출력 및 도구 호출을 확인할 수 있습니다. |
| ... |
에이전트가 실제로 읽은 내용, 해당 증거의 한계, 그리고 전달 전에 적용된 검사(checks)와 답변을 연결하는 것이 핵심 요구 사항일 때 Agentfootprint를 선택하십시오. 스킬, 도구 및 오케스트레이션이 에이전트를 구축하며, 실행 기록 또한 그 답변 정책을 지원합니다. 이 비교는 디자인 강조점을 설명하는 것이며, 독점적인 기능이나 답변 정확도의 측정된 우월성을 의미하지 않습니다.
빠른 시작 — 오프라인에서 실행되며, API 키가 필요하지 않음
npm install 'agentfootprint@^15.0.0' 'footprintjs@^14.0.0'
Agentfootprint 15는 FootprintJS의 피어(peer) 및 Foottrace의 의존성으로 각각 ^14.0.0과 ^2.1.0을 요구합니다. 위에서 보여준 대로 FootprintJS를 명시적으로 설치하십시오.
릴리스 트레인(release train) 기간 동안, 게시된 Agentfootprint 15 후보와 [email protected]을 함께 사용하십시오. npm의 next 태그가 Agentfootprint 15 후보를 가리킬 때 이 명령어를 사용하십시오.
import { Agent, defineTool } from 'agentfootprint';
import { mock } from 'agentfootprint/providers';
...
이 도구는 로컬에서 실행되며 모의(mock) 스크립트가 호출 및 응답을 처리합니다. 온도는 실제 날씨 정보가 아닌 고정된 데이터(fixture data)입니다. 이 예제는 답변 검증이 아니라 연결(wiring)을 시연합니다. 구성된 전달 검사를 위해서는 모의 답변 유효성 검사 예제를 실행하십시오.
실제 모델을 사용하려면 스크립트된 모의(mock) 대신 agentfootprint/providers에서 제공하는 프로바이더 — anthropic(...) / openai(...) / bedrock(...) / gemini(...) / ollama(...) — 로 대체하고, 해당 모델과 필요한 모든 인증 정보를 구성해야 합니다. 에이전트(agent)와 도구 연결(tool wiring)은 동일하게 유지됩니다. mock을 포함한 모든 프로바이더는 이 서브 경로에 위치하므로, 메인 배럴(main barrel)은 선택적 프로바이더 SDK 임포트로부터 자유로울 수 있습니다.
클라우드 계정이 없으신가요? agentfootprint/providers의 ollama('llama3.2')를 사용하면 $0으로 동일한 에이전트를 로컬 모델에 대해 실행할 수 있습니다. 이는 모의(mock)와 실제 비용 사이의 무료 연결고리입니다. 전체 레시피: Ollama · OpenAI 호환 엔드포인트.
도구가 반환하는 것 — 세 가지 헬퍼, 하나의 규칙
도구가 무엇을 반환하든 그것이 모델이 다음에 읽는 내용입니다. 이 값이 모델이 손실해서는 안 되는 제한 사항(limits)을 가지고 있을 경우, 세 가지 헬퍼 중 하나를 통해 반환해야 합니다. 각 헬퍼는 도구의 응답이며, 시스템 프롬프트나 도구 스키마에 추가되는 것은 없습니다:
| 헬퍼 | 사용 시점 | 모델이 읽는 내용 | 기록 보관소(record)가 유지하는 것 |
|---|
describedResult({ … }) | 레코드 시스템의 행, 시리즈 또는 관계 | grain, provenance 및 간극당 하나의 not_covered 라인이 포함된 데이터 전체 | 전체 봉투 (tools.semantics_declared) |
| ... | | | |
절대 하나를 다른 것으로 감싸지 마십시오. .limitsTravelWithTheAnswer()를 추가하면 선언된 커버리지가 최종 답변에 추가됩니다 — 또는, 타입이 지정된 .outputSchema() 답변의 경우, agent.answerCoverage()에 의해 데이터로 그 옆에 반환됩니다. Provenance와 grain은 절대 그렇지 않습니다.
import { absent, coverage, describedResult } from 'agentfootprint';
execute: ({ vm, summary }) => {
...
모델이 각각으로부터 정확히 읽는 내용은 다음과 같습니다: 도구 → execute가 반환하는 것.
에이전트 구축 — 컨텍스트, 도구 및 오케스트레이션
Skills, steering, RAG, facts, memory, guardrails 등 컨텍스트를 지칭하는 모든 이름은 하나의 역할을 수행합니다. 바로 세 개의 LLM 슬롯 중 하나에 주입(injects)된다는 것입니다. 그래서 우리는 이 '주입' 자체를 추상화했습니다.
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/hero-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="docs/assets/hero-light.svg">
<img alt="agentfootprint mascot composing context flavors (Skills, Steering, Guardrails, RAG, Tool APIs, Memory) into three structured LLM slots (system, messages, tools) — the central abstraction, visualized." src="https://raw.githubusercontent.com/footprintjs/agentfootprint/HEAD/docs/assets/hero-light.svg" width="100%"/>
</picture>
</p>
<p align="center">
<sub><em>하나의 기본 원리(primitive)가 있습니다: <code >Injection = slot × trigger × cache</code>. 프레임워크가 이 지점을 소유하기 때문에, 모든 컨텍스트 조각은 태어날 때부터 추적 가능합니다(<b >born tracked</b >). 관찰 가능성(observability)은 별도로 연결된 것이 아니라, 바로 이 추상화의 결과물인 것입니다. <a href="#the-4-triggers">The 4 triggers ↓</a></em></sub>
</p>
<p align="center">
<picture>
<source media="(prefers-color-scheme: dark)" srcset="docs/assets/triggers-dark.svg">
<source media="(prefers-color-scheme: light)" srcset="docs/assets/triggers-light.svg">
<img alt="agentfootprint — Every LLM call has 3 fixed slots (system, messages, tools). Every flavor lands in one slot under one of 4 fixed triggers (always · rule · on-tool-return · llm-activated). Sparkle streams flow from each trigger lane down to a specific pill inside its destination slot — same slot can hold pills from different triggers (RAG via rule, Instruction via on-tool-return), and the same flavor (Skill) can land in different slots." src="https://raw.githubusercontent.com/footprintjs/agentfootprint/HEAD/docs/assets/triggers-light.svg" width="100%"/>
</picture>
</p>
이 추상화는 세 가지 규칙으로 이루어져 있습니다:
- 세 개의 슬롯이 고정되어 있습니다.
system, messages, tools—LLM API 표면입니다.
- N개의 맛(flavor)은 열려 있습니다. 사용자가 가진 것을 선언합니다. 내일의 맛(few-shot, reflection, persona, A2A handoff 등)도 같은 방식으로 플러그인됩니다.
- 규칙이 어디서 그리고 언제를 결정합니다. 사용자가 규칙을 제공합니다. 저희는 데이터를 수집하고, 적절한 것을 실행하며, 올바른 반복(iteration)에서 올바른 슬롯에 배치합니다.
이것이 전체 모델입니다: Injection = slot × trigger × cache.
- 슬롯(Slot) — 콘텐츠가 어느 3개의 LLM API 영역(
system / messages / tools)에 위치하는지.
- 트리거(Trigger) — 콘텐츠가 언제 실행되는지 (아래 참조).
- 캐시(Cache) — 반복을 거치면서 콘텐츠가 얼마나 안정적인지. 프레임워크는 사용자를 위해 제공업체 캐시 마커를 배치합니다. 안정적인 콘텐츠는 80–90% 저렴한 접두사(prefix)를 얻습니다.
4가지 트리거
| 트리거 | 맛 (Flavor) | 실행 시점 | 예시 | 기본 슬롯 |
|---|
always | 정적(static) | 모든 반복마다 | .steering(defineSteering({ id, prompt: 'You are a triage agent…' })) | system |
| ... | | | | |
| 3개의 슬롯 × 4개의 트리거 × N개의 맛(flavor) = 전체 컨텍스트 엔지니어링 표면입니다. | | | | |
증거 검사 및 재현 (Inspect and replay the evidence)
기록된 실행은 디버깅도 지원합니다. 이 예시들은 다양한 종류의 증거를 보여줍니다. 유사성 점수나 기록된 의존성만으로는 모델이 왜 특정 답변을 선택했는지에 대한 증거가 될 수 없습니다.