GPT, Claude, Gemini, DeepSeek, Grok을 모두 사용하는 하나의 AI 앱을 만들고 싶다면, 공통 요청 경로에는 통합 API를 쓰고 라우팅 정책은 애플리케이션 내부에 유지하세요. CometAPI는 OpenAI 호환 base URL과 공유 모델 카탈로그를 제공하므로, Python 서비스가 하나의 클라이언트로 서로 다른 모델 ID를 호출할 수 있습니다. 어떤 모델을 실행할지, 어떤 도구를 허용할지, 언제 폴백이 안전한지는 여전히 여러분의 코드가 결정합니다.
이 튜토리얼은 두 개의 읽기 전용 비즈니스 도구를 요청하고, 실행 전에 알 수 없는 도구와 잘못된 인자를 거부하며, 선택된 일시적 장애에서만 계약 검증을 통과한 다른 모델로 전환하는 Grok 4.7 에이전트를 만듭니다. 목표는 마법 같은 자율 시스템이 아닙니다. 프로덕션에서 테스트하고 운영할 수 있는 작고 점검 가능한 루프입니다.
무엇을 만들 것인가
에이전트는 다섯 가지 명시적 구성 요소로 이루어집니다:
- 하나의 CometAPI 클라이언트. 아래 설정과 같이 OpenAI Python SDK가 CometAPI의 API base URL을 사용합니다.
- 기본 모델로 Grok 4.7. 현재 CometAPI 모델 ID는
grok-4.7입니다. - 도구 레지스트리. 모델이 함수 호출을 제안할 수 있지만, 허용 목록에 있는 함수만 애플리케이션 코드가 실행합니다.
- 제한된 에이전트 루프. 루프는 무한히 돌지 않고 고정된 모델 턴 수 후에 중지됩니다.
- 순서가 있는 폴백 정책. 재시도 가능한 모델/API 실패가 있을 때만 호환되는 GPT, Claude, Gemini, DeepSeek 모델 ID를 시도합니다.
Grok 4.7은 함수 호출을 지원하며, CometAPI는 현재 모델에 대해 /v1/chat/completions와 /v1/responses 라우트를 모두 문서화합니다. 이 튜토리얼은 Chat Completions를 사용합니다. OpenAI 호환 tools, 어시스턴트의 도구 호출, 그리고 이에 매칭되는 tool 결과 메시지가 컴팩트하고 점검 가능한 Python 루프에 직접 매핑되기 때문입니다. 전송 계층 호환성은 모든 모델에서 기능 동등성을 보장하지 않으므로, 구성된 모든 폴백은 프로덕션 도입 전에 동일한 계약 테스트를 통과해야 합니다.
다중 턴 Grok 4.7 에이전트의 추론 상태
Grok 4.7은 low, medium, high, xhigh 추론 노력을 수용하며 기본값은 high입니다. xAI의 Responses API에서는 모든 Grok 4.7 응답에 reasoning.encrypted_content가 포함됩니다. 클라이언트가 관리하는 다중 턴 루프는 반환된 추론 항목을 다음 요청에 변경 없이 전달해야 합니다. 긴 루프는 context compaction도 사용할 수 있습니다. 반환된 compaction 항목을 불투명 상태로 보존하고 그 뒤에 새 턴을 추가합니다. 이는 상태ful하며 공급자별 응답 필드이므로, 프로덕션 의존성을 만들기 전에 선택한 CometAPI 라우트가 이를 종단 간로 반환하는지 확인하세요.
에이전트 아키텍처: 모델이 제안하고, 애플리케이션이 결정한다
안전한 도구 호출 흐름은 단순합니다:
사용자 요청 → 모델 응답 → 도구 호출 검증 → 허용된 도구 실행 → 도구 결과 추가 → 모델 응답
모델은 데이터베이스 자격 증명을 받지 않으며 Python을 직접 실행하지 않습니다. “이 주문 ID로 get_order_status를 호출하라”와 같은 구조화된 요청을 생성합니다. 애플리케이션이 도구 이름을 확인하고, 인자를 파싱하고, 인가 및 비즈니스 규칙을 적용하고, 함수를 실행한 뒤 직렬화된 결과를 반환합니다.
이 분리는 모델 선택보다 중요합니다. 폴백 모델은 동일한 도구 경계(더 넓지 않은 것)를 상속해야 하며, 외부 콘텐츠를 포함하는 경우 도구 결과는 신뢰할 수 없는 데이터로 취급해야 합니다.
Python으로 Grok 4.7 AI 에이전트 만드는 법
1단계: OpenAI Python SDK를 CometAPI용으로 구성
OpenAI SDK 설치:
pip install openai
환경 변수로 구성 설정:
export COMETAPI_KEY="your-cometapi-key"
export PRIMARY_MODEL="grok-4.7"
export FALLBACK_MODEL_1="your-compatible-gpt-model-id"
export FALLBACK_MODEL_2="your-compatible-claude-model-id"
export FALLBACK_MODEL_3="your-compatible-gemini-model-id"
export FALLBACK_MODEL_4="your-compatible-deepseek-model-id"
이 튜토리얼은 Chat Completions를 사용합니다. 어시스턴트의 명시적인 도구 호출과 이에 대응하는 도구-결과 메시지가 제어 흐름을 컴팩트한 Python 예제에서 쉽게 점검할 수 있게 해주기 때문입니다. 더 긴 상태ful 루프에는 위에서 설명한 Responses API를 평가하세요. 또한, 예전 블로그 글의 모델 ID를 프로덕션에 그대로 복사하지 마세요. 배포나 시작 시점에 CometAPI의 공개 GET /api/models 카탈로그를 가져온 뒤, 모델 디렉터리에서 기능과 가격을 확인하세요.
import os
from openai import OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
timeout=30.0,
)
명시적인 타임아웃과 비활성화된 SDK 재시도는 의도적입니다. 애플리케이션이 실패를 분류하고 요청을 반복할지, 다음 모델로 이동할지를 결정합니다. 숨겨진 재시도는 지연 시간, 중복 부작용, 폴백 동작을 이해하기 어렵게 만듭니다.
2단계: 먼저 좁은 범위의 읽기 전용 도구 정의
데이터를 변경하기보다 읽는 도구부터 시작하세요. 아래 정의는 에이전트가 주문을 확인하고 재고를 조회할 수 있게 합니다. 구현은 데모 데이터를 반환합니다. 이를 인증된 자체 서비스 호출로 교체하세요.
import json
TOOLS = [
{
"type": "function",
"function": {
"name": "get_order_status",
"description": "하나의 주문에 대한 현재 상태를 읽습니다.",
"parameters": {
"type": "object",
"properties": {
"order_id": {"type": "string"}
},
"required": ["order_id"],
"additionalProperties": False,
},
},
},
{
"type": "function",
"function": {
"name": "check_inventory",
"description": "하나의 SKU에 대한 사용 가능한 재고를 읽습니다.",
"parameters": {
"type": "object",
"properties": {
"sku": {"type": "string"}
},
"required": ["sku"],
"additionalProperties": False,
},
},
},
]
def get_order_status(order_id: str) -> dict:
# 이 데모를 인증된 읽기 전용 서비스 호출로 교체하세요.
return {"order_id": order_id, "status": "in_transit"}
def check_inventory(sku: str) -> dict:
# 이 데모를 인증된 읽기 전용 서비스 호출로 교체하세요.
return {"sku": sku, "available_units": 12}
TOOL_REGISTRY = {
"get_order_status": get_order_status,
"check_inventory": check_inventory,
}
JSON 스키마는 요청의 형태를 개선하지만, 인가는 아닙니다. 인자 길이와 형식을 검증하고, 현재 사용자가 요청된 주문이나 SKU에 접근할 수 있는지 확인하며, 모델에 반환하기 전에 모든 도구 결과의 크기를 제한하세요.
3단계: 좁은 범위의 다중 모델 폴백 정책 추가
폴백은 깨진 요청을 숨기기보다 일시적인 라우트 장애에서 복구해야 합니다. CometAPI의 공식 폴백 가이드는 연결 오류, 타임아웃, HTTP 408, HTTP 429, 일시적 5xx 응답에서 다음 구성 라우트로 이동할 것을 권장합니다. 잘못된 자격 증명, 지원되지 않는 파라미터, 유효하지 않은 요청은 즉시 실패해야 합니다.
from openai import APIConnectionError, APIStatusError, APITimeoutError
def configured_models() -> list[str]:
names = [
os.getenv("PRIMARY_MODEL", "grok-4.7"),
os.getenv("FALLBACK_MODEL_1"),
os.getenv("FALLBACK_MODEL_2"),
os.getenv("FALLBACK_MODEL_3"),
os.getenv("FALLBACK_MODEL_4"),
]
return [name for name in names if name]
def is_retryable(error: Exception) -> bool:
if isinstance(error, (APIConnectionError, APITimeoutError)):
return True
if isinstance(error, APIStatusError):
return error.status_code in {408, 429} or error.status_code >= 500
return False
def complete_with_fallback(messages: list[dict], tools: list[dict]):
models = configured_models()
last_error = None
for index, model in enumerate(models):
try:
response = client.chat.completions.create(
model=model,
messages=messages,
tools=tools,
tool_choice="auto",
)
return response, model
except Exception as error:
last_error = error
final_route = index == len(models) - 1
if final_route or not is_retryable(error):
raise
raise RuntimeError("No configured model completed the request") from last_error
모델 목록은 구성이지, 품질 순위가 아닙니다. 이 에이전트에 필요한 동일한 메시지 역할, 도구 스키마, 입력 모달리티, 컨텍스트 요구 사항, 응답 동작을 지원하는 폴백을 선택하세요. 선택된 라우트와 전환을 유발한 실패를 로깅하세요.
4단계: 제한된 Grok 4.7 에이전트 루프 실행
아래 루프는 대화를 보내고, 허용 목록의 도구 호출을 실행하고, 일치하는 tool_call_id로 결과를 추가한 다음, 선택된 모델에 답변 완료를 요청합니다.
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
if name not in TOOL_REGISTRY:
return json.dumps({"error": f"허용되지 않은 도구: {name}"})
try:
arguments = json.loads(tool_call.function.arguments)
result = TOOL_REGISTRY[name](**arguments)
return json.dumps(result)
except (json.JSONDecodeError, TypeError, ValueError) as error:
return json.dumps({"error": f"잘못된 도구 인자: {error}"})
def run_agent(user_text: str, max_turns: int = 4) -> dict:
messages = [
{
"role": "system",
"content": (
"당신은 지원 에이전트입니다. 필요한 경우에만 도구를 사용하세요. "
"주문 또는 재고 데이터를 절대 만들어내지 마세요."
),
},
{"role": "user", "content": user_text},
]
route_log = []
for turn in range(max_turns):
response, model = complete_with_fallback(messages, TOOLS)
route_log.append({"turn": turn + 1, "model": model})
assistant = response.choices[0].message
messages.append(assistant.model_dump(exclude_none=True))
if not assistant.tool_calls:
return {
"answer": assistant.content,
"routes": route_log,
"usage": response.usage.model_dump() if response.usage else None,
}
for tool_call in assistant.tool_calls:
messages.append(
{
"role": "tool",
"tool_call_id": tool_call.id,
"content": execute_tool_call(tool_call),
}
)
raise RuntimeError("Agent stopped after reaching max_turns")
result = run_agent("주문 A-104는 어디에 있나요? 그리고 SKU BLUE-42는 재고가 있나요?")
print(result["answer"])
print(result["routes"])
이 코드는 하나의 모델 응답에서 여러 도구 호출을 지원합니다. 반환된 각 호출에 대한 결과를 추가하기 때문입니다. 만약 도구가 상태를 변경한다면(이메일 발송, 주문 생성, 환불 실행 등), 멱등성 키와 사람의 확인 단계를 추가하세요. 부작용이 이미 발생했을 수 있는 경우, 타임아웃 후에 전체 에이전트 턴을 맹목적으로 다시 시작하지 마세요.
GPT, Claude, Gemini, DeepSeek을 동일한 앱에 넣는 방법
CometAPI는 연결 계층 중복을 줄여줍니다. 하나의 계정, 공통 경로를 위한 하나의 OpenAI 호환 base URL, 그리고 애플리케이션 코드에서 선택하는 모델 ID. 그 결과 GPT, Claude, Gemini, DeepSeek, Grok이 하나의 내부 인터페이스 뒤의 후보가 됩니다.
이는 모델들이 상호 교환 가능하다는 뜻이 아닙니다. 폴백을 추가하기 전에 다음을 검증하세요:
- 현재 모델 ID가 CometAPI 카탈로그에서 반환되는지
- 라우트가 필요한 도구 스키마와 메시지 역할을 지원하는지
- 도구 호출 인자와 다중 호출 동작이 에이전트 계약에 부합하는지
- 컨텍스트 윈도와 입력 모달리티가 요청에 맞는지
- 응답이 사용자에게 전달되기 전에 검증 가능하지
- 지연 시간과 비용이 제품 예산을 벗어나지 않는지
공급자 고유 기능은 네이티브 엔드포인트나 별도 어댑터가 필요할 수 있습니다. 모든 기능을 공통 인터페이스로 억지로 넣기보다, 예외는 명시적으로 유지하세요.
Grok 4.7 다중 모델 폴백은 다중 에이전트와 다르다
다중 모델 폴백 체인은 라우트가 실패할 때 다른 모델을 선택합니다. 다중 에이전트 시스템은 예를 들어 계획자, 연구자, 검토자처럼 서로 다른 책임을 별도의 에이전트에 할당합니다. 둘은 다른 문제를 해결합니다.
이 Grok 4.7 에이전트를 다중 에이전트 워크플로로 확장한다면, 각 워커에 좁은 역할, 분리된 도구 허용 목록, 제한된 예산, 구조화된 인계 절차를 부여하세요. 모든 에이전트가 모든 도구를 호출하거나 무제한 전사를 전달할 수 있게 두지 마세요. 역할 분리가 결과를 개선한다는 평가 데이터가 입증될 때까지는 단일 에이전트로 시작하세요.
Grok 4.7 AI 에이전트의 프로덕션 안전장치
실행 전 검증
도구 이름, 인자 스키마, 테넌트 소유권, 사용자 권한, 레이트 리밋을 애플리케이션 코드에서 점검하세요. 도구 설명은 모델을 위한 가이드일 뿐, 보안 통제가 아닙니다.
읽기 도구와 쓰기 도구 분리
읽기 전용 도구는 인가 후 자동 실행이 가능할 때가 많습니다. 쓰기 도구는 더 강한 점검, 멱등성, 결과가 큰 행동에 대한 확인이 필요합니다.
모든 루프에 한계 설정
최대 모델 턴 수, 도구 호출 수, 총 경과 시간, 프롬프트 크기, 토큰 예산을 설정하세요. 한계에 도달하면 제어된 오류나 에스컬레이션 경로를 반환하세요.
의사결정 기록 보존
요청된 작업, 정책 버전, 선택된 모델 ID, 폴백 사유, 도구 이름, 도구 지연 시간, 검증 결과, 토큰 사용량, 최종 상태를 로깅하세요. 비밀이나 불필요한 고객 콘텐츠는 기록하지 마세요.
가정이 아닌 계약 테스트 사용
구성된 모든 모델에 동일한 픽스처를 실행하세요. 유용한 최소 테스트 스위트에는 정상 답변, 단일 도구 호출, 다중 도구 호출, 잘못된 인자, 알 수 없는 도구, 도구 타임아웃, 기본 모델 429, 폴백을 유발하면 안 되는 유효하지 않은 API 키가 포함됩니다.
배포 체크리스트
- 현재 모델 ID를 가져오고 배포 전에 Grok 4.7 라우트를 검증하세요.
- CometAPI 키는 소스 코드나 프롬프트가 아닌 시크릿 매니저에 보관하세요.
- 읽기 전용 도구와 명시적 JSON 스키마부터 시작하세요.
- 각 도구 호출 전에 인증과 테넌트 인가를 적용하세요.
- 분류된 일시적 오류에 대해서만 폴백을 허용하세요.
- 모든 폴백을 동일한 도구 호출 계약으로 테스트하세요.
- 쓰기 도구를 활성화하기 전에 멱등성과 확인 단계를 추가하세요.
- 루프, 지연 시간, 컨텍스트, 비용 한계를 설정하세요.
- API 가용성뿐 아니라 과업 성공을 측정하세요.
왜 CometAPI로 이 에이전트를 구축할까?
CometAPI는 공통 통합을 작게 유지하는 데 유용합니다. OpenAI Python SDK는 하나의 base URL을 가리키고, Grok 4.7은 모델 ID로 선택되며, 다른 공급자의 호환 모델을 동일한 애플리케이션 소유 라우팅 정책 뒤에 배치할 수 있습니다.
이는 팀이 제품 전반에 공급자별 연결 코드를 흩뿌리지 않고도 GPT, Claude, Gemini, DeepSeek, Grok을 평가할 여지를 제공합니다. 또한 중요한 경계를 보존합니다. CometAPI는 접근을 제공하고, 역량 점검, 도구 실행, 폴백 정책, 평가, 사용자 대상 동작은 애플리케이션이 소유합니다.
최신 Grok 4.7 모델 페이지를 검토하고, CometAPI 퀵스타트로 클라이언트를 구성하며, 프로덕션 폴백을 선택하기 전에 최신 모델 ID를 가져오세요.
FAQ
GPT, Claude, Gemini, DeepSeek이 있는 앱에는 어떤 API를 써야 하나요?
공통 채팅 및 도구 호출 경로에는 CometAPI 같은 OpenAI 호환 통합 API가 통합 작업을 줄여줄 수 있습니다. 모델 선택과 폴백 정책은 애플리케이션에 유지하고, 필요한 기능이 공유 계약에 맞지 않으면 공급자 네이티브 어댑터를 사용하세요.
Grok 4.7이 Python 함수를 직접 호출할 수 있나요?
Grok 4.7은 구조화된 함수 호출 요청을 반환할 수 있습니다. Python 애플리케이션이 요청을 파싱하고, 검증하고, 허용 목록의 함수를 실행한 뒤 결과를 모델에 다시 보냅니다. 모델 자체가 로컬 Python을 실행하지는 않습니다.
모든 오류가 다른 모델을 트리거해야 하나요?
아니요. 선택된 연결 실패, 타임아웃, 408, 429, 일시적 5xx 응답에서만 폴백을 사용하세요. 유효하지 않은 요청, 인증 실패, 지원되지 않는 파라미터는 다른 모델로 보내기보다 수정해야 합니다.
하나의 도구 스키마를 모든 모델에서 사용할 수 있나요?
테스트 후에만 가능합니다. 공유 전송 계층이 도구 동작, 인자 품질, 병렬 호출 동작, 스키마 강제의 동일성을 보장하지는 않습니다. 에이전트의 계약 테스트를 통과한 모델만 체인에 추가하세요.
다중 모델 폴백 시스템이 다중 에이전트 시스템인가요?
아닙니다. 폴백은 라우트 실패 후 요청에 사용되는 모델을 바꿉니다. 다중 에이전트 아키텍처는 서로 다른 작업을 별도의 에이전트에 할당합니다. 별도의 계층으로 구축하고, 별도의 테스트와 통제를 적용하세요.