Claix로 AI 에이전트가 SQL 없이 데이터베이스를 조회한다

Claix: AI 에이전트를 위한 통제된 데이터베이스 조회

Claix 저장소

Postgres 또는 Supabase 데이터베이스를 연결하고, 각 AI 에이전트가 지정한 테이블과 열에 읽기 전용으로 접근하도록 설정할 수 있다. 에이전트는 일상적인 말로 질문하고 REST, MCP, A2A를 통해 검증된 결과나 지정한 형식의 답변을 받는다.

웹사이트 · 문서 · A2A Agent Card · MCP 서버

Claix는 AI 에이전트를 위한 호스팅형 데이터베이스 조회 서비스다. 에이전트와 관계형 데이터베이스 사이에서 작동하므로 에이전트가 테이블을 대상으로 SQL을 작성하거나 데이터베이스 연결을 직접 보유할 필요가 없다.

사용자의 Postgres 또는 Supabase 데이터베이스(읽기 전용 역할)
        ↓ Data Map: 테이블, 열, 관계
        ↓ Routes: 사용할 수 있는 테이블과 열, 사용 방법
        ↓ Agent: 개별 엔드포인트, 업무 프롬프트, routes
        ↓ 검증된 결과 또는 지정한 형식의 답변
        ↓ 사용자의 애플리케이션, 워크플로 또는 AI 에이전트

Claix는 데이터를 복사하거나 데이터에 대한 색인을 만들지 않는다. 에이전트는 데이터가 있는 데이터베이스에서, 허용된 데이터만 조회한다.

• OpenAPI 명세
• A2A Agent Card
• MCP 서버

Claix를 사용하는 이유

데이터베이스의 실제 데이터가 필요한 에이전트를 구현하는 방법은 흔히 두 가지지만, 각각 문제가 있다. 프레임워크를 사용해 쿼리 도구와 권한 검사, 로깅을 직접 만들고 호스팅·유지보수하거나, 모델에 데이터베이스 연결을 주고 SQL을 작성하게 하는 방법이다. 후자는 데모에서는 작동할 수 있지만 운영 환경에서는 위험하다. 모델이 읽는 텍스트에 숨겨진 지시로 조작될 수 있고, 오류 없이 실행되지만 잘못된 답을 내는 쿼리를 작성할 수도 있으며, 모델이 무엇을 했는지 파악하기 어렵다.

Claix는 두 방법 대신 데이터베이스에 읽기 전용 역할로 연결하고, 에이전트별로 사용할 테이블과 열을 정하며, 업무 규칙을 일상적인 말로 적도록 한다. 작성할 코드나 직접 호스팅할 서비스는 없다. 에이전트는 자신의 엔드포인트로 질문을 보내고 지정된 형식의 답변을 받는다. 프레임워크처럼 사용자가 기반을 만들어 가는 도구가 아니라 호출해서 사용하는 서비스다.

Claix가 설명하는 설계 원칙은 에이전트가 데이터베이스 구조, SQL, 권한이 아니라 맡은 업무를 추론하도록 역할을 나누는 것이다. 에이전트가 볼 수 있는 데이터는 설정한 범위에 한정되며, 조작된 프롬프트가 설정 이상의 접근 권한을 주지는 않는다. 모든 답변을 확인하고 시험할 수 있다.

주요 기능은 다음과 같다.

• 읽기 전용 접근: 사용자가 만들고 제한한 데이터베이스 역할로 연결한다.
• Data Map: 테이블, 열, 관계를 일상적인 말로 설명한다. Claix가 초안을 만들고 사용자가 검토한다.
• Routes: 사용할 테이블과 열, 업무 규칙에 대한 간단한 안내를 정한다.
• Agents: 에이전트마다 별도의 엔드포인트, 업무 프롬프트, routes를 둔다.
• 지정 형식 답변: 문자열, 정수, 불리언, 배열, 객체 형식으로 요청하고 해당 형식의 답변을 받는다.
• 요청당 여러 질문: 질문 목록을 보내고 입력한 순서대로 답변을 받는다.
• Traces: 질문, 선택된 route, 실행된 쿼리, 결과를 요청별로 기록한다.
• Sandbox: 애플리케이션에 연결하기 전에 실제 질문으로 에이전트를 시험한다.
• REST, MCP, A2A: 코드, MCP 클라이언트, 다른 에이전트에서 호출할 수 있다.
• 관리형 AI 또는 BYOK: Claix 모델 스택을 쓰거나 지원되는 제공자의 키를 가져올 수 있다.

