LLMWiki Agent Bridge

llmwiki-agent-bridge는 LLMWiki 툴체인을 위한 선택적 소스 팬아웃 및 런타임 합성 계층입니다. 로컬 HTTP 서비스로 실행되며 하나 이상의 llmwiki-serve Knowledge Source에서 증거를 수집하고, 인용, 선택적 그래프 컨텍스트, 추적 단계가 포함된 하나의 정규화된 답변 아티팩트를 반환합니다. 첫 스모크 테스트를 위해 증거 전용으로 실행하거나, 구성된 런타임 어댑터를 호출하여 합성 답변을 생성할 수 있습니다. 기본 어댑터는 OpenAI 호환 채팅 완료를 대상으로 합니다.

다음과 같은 경우에 사용하세요:

• 클라이언트가 소스 팬아웃, 프롬프팅, 런타임 호출, 인용, 추적 형태 구성을 직접 관리하지 않고 하나의 엔드포인트를 원하는 경우

• Hermes, DeepAgents 또는 일반 로컬 런타임을 LLMWiki 증거에 연결하는 경우

• llmwiki-chat 또는 다른 UI가 로컬 Knowledge Source를 기반으로 하는 Agent Bridge A2A 또는 MCP 엔드포인트를 필요로 하는 경우

에이전트나 스크립트가 llmwiki-serve를 직접 호출하고 자체 답변 합성을 관리할 수 있다면 브리지는 건너뛰세요.

빠른 시작 | 경로 선택 | 데모 | 런타임 프로필 | 메시지 계약 | OpenAPI | 통합 | 예제 | 문서 포털 | 기여 | 보안 | 지원 | 변경 로그

공개 미리보기 참고: llmwiki-agent-bridge@latest에 대해 npm install을 사용할 수 있습니다. 소스 체크아웃은 로컬 개발 및 릴리스 검사를 위해 계속 지원됩니다.

처음 실행을 위한 시각적 안내는 docs 데모를 참조하세요. 이 데모는 툴체인 경계를 보여줍니다. 상위 워크플로가 호환되는 Markdown/wiki 파일을 만들고, llmwiki-serve가 이를 읽기 전용 Knowledge Source로 제공하며, 선택적 브리지는 선택된 제공 소스를 함께 조회할 수 있습니다.

Hermes 전용 브리지가 아닙니다. Hermes는 generic과 deepagents 외에 지원되는 런타임 프로필 중 하나이며, 모든 프로필은 동일한 메시지 계약을 사용하고 동일한 llmwiki_agent_result 아티팩트 형태를 반환합니다. 런타임 프로필은 런타임 계열을 식별하고, 런타임 어댑터는 브리지가 이를 호출하는 방식을 선택합니다.

이 프로젝트는 LLM Wiki 스타일 Markdown 지식 폴더와 에이전트가 읽을 수 있는 컨텍스트를 위한 독립적인 커뮤니티 도구입니다. Andrej Karpathy 또는 호환성 예제에 언급된 상위 프로듀서의 공식 프로젝트가 아닙니다.

경로 선택

클라이언트가 llmwiki-serve 자체를 호출할 수 있다면 항상 직접 경로부터 시작하세요. 팬아웃, 런타임 합성, 또는 하나의 로컬 서비스 뒤에서 단일 정규화 결과가 필요할 때 브리지를 추가하세요.

직접 클라이언트 템플릿은 integrations에 있습니다. 브리지 요청 및 아티팩트 계약은 docs/message-send-contract.md에 문서화되어 있으며 docs/openapi.json으로 생성됩니다.

Related MCP server: A2ABench

빠른 시작

요구 사항:

• Node.js >=22.12

• npm >=10

• 하나 이상의 실행 중인 llmwiki-serve Knowledge Source 엔드포인트

• 선택 사항: 합성을 위한 런타임. 패키지 실행은 현재 OpenAI 호환 /v1/chat/completions 어댑터를 기본으로 사용합니다.

• 체크아웃에서 샘플 소스를 시작할 때 uv 및 Python 3.11 이상

