01. 에이전트 네이티브 인터페이스 — 왜 별도 표면이 필요한가

이 문서가 답하는 질문

• 사람이 쓰는 DB 인터페이스와 에이전트가 쓰는 인터페이스는 왜 달라야 하는가?
• spec 008이 정의하는 표면은 무엇으로 구성되고, 그중 무엇이 실제로 동작하는가?
• 에이전트 루프(스키마 → 작성 → 추정 → 실행 → 교정)는 어떤 함수 호출로 이뤄지는가?
• 이 표면을 쓸 때 반드시 지켜야 하는 규칙과 하지 말아야 할 것은?

1. 사실 — 문제 정의

engine/src/agent/mod.rs 의 모듈 주석이 전제를 명시한다 (engine/src/agent/mod.rs:1-8):

The entity writing Cypher against this database is increasingly a language model, and it fails differently from a human. It invents labels, reverses relationship directions and writes accidental cartesian products — confidently. So the database owes it three things: an accurate machine-readable schema, errors that carry their own correction, and limits that stop a bad query before it stops the server.

spec 008 개요도 같은 세 가지를 든다 (specs/008-agent-native-interface/spec.md:13-20): 기계 판독 가능한 스키마 / 교정 가능한 오류 / 답의 출처 / "언제 기준으로 참인가".

LLM의 실패 양식은 사람의 실패 양식과 다르다. 사람은 모르면 문서를 찾지만, LLM은 확신에 차서 존재하지 않는 레이블을 만들어낸다. 그래서 "문서를 읽어라"는 해법이 성립하지 않고, 오류 응답 자체가 교정 정보를 실어야 한다.

2. 사실 — 표면의 구성과 구현 상태

spec 008 plan의 아키텍처 표 (specs/008-agent-native-interface/plan.md:21-31) 와 실제 코드를 대조한 결과다.

미구현 항목의 근거는 tasks.md의 미체크 항목이다 (specs/008-agent-native-interface/tasks.md:22-23, 27-28, 34, 37): T011(방문 노드 수 상한 주입), T012(반복 실패 질의 속도 제한), T014(결과별 기여 추적), T015(추론 근거 반환), T019(valid/transaction time 분리), T020(MCP 서버).

3. 사실 — 루프의 형태

원문 docs/agents.md:8-22 가 그리는 루프를, 실제 함수 호출로 다시 쓰면 다음과 같다. 모든 단계가 평문 SQL 호출이라는 점이 이 설계의 핵심이다 (spec 008 FR-034, specs/008-agent-native-interface/spec.md:281).

-- 1. 질문에 관련된 스키마만 받는다 (토큰 절약)
SELECT og_schema_for('meeting', '"라일락" 회의실을 어제 예약했던 사람 목록');

-- 2. (에이전트가 Cypher 작성)

-- 3. 구문만 먼저 확인한다 — DB 접근 없음, immutable
SELECT og_cypher_check($$MATCH (m:MeetingRoom) RETURN m.name$$);

-- 4. 실행 전 비용 추정
SELECT og_estimate('meeting', $$MATCH (a:Employee), (b:Employee) RETURN a.name, b.name$$);

-- 5. 실행
SELECT og_cypher('meeting',
  $$MATCH (e:Employee)<-[:RESERVED_BY]-(r:Reservation) RETURN e.name, r.purpose$$,
  '{}'::jsonb);

-- 6a. 오류였다면: 구조화된 교정 정보
SELECT og_explain_error('meeting', $$MATCH (p:Emploee) RETURN p$$);

-- 6b. 0행이었다면: 어느 패턴 단계에서 죽었는가
SELECT og_diagnose_empty('meeting',
  $$MATCH (e:Employee)<-[:RESERVED_BY]-(r:Reservation) RETURN e.name$$);

주의: 5번과 6번 사이에 트랜잭션 경계가 있다. og_cypher 가 실패하면 error! 로 트랜잭션이 중단되므로(engine/src/cypher/mod.rs:96-98, 140), 6a/6b는 새 트랜잭션에서 호출해야 한다. 같은 트랜잭션에서 이어 호출하면 current transaction is aborted 를 받는다.