저장소에는 빠른 시작, 개념, API 개요, 응답 모드, 통합, Claix Ingest, 오류 처리, LLM 키와 가격, 보안 관행, 제한 사항, 추가 자료를 안내한다.

설정과 사용

먼저 에이전트가 사용할 테이블과 열만 읽을 수 있는 전용 역할을 데이터베이스에 만든다. 필요한 권한만 부여해야 한다.

CREATE ROLE claix_agent WITH LOGIN PASSWORD 'use-a-secret-manager'
 NOSUPERUSER NOCREATEDB NOCREATEROLE NOINHERIT NOREPLICATION NOBYPASSRLS
 CONNECTION LIMIT 10;

GRANT CONNECT ON DATABASE mydb TO claix_agent;
GRANT USAGE ON SCHEMA public TO claix_agent;

-- Grant only the columns agents may use
GRANT SELECT (id, name, country) ON public.customers TO claix_agent;
GRANT SELECT (id, customer_id, status, total) ON public.orders TO claix_agent;

저장소는 이 역할이 실제 접근 경계라고 강조한다. 역할이 읽을 수 있는 데이터는 에이전트도 요청할 수 있으므로 권한을 가능한 한 좁게 설정하고, 슈퍼유저나 애플리케이션의 주 데이터베이스 계정을 사용하지 말아야 한다.

Claix 대시보드의 Database connection에서 claix_agent 역할의 접속 정보를 등록한다. 현재 지원하는 데이터베이스는 Postgres와 Supabase다. 이어서 Claix가 해당 역할로 볼 수 있는 구조를 읽어 작성한 Data Map을 검토하고 수정한 뒤 게시한다. Data Map에는 각 테이블 설명과 발견한 관계, 제안한 관계가 포함된다.

그다음 한 가지 목적에 사용할 테이블과 열, 규칙과 용어를 설명하는 안내를 묶어 route를 만든다. 예를 들어 주문 상태용 route에는 orders.status와 orders.total을 허용하고, cancelled 상태의 주문도 테이블에 남는다는 규칙을 적을 수 있다.

에이전트에는 이름, 짧은 설명, 업무와 각 route의 사용 시점을 설명하는 업무 프롬프트, 사용할 routes, 응답 모드를 설정한다. 이름은 /agent/{name} 형식의 엔드포인트가 된다. 응답 모드는 원시 결과를 반환하거나 추론을 거쳐 지정 형식으로 답하는 방식 중 하나다.

다음 예시는 질문 세 개를 에이전트에 보내는 호출과 응답이다.

curl -X POST "https://claix.dev/agent/hr-assistant" \\
 -H "x-api-key: YOUR_API_KEY" \\
 -H "Content-Type: application/json" \\
 -d '{
 "questions": [
 { "question": "What is the phone number of the employee named Carlos?", "format": "string" },
 { "question": "Has the customer Javier Perez accepted marketing consent?", "format": "boolean" },
 { "question": "What is the job title of Marta?", "format": "string" }
 ]
 }'

[
 {
 "user_ask": [
 { "question": "What is the phone number of the employee named Carlos?", "format": "string" },
 { "question": "Has the customer Javier Perez accepted marketing consent?", "format": "boolean" },
 { "question": "What is the job title of Marta?", "format": "string" }
 ],
 "ia_response": [null, true, "Waiter"],
 "log_id": "9ff38974-1392-4c1a-83e5-3b2f09bb43dc"
 }
]

답변은 질문 순서대로 반환된다. null은 에이전트가 사용할 수 있도록 허용된 데이터에서 답을 찾지 못했다는 뜻이며, Claix가 값을 만들어 내지는 않는다.