이 빠른 시작은 터미널 1에서 소스 서버 체크아웃을 시작합니다. 터미널 2에서는 일반 로컬 실행을 위해 게시된 브리지 패키지를 사용하거나, 리포지토리 검사를 실행하거나 패키지된 예제를 살펴보거나 브리지를 개발하려면 브리지 소스 체크아웃을 사용합니다.

터미널 1: 소스 서버

샘플 llmwiki-serve Knowledge Source를 클론하고 시작하세요. 이 프로세스를 계속 실행 상태로 두세요:

git clone https://github.com/knowledge-bridge-labs/llmwiki-serve.git
cd llmwiki-serve
uv sync --extra dev
uv run llmwiki-serve serve ./examples/sample-wiki --host 127.0.0.1 --port 8765

터미널 2: 브리지

어느 터미널에서든 터미널 1이 샘플 소스를 서빙하고 있는지 확인하세요:

curl -s http://127.0.0.1:8765/manifest

게시된 공개 미리보기 패키지를 시작하세요:

npx llmwiki-agent-bridge@latest

대신 소스 체크아웃 개발을 하려면 llmwiki-serve 체크아웃이 포함된 동일한 상위 워크스페이스에서 터미널 2를 열고, 브리지를 클론하고, 의존성을 설치하고, 로컬 검사를 실행하고, 체크아웃 CLI를 시작하세요:

git clone https://github.com/knowledge-bridge-labs/llmwiki-agent-bridge.git
cd llmwiki-agent-bridge
npm ci
npm run check
node ./bin/llmwiki-agent-bridge.mjs

CLI는 브리지가 수신 대기 중일 때 JSON ready 이벤트를 작성합니다:

{
  "event": "ready",
  "url": "http://127.0.0.1:8788",
  "sourcePolicy": "private-http"
}

런타임 기반 답변 합성을 위해 로컬 런타임과 일치하는 런타임 프로필로 브리지를 다시 시작하세요. 이 일반 예제는 OpenAI 호환 채팅 완료를 구현하는 모든 런타임에서 작동합니다.

macOS/Linux:

LLMWIKI_AGENT_BRIDGE_BASE_URL=http://127.0.0.1:8642/v1 \
LLMWIKI_AGENT_BRIDGE_MODEL=local-model \
LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic \
npx llmwiki-agent-bridge@latest

Windows PowerShell:

$env:LLMWIKI_AGENT_BRIDGE_BASE_URL = 'http://127.0.0.1:8642/v1'
$env:LLMWIKI_AGENT_BRIDGE_MODEL = 'local-model'
$env:LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE = 'generic'
npx llmwiki-agent-bridge@latest

소스 체크아웃에서는 마지막 npx 명령 대신 node ./bin/llmwiki-agent-bridge.mjs 또는 node .\bin\llmwiki-agent-bridge.mjs를 사용하세요.

Hermes 또는 호환되는 OpenAI 스타일 런타임의 경우 명령 형태는 동일하게 유지하고 LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE과 모델 이름을 변경하세요:

DeepAgents 직접 제공자 통합은 ACP 우선이어야 합니다. 공식 DeepAgents 문서는 deepagents-acp를 ACP stdio CLI/프로그래매틱 API로 설명합니다. 이 패키지는 runtimeAdapter=deepagents-acp 뒤에 선택적으로 활성화되는 라이브 ACP 하위 프로세스 어댑터를 제공합니다. 기본값은 채팅 완료로 유지됩니다. ACP 어댑터는 브리지 런타임 요청마다 deepagents-acp stdio 프로세스 하나를 시작하고, 권한 프롬프트는 ACP cancelled로 거부 처리하며, 브리지 요청 시간 초과를 하위 프로세스 정리에 적용합니다.

브리지를 계속 실행 상태로 두세요. 다음 명령도 브리지 체크아웃 명령입니다. 터미널 2가 브리지 프로세스로 사용 중이면 다른 프롬프트를 열고 먼저 cd llmwiki-agent-bridge를 실행하세요.

로컬 표면을 확인하세요:

curl -s http://127.0.0.1:8788/health
curl -s http://127.0.0.1:8788/.well-known/agent-card.json
curl -s http://127.0.0.1:8788/settings.json

첫 실행에는 http://127.0.0.1:8788/settings를 열고 안내된 설정을 따르세요:

1. 합성이 필요할 때 런타임을 연결하세요. 런타임 프로필, 기본 URL, 모델을 설정합니다. 페이지는 PUT /settings/config.json을 통해 이러한 필드를 저장합니다.

2. Knowledge Source를 등록하세요. http://127.0.0.1:8765의 샘플 소스를 추가하고, 준비됨 및 선택됨으로 표시한 다음 GET/PUT /settings/sources.json을 통해 저장합니다.

3. 브리지를 검증하세요. 등록된 소스를 사용하여 POST /message:send를 보내고 반환된 답변 아티팩트, 인용, 그래프, 추적 단계를 표시하는 설정 페이지 검증을 실행합니다. /message:send는 기본적으로 delegated-runtime을 사용하므로 이 설정 페이지 검사는 구성된 런타임에 연결할 수 있어야 합니다. 런타임 없는 스모크 테스트에는 아래의 증거 전용 샘플 요청을 사용하세요.

런타임 자격 증명, 네트워크, 인증, CORS, 시간 초과 및 소스 정책 제어는 진단/고급 아래에 있습니다. 대부분의 로컬 OSS 사용자는 위의 세 가지 설정 단계만 필요합니다.

패키지만으로 시작하는 경우 런타임 없는 스모크 테스트를 위해 인라인 증거 전용 요청을 보내세요:

curl -s http://127.0.0.1:8788/message:send \
  -H 'content-type: application/json' \
  -d '{"data":{"query":"release readiness","mode":"evidence-only","knowledgeSources":[{"id":"sample-wiki","name":"Sample Wiki","protocol":"llmwiki-http","status":"ready","url":"http://127.0.0.1:8765","selected":true}]}}'

llmwiki-agent-bridge 소스 체크아웃에서는 번들된 동일한 요청을 보낼 수 있으므로 --data @examples/message-send.local.json 경로가 이 리포지토리를 가리킵니다:

curl -s http://127.0.0.1:8788/message:send \
  -H 'content-type: application/json' \
  --data @examples/message-send.local.json

번들된 examples/message-send.local.json은 http://127.0.0.1:8765를 가리키며 mode를 evidence-only로 설정합니다. llmwiki-serve 또는 브리지 프로세스가 다른 포트를 사용하는 경우 해당 파일을 임시 경로에 복사하고 소스 URL을 업데이트한 후 시작한 브리지 URL에 게시하세요.

MCP 스타일 클라이언트는 /mcp에서 initialize, notifications/initialized, ping으로 기본 수명 주기를 완료한 다음 브리지 도구를 나열할 수 있습니다. 브리지가 완전한 근거 있는 답변을 생성하도록 하려면 llmwiki_agent_run을 사용하고, 호스트 에이전트가 소스를 점진적으로 검사하려면 읽기 전용 소스 도구를 사용하세요:

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"ping"}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/list"}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"llmwiki_agent_run","arguments":{"query":"release readiness"}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"llmwiki_context","arguments":{"sourceId":"sample-wiki","query":"release readiness","limit":5}}}'

curl -s http://127.0.0.1:8788/mcp \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":6,"method":"tools/call","params":{"name":"llmwiki_graph_neighbors","arguments":{"sourceId":"sample-wiki","nodeId":"sample-wiki:overview","direction":"out","relation":"supports","limit":20}}}'

knowledgeSources를 생략하면 /settings를 통해 등록된 소스를 사용합니다. knowledgeSources: []를 전달하면 "소스 없이 실행"을 의미하며 부정 테스트에만 유용합니다. 사람이 읽을 수 있는 소스 목록에는 엔드포인트 URL이 포함되지 않습니다. 구조화된 llmwiki_sources.sources 설명자에는 소스 URL이 포함되므로 로컬 워크벤치가 브리지 관리 소스를 선택하고 이를 /message:send로 다시 전달할 수 있습니다. 비공개 로컬 URL을 공개 문서, 이슈 또는 예제에 복사하지 마세요.

샘플 요청은 release readiness를 묻습니다. 정확한 답변 표현은 런타임에 따라 다를 수 있습니다. 안정적인 통합 대상은 완료된 작업과 llmwiki_agent_result 데이터 아티팩트 필드입니다:

{
  "answer": "Grounded answer text from the configured runtime.",
  "citations": [
    {
      "sourceId": "sample-wiki",
      "pageId": "release-readiness",
      "title": "Release Readiness",
      "score": 0.92
    }
  ],
  "graph": {
    "nodes": [],
    "edges": []
  },
  "steps": [
    {
      "id": "bridge-evidence",
      "label": "Prepare evidence",
      "status": "done"
    },
    {
      "id": "runtime-chat-completions",
      "label": "Call chat completions",
      "status": "done"
    }
  ]
}

전체 페이로드와 로컬 설정 참고 사항은 예제, 런타임 프로필, 메시지 계약, 클라이언트 경로를 사용하세요.

하는 일

브리지는 하나의 작은 로컬 HTTP 표면을 노출합니다:

각 POST /message:send 요청에 대해 브리지는:

1. 요청에서 준비된 Knowledge Source 설명자를 선택합니다.

2. llmwiki-http, MCP 스타일 JSON-RPC 또는 A2A 스타일 HTTP를 통해 컨텍스트를 가져옵니다.

3. 인용, 그래프 컨텍스트, 소스 번들 메타데이터, 트레이스 단계를 패키징합니다.

4. delegated-runtime 또는 hybrid에서는 증거 번들을 컴팩트 JSON으로 렌더링하고 구성된 OpenAI 호환 /v1/chat/completions 엔드포인트를 호출합니다.

5. evidence-only에서는 런타임 호출을 건너뛰고 브리지가 생성한 증거 요약을 반환합니다.

6. 답변 텍스트와 llmwiki_agent_result 아티팩트를 반환합니다.

POST /mcp는 두 계층을 노출합니다. llmwiki_agent_run은 /message:send와 동일한 내부 실행 경로를 호출하고 텍스트 콘텐츠와 structuredContent.llmwiki_agent_result를 반환합니다. 읽기 전용 소스 도구인 llmwiki_list_sources, llmwiki_context, llmwiki_search, llmwiki_read, llmwiki_graph, llmwiki_graph_neighbors, llmwiki_source_bundle은 구성된 런타임을 호출하지 않습니다. 이 도구들은 호스트 에이전트가 소스 목록을 확인하고, 오리엔테이션 우선 컨텍스트를 읽고, 검색하고, 페이지를 열고, 그래프 데이터를 검사하고, 제한된 이웃을 탐색하거나 안전한 소스 번들 메타데이터를 읽은 다음, 추가 소스 탐색이나 전체 답변 실행이 필요한지 결정할 수 있게 해줍니다.

HTTP 서비스를 시작하지 않고 로컬 운영자 점검을 수행하려면 llmwiki-agent-bridge sources --json, llmwiki-agent-bridge ls 또는 llmwiki-agent-bridge status --probe를 사용하세요. CLI 출력은 로컬 설정 파일을 읽고 진단용으로 저장된 로컬 루트를 표시할 수 있습니다. HTTP 레지스트리 응답은 절대 루트를 안전한 라벨로 편집하고 PUT /settings/sources.json에서 중복 소스 ID를 거부합니다.

요청은 knowledgeSources를 직접 제공하거나 생략하고 브리지에 등록된 Knowledge Sources를 사용할 수 있습니다. /settings의 2단계에서 소스를 등록하거나 sources 배열로 PUT /settings/sources.json을 호출하여 등록하세요. 여러 개의 준비된 선택 소스를 한 번의 실행에서 등록하고 질의할 수 있습니다. 소스 호출은 무한 병렬로 전송되지 않고 내부적으로 제한됩니다. 반환되는 아티팩트는 인용, 그래프 데이터, 소스 번들, 트레이스 단계, 진단, 소스별 실패에 대해 선택된 소스 순서로 다시 정규화됩니다.

/message:send는 레거시 data.query 계약을 유지하며 추가적인 대화 런타임 컨텍스트도 허용합니다: data.message 또는 최상위 A2A message, data.messages, data.threadId, data.sessionId, data.turnId, data.runtimeContext.conversation, A2A 스타일 configuration.historyLength, A2A 스타일 metadata.threadId/sessionId/turnId. 브리지는 소스 검색을 위해 data.query 또는 A2A 메시지 텍스트의 현재 쿼리를 사용한 다음, 증거 시스템 프롬프트 이후 런타임 chat-completions 호출에 제한된 사용자/어시스턴트 대화 기록을 포함합니다.