4. 결정(Decision) — 왜 이렇게 설계되었는가

D-1. LLM 호출은 DB 안에 두지 않는다 (예외 1건)

spec 008은 자연어→Cypher 변환을 명시적으로 범위 밖에 둔다 (specs/008-agent-native-interface/spec.md:326-328). 유일한 예외인 genai.vector.encode 는 임베딩 호출인데, 이것조차 "Neo4j가 같은 결론에 도달해 같은 이름의 함수를 추가했기 때문"으로 정당화되고 (engine/src/compat/genai.rs:10-11), 기본 비활성이다.

D-2. 오류는 문자열이 아니라 구조체다

og_explain_error 는 {ok, code, message, stage, suggestions} 를 낸다 (engine/src/agent/mod.rs:264-289). code 가 안정적이어야 에이전트의 재시도 분기가 성립한다(FR-011).

D-3. 스키마는 잘라내되, 잘랐다고 말한다

og_schema 는 예산 초과 시 truncated 객체를 응답에 넣는다 (engine/src/agent/mod.rs:101-111). 모듈 주석의 표현: "an agent given a truncated schema it knows is truncated behaves better than one given a complete schema it cannot afford to read" (engine/src/agent/mod.rs:17-20).

D-4. 이력이 없으면 현재 값을 반환하지 않고 오류를 낸다

og_as_of 는 이력이 없는 엔티티에 대해 명시적으로 error! 를 던진다 (engine/src/agent/mod.rs:511-516): "returning the current value instead would be a lie". FR-021의 직접 구현이다.

D-5. 사용자 값은 SQL 텍스트로 보간하지 않는다

og_cypher(graph, query, params jsonb) — 파라미터는 jsonb 하나로 바인딩되고 (engine/src/cypher/mod.rs:84-88), 컴파일된 SQL 안에서 ($1 ->> 'name') 형태로 참조된다 (engine/src/cypher/compile.rs:1156-1157). spec 003 FR-026.

5. 금지(Forbidden) / 필수(Required)

필수

• 에이전트에게 Cypher를 생성시키기 전에 og_schema_for 또는 og_schema 를 먼저 호출할 것. 스키마 없이 생성한 Cypher는 레이블을 지어낸다.
• 스키마 응답의 schema_version 을 캐시 키로 쓸 것 (engine/src/agent/mod.rs:24-30, 90). 값이 그대로면 컨텍스트에 유지하고, 바뀌면 다시 받는다.
• 응답에 truncated 가 있으면, 그 사실을 프롬프트에 그대로 넘길 것.
• 오류 진단 함수(og_explain_error, og_diagnose_empty)는 실패한 트랜잭션 밖에서 호출할 것.
• 사용자 입력은 반드시 params jsonb로 전달할 것. 질의 문자열에 보간 금지.

금지

• og_explain_error 의 {"ok": true} 를 "이 질의는 결과가 있다"로 해석하지 말 것. 존재하지 않는 레이블은 컴파일에 성공하고 0행을 반환한다 (engine/src/catalog/types.rs:160-175, engine/src/cypher/compile.rs:709-715). 상세는 03_correctable_errors.md 4절.
• og_estimate 의 would_run: true 를 안전 보증으로 쓰지 말 것. advice 배열이 비었다는 뜻일 뿐이고, 판정 기준은 세 개의 하드코딩된 임계값이다 (engine/src/agent/mod.rs:374-388).
• og_apply_role 이 적용한 og.max_rows 가 행 수를 제한한다고 가정하지 말 것. 저장소 어디에서도 이 GUC를 읽지 않는다 (근거: 08_guardrails_and_roles.md 3절).
• 에이전트에게 og_set_setting 실행 권한을 주지 말 것. 임베딩 엔드포인트 URL을 바꿀 수 있게 되고, 이는 SSRF 경로다 (engine/src/compat/genai.rs:55-63, 상세는 05_embedding_pipeline.md 6절).

6. 참고

• 원문: docs/agents.md
• 함수 계약: docs/api.md "Agents — spec 008" 절 (169-185행)
• 스펙: specs/008-agent-native-interface/spec.md, specs/008-agent-native-interface/plan.md, specs/008-agent-native-interface/tasks.md