개념상 연결은 읽기 전용 역할로 데이터베이스를 연결하는 설정이다. Data Map은 테이블, 열, 관계에 대한 설명으로, 변경을 명시적으로 관리하도록 버전 단위로 게시한다. Route는 한 가지 목적에 쓸 수 있는 테이블과 열, 규칙 안내를 묶는다. Agent는 질문을 보내는 주체로, 자체 엔드포인트와 업무 프롬프트, routes를 가진다. 응답 모드는 원시 결과와 추론을 거친 지정 형식 답변 중 반환 방식을 정한다. Trace는 질문, 선택된 route, 실행된 쿼리, 결과를 기록한다. Sandbox에서는 실제 질문으로 에이전트를 시험한다.

Route는 어떤 데이터를 조회할 수 있는지 정하고, agent는 누가 어떤 routes를 이용하는지 정한다. routes를 여러 에이전트가 공유할 수 있으므로 지원 봇과 내부 도우미가 같은 데이터베이스를 사용하면서도 서로 다른 데이터를 보도록 설정할 수 있다.

업무 프롬프트는 에이전트의 업무, 각 route를 사용할 상황, 용어의 뜻, 답변하면 안 되는 내용을 설명하는 안내이지 보안 경계가 아니다. 실제 접근 범위는 데이터베이스 역할과 routes가 결정한다. 예를 들어 예약 도우미에 Bookings route는 예약과 테이블 질문에, Staff route는 근무 일정과 직무 질문에 사용하라고 안내할 수 있다. 결제 질문에는 답하지 말고 정보가 없다고 말하도록 지정하고, 상태 코드 C는 확정, P는 대기, X는 취소라고 설명할 수 있다.

API와 응답

모든 Claix API 호출에는 API 키가 필요하다. 전용 x-api-key 헤더를 권장하며, Authorization: Bearer 방식도 사용할 수 있다.

x-api-key: YOUR_API_KEY

Authorization: Bearer YOUR_API_KEY

API 키는 서버 자격 증명이다. 브라우저 코드, 모바일 앱, 공개 저장소, 스크린샷, 클라이언트 측 워크플로, 로그에 노출하지 말아야 한다. 서버 측 환경 변수나 비밀 정보 관리 도구에 보관해야 한다. 키가 있으면 해당 키로 호출할 수 있는 에이전트의 허용 데이터에 접근할 수 있다.

에이전트 엔드포인트는 POST https://claix.dev/agent/{name}이다. 요청의 questions에는 질문을 최대 5개까지 넣을 수 있다. 각 항목의 question은 일상적인 말로 쓴 질문이며, format에는 기대하는 형식인 string, integer, boolean, array, object 중 하나를 지정한다. 질문은 서로의 내용을 참조하지 않고 각각 독립적으로 처리되므로, 각 질문을 따로 읽어도 의미가 통하도록 작성해야 한다.

응답의 user_ask에는 보낸 질문이, ia_response에는 같은 순서로 지정한 형식에 맞춘 답이 들어간다. log_id는 해당 요청을 대시보드에서 찾을 수 있는 식별자다. 이를 이용해 정확한 요청의 Trace를 확인하고, 어떤 route가 답했는지와 어떤 쿼리가 실행됐는지 살펴보거나, 자체 워크플로 실행과 연결하고, 지원 문의에 참조 번호로 제공해 감사 기록을 만들 수 있다.

응답 모드는 두 가지다. Data 모드는 두 번째 모델 호출 없이 쿼리 결과를 그대로 반환하며, 결과를 처리하는 코드나 다른 에이전트에 적합하다. 기본 모드다. Answer 모드는 추론을 거친 뒤 요청한 형식으로 답하며, 사람에게 바로 전달할 결과나 단일 값이 필요한 워크플로에 적합하다. 이 모드에서는 쿼리 결과를 모델에 보내 답을 작성하므로 모델 호출이 추가돼 지연 시간과 비용이 늘어난다. 데이터가 모델 제공자에게 전달되므로 민감한 데이터라면 이를 고려해야 한다.

연동과 별도 제품

모든 에이전트는 세 가지 인터페이스로 이용할 수 있다. REST 엔드포인트는 백엔드, 스크립트, n8n, Make, Zapier 등 HTTP 요청을 보낼 수 있는 도구에서 호출한다. MCP 서버는 AI 비서, 코딩 도구, MCP 지원 클라이언트에 제공된다.