검색 모드 라우팅

클라이언트는 선택적으로 data.retrieval로 소스 검색 모드를 요청할 수 있습니다. 이는 data.mode와 별개입니다. data.mode와 data.orchestrationMode는 브리지 오케스트레이션을 제어하고, data.retrieval.searchMode는 소스 검색을 제어합니다. 레거시 어휘 요청 형태를 유지하려면 data.retrieval을 생략하세요.

{
  "data": {
    "query": "Which release checks are still missing?",
    "mode": "evidence-only",
    "retrieval": {
      "schemaVersion": "llmwiki.retrieval.v1",
      "searchMode": "hybrid",
      "fallback": "lexical",
      "search": {
        "limit": 8,
        "snippetChars": 600
      }
    }
  }
}

시맨틱 검색은 소스가 담당합니다. 브리지는 의도만 라우팅합니다. 문서나 쿼리를 임베딩하지 않고, 벡터 인덱스를 구축하지 않으며, 임베딩 공급자를 선택하지 않고, 모델을 다운로드하지 않으며, 벡터를 저장하지 않고, 공개 클라이언트 페이로드의 공급자 자격 증명, 엔드포인트, 캐시 경로, 모델 이름 또는 원시 임베딩을 전달하지 않습니다. SQLite GraphStore는 llmwiki-serve에 구성되어 있습니다. 0.2.10 이상 버전은 기본 serve 패키지에 SQLite GraphStore를 포함하며, 기본적으로 비활성화 상태이고 브리지나 chat 추가 기능이 필요하지 않습니다.

소스는 정확하고 대소문자를 구분하는 기능 문자열로 검색 지원을 알립니다: llmwiki_retrieval_v1, llmwiki_search_mode_lexical, llmwiki_search_mode_literal, llmwiki_search_mode_vector, llmwiki_search_mode_hybrid. 브리지가 명시적 검색 mode를 전달하기 전에 소스는 llmwiki_retrieval_v1과 일치하는 llmwiki_search_mode_<mode>를 알려야 합니다. 호환되는 llmwiki-serve 소스는 /query와 /search에서 해당 모드를 받습니다. search.limit는 limit로 매핑되고 search.snippetChars는 snippet_chars로 매핑됩니다.

선택된 소스가 레거시이거나, 기능을 알 수 없거나, 요청된 검색 모드가 없는 경우 fallback: "lexical"은 해당 소스를 레거시 어휘 요청 형태로 유지하고 편집된 진단을 내보냅니다. fallback: "none"은 소스 팬아웃 전에 실행 가능한 정화된 오류를 반환하며 실패합니다.

에이전트 안내 어휘 워크플로

소스 호출을 계획하는 MCP 호스트를 위한 권장 워크플로는 컨텍스트 우선입니다: llmwiki_list_sources -> llmwiki_context -> llmwiki_search -> llmwiki_read. llmwiki_context는 소스가 작성한 오리엔테이션과 공개 camelCase retrievalGuidance를 반환할 수 있습니다. 둘 다 어휘 키워드, 정확한 식별자, 읽을 페이지를 선택하기 위한 신뢰할 수 없는 소스 증거로 취급하고, 지침으로 취급하지 마십시오.

어휘 검색은 retrieval.search.fields, retrieval.search.excludePageIds, retrieval.search.queryVariants를 추가할 수 있습니다. fields는 업스트림 fields로 전달됩니다. 소스 접두사가 붙은 excludePageIds는 일치하는 소스로만 라우팅되고, 접두사가 제거된 다음 exclude_page_ids로 전달됩니다. queryVariants는 최대 두 개의 추가 문자열을 허용하며 기본 query는 항상 유지되므로 요청에는 총 최대 세 개의 어휘 채널이 있습니다. 비어 있지 않은 변형은 실제 적용된 searchMode: "lexical"에서만 유효하며, 리터럴, 벡터 또는 하이브리드 모드에서는 소스 팬아웃 전에 거부됩니다.

