‘Cognitive Interface’: UI와 API를 넘어
Source: Dev.to
인식 격차
전통적인 API는 컴파일러와 인간 개발자를 위해 설계되었습니다. 개발자가 API를 사용할 때는 문서를 읽고, 엣지 케이스를 이해하며, 이를 처리하는 코드를 작성합니다. 머신이 gRPC를 통해 다른 머신을 호출할 때는 엄격한 바이너리 계약에 의존합니다.
AI 에이전트는 다르게 작동합니다. 이들은 의미론적 렌즈를 통해 시스템을 “인식”합니다. API에 인지 인터페이스가 없으면 에이전트는 상황을 “환상”으로 추정해야 합니다.
진정으로 AI‑Perceivable하려면 모듈은 인지의 세 단계를 거쳐야 합니다:
- Perception – “Payments를 처리한다고 주장하는 도구가 존재함을 확인했습니다.”
- Understanding – “이 도구가
destructive이며,mfa_approval이 필요하고, $500 초과 금액에는 사용해서는 안 된다는 것을 이해했습니다.” - Execution – “올바른 JSON 스키마를 생성하고, 잔액이 부족할 경우 구조화된 오류를 처리할 수 있습니다.”
Swagger/OpenAPI만으로는 충분하지 않은 이유
많은 개발자들이 “이미 Swagger 문서가 있는데, 이것도 인지 인터페이스가 아니겠어요?” 라고 생각합니다.
정확히는 아닙니다. Swagger (OpenAPI)는 사람이 읽기 쉽고, 도구가 클라이언트 SDK를 생성하도록 설계되었습니다. AI가 자율적으로 판단하기 위해 필요한 행동 의미론이 부족합니다.
- Swagger가 특정 엔드포인트가 “비용이 많이 든다”거나 “느리다”는 정보를 에이전트에게 제공하나요?
- “일반적인 실수”나 “이 도구를 사용하면 안 되는 경우”를 설명하나요?
- 403 오류에서 복구하는 방법에 대한 “AI‑전용 가이드”를 제공하나요?
apcore 표준에서 정의한 진정한 인지 인터페이스는 기술 API를 감싸는 의미론적 레이어를 제공합니다.
인지 인터페이스의 아키텍처
apcore에서는 Progressive Disclosure 시스템을 통해 인지 인터페이스를 구현합니다. 우리는 LLM의 컨텍스트 창을 한 번에 모든 세부 정보로 압도하지 않습니다.
1. Discovery 레이어 (description)
AI가 후보 도구를 찾는 데 사용하는 “인덱스” 역할을 하는 짧은, 약 100자 문자열입니다.
예시: "Send encrypted emails via ProtonMail API."
2. Planning 레이어 (annotations)
코드의 “성격”을 AI에게 알려주는 구조화된 메타데이터입니다.
예시: readonly=False, destructive=True, requires_approval=True.
3. Cognition 레이어 (documentation)
AI가 작업에 사용할 도구를 선택한 후에만 읽는 상세하고 Markdown 형식에 맞춘 문서입니다. 여기에는 사용 예시, 비즈니스 제약 조건, 그리고 함정이 포함됩니다.
# A Cognitive Interface in apcore (Python)
class FinancialTransferModule(Module):
description = "Transfer funds between internal accounts."
documentation = """
## Constraints
- Maximum transfer: $10,000 per transaction.
- Requires 'finance_admin' role in the context.
- Post‑condition: Both account balances are updated atomically.
## Common Mistakes
- Don't use this for external wire transfers; use `executor.wire.transfer` instead.
"""
annotations = ModuleAnnotations(
destructive=False,
requires_approval=True, # Critical cognitive stop‑sign
cacheable=False
)“번역 세금” 해소
Enterprise AI integration은 현재 무거운 Translation Tax에 시달리고 있습니다. 개발자들은 API를 LLM에 설명하기 위해 “tool wrappers”와 “system prompts”를 수동으로 작성하는 데 수천 시간을 소비합니다.
apcore와 같은 AI‑Perceivable 표준으로 구축하면 이 세금을 없앨 수 있습니다. 모듈 is the documentation. 스키마 is the contract. 주석 are the governance.
우리가 “Agentic Operating Systems”로 나아가면서, Cognitive Interface는 Windows의 UI가, Web의 API가 그랬던 것처럼 기본적인 요소가 될 것입니다.
What’s Next?
다음 기사에서는 방 안의 코끼리 문제를 다룹니다: apcore가 MCP (Model Context Protocol)와 LangChain과는 어떻게 연관되는가? 경쟁자인가, 아니면 누락된 기반인가?
Stay tuned.
This is Article #2 of the apcore: Building the AI‑Perceivable World series. Join the movement toward structured AI‑machine interaction.
GitHub