https://claix.dev/mcp

서버 메타데이터는 다음 주소에서 확인할 수 있다.

https://claix.dev/.well-known/mcp/server-card.json

클라이언트 설정 예시는 다음과 같다.

{
 "mcpServers": {
 "claix": {
 "url": "https://claix.dev/mcp",
 "headers": {
 "x-api-key": "YOUR_API_KEY"
 }
 }
 }
}

Claix는 기본 Agent-to-Agent(A2A) 에이전트이기도 하다. A2A 호환 에이전트와 오케스트레이터는 공개 Agent Card를 통해 Claix를 찾아 데이터 질문을 위임할 수 있다.

https://claix.dev/.well-known/agent-card.json

A2A JSON-RPC 엔드포인트는 다음과 같다.

https://claix.dev/a2a

전체 내용은 A2A 문서를 참고한다. Python SDK는 pip install claix로 설치할 수 있으며, 현재 제공되는 메서드는 SDK 문서에 안내돼 있다.

Claix Ingest는 데이터베이스에 데이터를 넣기 위한 별도 제품이다. 문서, 스프레드시트, 이미지, 텍스트, HTML, XML, 오디오를 스키마에 맞고 출처를 추적할 수 있는 JSON으로 변환해 사용자의 테이블에 적재할 수 있다. 데이터가 데이터베이스에 들어간 뒤에는 Claix Retrieve가 해당 데이터를 대상으로 질문에 답할 수 있다.

• Excel / CSV: POST /api/excel-json
• PDF: POST /api/pdf-json
• 문서(Word, 텍스트, Markdown, RTF): POST /api/doc-json
• 이미지: POST /api/img-json
• 텍스트 / HTML / XML: POST /api/txt-json
• 오디오: POST /api/audio-json

Ingest는 출처 추적, 지속 문서 컨텍스트, Knowledge Spaces를 지원한다. 기존 통합도 계속 작동한다. 자세한 내용은 문서를 참고한다.

오류, 비용, 보안과 제약

오류 응답은 다음과 같은 형태를 사용한다.

{
 "error": "Human-readable error message.",
 "detalle": "Optional technical detail.",
 "log_id": "9ff38974-1392-4c1a-83e5-3b2f09bb43dc"
}

상태 코드 200은 요청 성공을 뜻한다. 400은 잘못된 요청, 필수 필드 누락, 형식이 잘못된 페이로드이므로 요청을 수정해야 한다. 401은 API 키 누락, 무효, 비활성 또는 정지 상태로, 자격 증명을 바로잡아야 한다. 404는 에이전트가 없거나 다른 계정에 속한 경우다. 405는 HTTP 메서드가 잘못된 경우이며 문서에 지정된 메서드를 사용해야 한다. 413은 요청이 한도를 초과한 경우로 입력을 줄여야 한다. 이 네 오류는 요청을 바꾸지 않고 재시도하지 말아야 한다. 429는 요청 한도 초과를 뜻하며 재시도할 수 있다. 제공되면 Retry-After를 따른다. 500은 Claix 내부 오류로 신중하게 재시도한다. 502는 AI 제공자 또는 처리 과정의 일시적 실패로, 지수 백오프를 적용해 재시도한다.

모델 선택과 요금은 다음과 같이 안내돼 있다.

• Claix Managed AI: 제공자 설정 없이 관리형 모델을 사용하려는 팀을 위한 옵션이며 질문당 €0.10이다.
• Bring Your Own Key(BYOK): 모델을 선택하고 제공자 비용을 직접 관리하려는 팀을 위한 옵션이며 질문당 €0.02에 제공자 사용료가 추가된다.

요금은 질문 단위다. 한 요청에 질문이 여러 개 있으면 각 질문을 별도로 계산한다. BYOK도 AI 추론이 무료라는 뜻은 아니며, 토큰 및 기타 사용량에 대해 제공자가 요금을 청구한다. 자체 키를 쓰면 결과가 선택한 모델에 따라 달라지므로 운영 적용 전에 자체 routes로 Sandbox에서 시험해야 한다. 시작 시 무료 질문이 포함되며, 현재 세부 사항은 가격 페이지에서 확인할 수 있다. 대시보드의 LLM Keys에서 키를 추가하고 관리한다. 키는 암호화해 저장하며 에이전트 요청 실행에만 사용한다고 Claix는 설명한다.