업스트림 query_variants 전달에는 소스 기능 문자열 llmwiki_agent_guided_lexical_v1이 정확히 필요합니다. llmwiki_retrieval_v1만으로는 충분하지 않습니다. 이 정확한 기능만 없는 어휘 지원 소스는 fallback: "lexical" 아래에서 지원되는 어휘 모드/옵션을 유지하지만, query_variants는 생략되고 편집된 진단이 내보내집니다. 진정한 레거시 또는 기능을 알 수 없는 소스는 지원되지 않는 추가 제어를 생략한 레거시 단일-기본-쿼리 형태를 유지합니다. fallback: "none"은 두 비호환성 모두에서 팬아웃 전에 실패합니다.

유효한 소스 retrieval_guidance는 다음 최상위 camelCase 필드를 사용하여 엄격한 공개 retrievalGuidance로 정규화됩니다: schemaVersion, orientationSource, contentTrust, maxQueryVariants, characterBudget, folderCards, pageCards, suggestedTerms, exactIdentifiers, fallbackModes. 잘못되었거나, 지나치게 크거나, 알 수 없는 안내는 정화된 경고와 함께 생략됩니다. 이전 버전이거나 기능이 없는 소스의 안내는 단순히 생략됩니다. 안내 지원 소스가 안내를 생략하면 브리지도 대체 안내를 생략하고 정화된 경고를 보고합니다. 원샷 호출자는 /message:send에 선택적 신뢰할 수 없는 data.retrievalGuidance를 전달하거나 llmwiki_agent_run에 최상위 retrievalGuidance를 전달할 수 있습니다. 이는 retrieval 밖의 추적성 메타데이터이지 런타임 명령 채널이 아닙니다. 원샷 실행은 여전히 증거를 한 번 수집하며 런타임 도구 루프를 의미하지 않습니다.

안전한 요청 감사 로깅

LLMWIKI_AGENT_BRIDGE_AUDIT_LOG=1을 설정하거나 auditLog: true를 전달하면 기존 로거(기본값 stdout)를 통해 감사되는 브리지 요청마다 JSON 라인 하나를 내보냅니다. 감사 라우트는 /message:send, /mcp, /settings, /settings.json, /settings/config.json, /settings/sources.json, /.well-known/agent-card.json, /health입니다.

감사 이벤트는 의도적으로 허용 목록에 포함됩니다. 여기에는 라우트 패턴, 상태, 지속 시간, 요청/트레이스 ID, 오케스트레이션 모드, 런타임 호출 여부, 소스 및 아티팩트 수, 대화 수/불리언 필드, 편집 플래그가 포함됩니다. 원시 프롬프트, 런타임 답변, 요청 또는 응답 본문, 쿼리 문자열, 소스 URL, 런타임 기본 URL, 모델 이름, API 키, 베어러 토큰, 로컬 경로, 스레드/세션 ID 또는 대화 메시지 콘텐츠는 포함되지 않습니다.

기본 I/O 디버그 로깅

브리지는 또한 기본적으로 켜져 있는 별도의 JSONL I/O 디버그 스트림을 .runtime-logs/llmwiki-agent-bridge-io.jsonl로 내보냅니다. 이 이벤트는 llmwiki.agent_bridge.io를 사용하며 /message:send 요청, 소스, 런타임, 최종 아티팩트 흐름의 로컬 문제 해결을 위한 것입니다.

I/O 로그에는 편집을 거친 프롬프트, 소스 요청/응답 본문, 런타임 메시지, 런타임 답변, 브리지 응답 아티팩트가 포함될 수 있습니다. 이 로그는 항상 Authorization 및 자격 증명 유사 헤더, API 키, 베어러 토큰, 원시 소스/런타임 URL, URL 쿼리 내 비밀값, 명백한 로컬 절대 경로를 편집합니다. 이 스트림은 의도적으로 안전한 감사 로깅과 분리되어 있습니다.

I/O 로그를 비활성화하려면 LLMWIKI_AGENT_BRIDGE_IO_LOG=off를 설정하거나 "ioLog": false를 영속화하세요. LLMWIKI_AGENT_BRIDGE_IO_LOG=logger 또는 stdout을 설정하면 JSONL을 프로세스 로거로 라우팅합니다. LLMWIKI_AGENT_BRIDGE_IO_LOG_PATH는 다른 파일 경로를 선택합니다.

flowchart LR
  client["client or chat workbench"]
  bridge["llmwiki-agent-bridge"]
  sources["selected Knowledge Sources"]
  runtime["OpenAI-compatible runtime"]
  artifact["answer artifact<br/>citations, graph, trace"]

  client --> bridge
  bridge --> sources
  sources --> bridge
  bridge --> runtime
  runtime --> bridge
  bridge --> artifact

지원되는 Knowledge Source 프로토콜:

생성된 OpenAPI 계약은 docs/openapi.json에 커밋되어 있습니다. 이 계약은 브리지의 로컬 HTTP 표면과 llmwiki_agent_result 아티팩트 형태를 공개 미리 보기 호환성 계약으로 다루며, 인증된 A2A 적합성은 아닙니다.

이 패키지는 기존 /message:send 라우트를 안정적으로 유지하면서 A2A 디스커버리 호환성 검사를 위해 @a2a-js/sdk@0.3.14를 포함합니다.

런타임 프로필

프로필은 동일한 브리지 계약에 대한 보수적 구성 사전 설정입니다. 런타임 ID 메타데이터, 기본 모델 이름 지정, 운영자 대상 구성을 변경하며, LLMWiki 증거 형식은 변경하지 않습니다. Compact JSON은 현재 런타임 프롬프트 증거 인코딩입니다. 광범위한 프로덕션 기본 승인은 추적된 런타임 프롬프트 승인 e2e에 의해 게이트되는 증거 주장이지, 프로필 전환이 아닙니다.

레거시 HERMES_* 및 HERMES_A2A_BRIDGE_* 환경 별칭은 마이그레이션을 위해 계속 사용할 수 있습니다. 새 배포는 LLMWIKI_AGENT_BRIDGE_* 변수를 사용하는 것이 좋습니다.

자세한 내용: docs/runtime-profiles.md.

패키지 표면

llmwiki-agent-bridge는 다음과 같은 공개 진입점을 제공하는 Node 패키지 하나를 제공합니다:

공개 미리보기 패키지는 llmwiki-agent-bridge@latest로 제공됩니다. 전역 설치 없이 실행하려면:

npx llmwiki-agent-bridge@latest

또는 패키지를 설치하고 CLI를 실행합니다:

npm install --global llmwiki-agent-bridge@latest
llmwiki-agent-bridge

소스 체크아웃은 지원되는 개발 경로로 유지됩니다:

npm ci
npm run check
node ./bin/llmwiki-agent-bridge.mjs

통합 경로

에이전트가 llmwiki-serve 자체에서 컨텍스트를 안전하게 검색할 수 있을 때 직접 클라이언트 통합이 가장 좋은 첫 번째 선택입니다. 브리지 통합은 클라이언트가 증거 수집, 런타임 호출, 정규화된 결과 반환을 하나의 로컬 서비스에서 처리하려 할 때 더 적합합니다.

• 클라이언트 경로 가이드

• 통합 개요

• Codex 스킬 예시

• Claude Code 명령 예시

• Copilot 지침 예시

직접 에이전트 사용의 경우 llmwiki-serve를 실행하고 LLMWIKI_SERVE_URL을 설정한 후 integrations/의 템플릿을 조정합니다. 예시는 먼저 /query를 호출한 다음, 더 좁은 검사를 위해 /search, /read/{page_id}, /graph 또는 /mcp를 호출합니다.

export LLMWIKI_SERVE_URL=http://127.0.0.1:8765

워크플로에 소스 팬아웃, 런타임 합성, 하나의 정규화된 답변 아티팩트가 필요한 경우 llmwiki-agent-bridge를 사용하십시오.

구성

대부분의 로컬 실행은 런타임 기본 URL, 모델, 프로필, 선택적 브리지 베어러 토큰만 있으면 됩니다. 명시적 어댑터 통합을 테스트하지 않는 한 runtimeAdapter는 기본값으로 유지하십시오:

소스 정책, CORS, 바인드 호스트 및 마이그레이션 별칭 세부 정보는 런타임 프로필 및 클라이언트 경로에 문서화되어 있습니다.

구현은 이전 버전과의 호환성을 위해 Hermes 기본값을 유지합니다. 새로운 OSS 설치의 경우 Hermes 또는 DeepAgents에 연결하지 않는 한 LLMWIKI_AGENT_BRIDGE_RUNTIME_PROFILE=generic을 명시적으로 설정하고 해당 런타임이 기대하는 모델 이름을 설정하십시오.

LLMWIKI_AGENT_BRIDGE_BEARER_TOKEN 없이 공용 또는 공유 인터페이스에 브리지를 노출하지 마십시오. 비루프백 바인드는 명시적 옵트인이 필요하며, 공용 미인증 바인드는 개발 전용 탈출구입니다.

/settings 페이지는 동일한 구성에 대한 안내식 첫 실행 UI입니다. 1단계는 런타임을 연결하고 PUT /settings/config.json을 통해 프로필, 기본 URL 및 모델을 저장합니다. 2단계는 GET/PUT /settings/sources.json을 통해 재사용 가능한 Knowledge Source 설명자를 저장합니다. 3단계는 페이지에서 POST /message:send를 전송하고 반환된 아티팩트를 표시하여 브리지를 검증합니다. 런타임 자격 증명, 고급 네트워크, 인증, CORS, 타임아웃 및 소스 정책 필드는 진단/고급 아래에서 계속 사용할 수 있습니다. 라이브 런타임 필드 변경은 실행 중인 프로세스에 적용됩니다. 바인드 host 및 port는 다음 시작을 위해 저장되며 저장 응답의 restartRequired 아래에 나열됩니다.

프로그래밍 API

import { startAgentBridge } from 'llmwiki-agent-bridge'

const { server, url } = await startAgentBridge({
  port: 0,
  baseUrl: 'http://127.0.0.1:8642/v1',
  model: 'local-model',
  runtimeProfile: 'generic',
})

console.log(url)
server.close()

레거시 createHermesA2aBridge 및 startHermesA2aBridge 내보내기는 마이그레이션 기간 동안 사용할 수 있습니다.

저장소 구조

릴리스 상태

llmwiki-agent-bridge는 공개 미리 보기 상태입니다. npm 패키지가 게시되어 있으며, 패키지 기반 npx llmwiki-agent-bridge@latest 또는 npm install --global llmwiki-agent-bridge@latest 실행은 로컬 사용으로 지원됩니다. 소스 체크아웃은 개발, 저장소 검증, 릴리스 확인을 위해 계속 지원됩니다.

저장소, 이슈, CI 배지, 패키지, 호스팅된 문서 URL은 의도적으로 Knowledge Bridge Labs 조직을 대상으로 합니다. 호스팅된 릴리스 상태 및 호환성 매트릭스는 현재 사용 가능한 패키지와 런타임 경로를 기록합니다.

다음 공개 미리 보기 릴리스를 준비, 게시 또는 태그하기 전에 docs/release.md를 참조하세요.

개발

npm run lint
npm run contracts:check
npm test
npm run pack:dry-run
npm run audit

npm run check는 린트, 생성 계약 드리프트 검사, 테스트, 드라이 패키징을 실행합니다.

툴체인

커뮤니티

풀 리퀘스트를 열기 전에 CONTRIBUTING.md를 읽고, 변경 사항을 브리지 계약에 집중하고 검증 결과를 포함하세요.

재현 가능한 버그, 명확한 기능 요청, 런타임 또는 프로토콜 호환성 정보, 문서 공백은 GitHub 이슈를 사용하세요. 예제는 공개되고 정제된 상태로 유지하세요. 자격 증명, 베어러 토큰, 비공개 엔드포인트 URL, 원본 민감 위키 콘텐츠, 비공개 런타임 로그는 포함하지 마세요.

• 버그 보고

• 런타임 또는 프로토콜 호환성

• 기능 요청

• 문서 이슈

• 보안 정책

• 지원 가이드

• 행동 강령

취약점의 경우 자세한 공개 이슈를 여는 대신 SECURITY.md를 따르세요.

라이선스

Apache-2.0. LICENSE를 참조하세요.