저장소가 권고하는 보안 관행은 다음과 같다.

• Claix 전용 읽기 전용 데이터베이스 역할을 만들고, 에이전트에 필요한 테이블과 열에만 SELECT를 허용한다. 민감한 데이터에는 뷰를 우선 고려한다.
• 슈퍼유저나 애플리케이션의 주 데이터베이스 계정을 사용하지 않는다.
• API 키와 데이터베이스 암호는 비밀 정보 관리 도구 등 서버 측에 보관하고 정기적으로 교체한다.
• 가능하면 개발, 스테이징, 운영에 서로 다른 API 키를 사용한다.
• 데이터베이스의 모든 내용을 신뢰할 수 없는 입력으로 취급한다. 텍스트 열에 에이전트를 겨냥한 지시가 들어갈 수 있으므로 쿼리 결과가 애플리케이션 규칙을 덮어쓰게 해서는 안 된다.
• 테이블 주석, routes, 업무 프롬프트에 비밀 정보나 개인정보를 넣지 않는다.
• 권한을 업무 프롬프트에 맡기지 않는다. 권한은 데이터베이스 역할과 routes로 결정한다.
• Trace를 정기적으로 검토하고 중요한 워크플로 결정에는 log_id를 함께 보관한다.
• 결제, 승인, 접근 권한 변경, 법적 판단처럼 영향이 큰 작업에는 자체 검증 절차를 추가한다.
• 데이터베이스 암호를 알고 있던 팀원이 떠나면 암호를 교체한다.

저장소가 밝힌 한계도 있다. 에이전트별 접근 제어이지 최종 사용자별 접근 제어는 아니다. 에이전트는 모든 사용자 요청에서 자신에게 허용된 데이터를 전부 읽을 수 있다. 사람마다 자기 행만 보게 하려면 데이터베이스나 애플리케이션에서 이를 강제해야 한다. 현재는 Postgres와 Supabase만 지원하며 다른 데이터베이스는 아직 지원하지 않는다. Claix는 호스팅 서비스이며 자체 호스팅할 수 없다. 쿼리는 모델이 작성하므로 유효하고 허용된 쿼리라도 질문에 맞지 않는 답을 낼 수 있다. 명확한 테이블 설명과 관계, Trace가 이를 발견하는 데 도움을 준다고 안내한다. Claix는 읽기 전용으로 데이터를 변경하지 않으며, 데이터 적재는 Claix Ingest 같은 별도 절차가 필요하다. 분석 도구도 아니어서 대시보드나 차트를 제공하지 않고 에이전트에 데이터와 답변을 반환한다.

추가 자료와 저장소

• AI 에이전트가 Postgres를 안전하게 조회하도록 하는 방법
• AI 에이전트를 위한 읽기 전용 Postgres 역할
• AI 에이전트를 위해 데이터베이스를 문서화하는 방법
• 텍스트-SQL 에이전트 시험 방법
• AI 에이전트를 위한 최적의 데이터베이스 접근 계층

저장소에는 호스팅형 Claix API의 예제와 연동 안내가 담겨 있다. Python, JavaScript, Node.js, PHP, n8n 예제와 일반적인 사용 사례의 route 및 업무 프롬프트 예제, A2A 및 MCP 클라이언트 연동, 문서 개선, 보안·신뢰성 안내에 대한 기여를 받는다. 실제 API 키, 데이터베이스 자격 증명, 비공개 문서, 고객 기록은 커밋하지 말아야 한다.

달리 명시되지 않은 한 저장소의 코드 예제와 문서는 MIT License를 따른다. 이 저장소는 호스팅 서비스인 Claix의 API 예제와 연동 안내를 제공하며, 자체 호스팅 배포판은 제공하지 않는다. 최신 엔드포인트, 한도, 지원 데이터베이스, 가격, 제품 약관은 공식 Claix 문서를 확인해야 한다.