xAI

xAI (Grok)

xAI의 Grok 모델은 XaiModel로 쓰면 돼요. 설치하고 API 키를 환경 변수로 설정한 뒤 이름으로 바로 에이전트를 만들 수 있어요. 이 통합은 API 호스트·타임아웃·gRPC 메타데이터 같은 고급 transport 설정과, 이미지 생성, X 검색, 추론 노력, 멀티 에이전트 모델 등 xAI 특유의 기능들을 함께 제공해요.

출처: 공식문서

설치

XaiModel을 쓰려면 pydantic-ai를 설치하거나 pydantic-ai-slim을 xai 옵션 그룹과 함께 설치해야 해요.

Terminal

pip install "pydantic-ai-slim[xai]"

Terminal

uv add "pydantic-ai-slim[xai]"

설정

xAI의 xAI 모델을 API로 쓰려면 console.x.ai에서 API 키를 만들어요.

docs.x.ai에 사용 가능한 xAI 모델 목록이 있어요.

환경 변수

API 키를 받았으면 환경 변수로 설정해요.

Terminal

export XAI_API_KEY='your-api-key'

이제 XaiModel을 이름으로 쓸 수 있어요.

from pydantic_ai import Agent

agent = Agent('xai:grok-4.3')
...

또는 직접 초기화할 수도 있어요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel

# Uses XAI_API_KEY environment variable
model = XaiModel('grok-4.3')
agent = Agent(model)
...

커스텀 provider로 XaiModel을 커스터마이즈할 수도 있어요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

# Custom API key
provider = XaiProvider(api_key='your-api-key')
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

게이트웨이, 리전, 프록시 배포에서는 provider를 커스텀 호스트로 가리키고 클라이언트 수준 기본 타임아웃을 설정할 수도 있어요. 둘 다 기본 xai_sdk.AsyncClient로 전달돼요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

provider = XaiProvider(
    api_key='your-api-key',
    api_host='gateway.example.com',
    timeout=30,
)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

api_host는 xAI API 서버의 호스트명이에요(SDK가 gRPC로 연결). timeout은 클라이언트가 만드는 모든 요청에 적용되는 기본 타임아웃(초)이에요. 다른 provider와 달리 xAI SDK는 요청별 타임아웃을 지원하지 않으므로 ModelSettings.timeout은 지원되지 않고 효과가 없어요. 둘 다 미설정이면 생략되어 SDK 자체 기본값이 적용돼요.

클라이언트가 만드는 모든 요청에 gRPC metadata를 붙일 수도 있어요. 대표적인 용도는 xAI 프롬프트 캐시 sticky routing으로, x-grok-conv-id로 대화를 캐시 노드에 고정해서 반복되는 접두사가 재처리 대신 캐시에서 서빙되게 하는 거예요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

provider = XaiProvider(
    api_key='your-api-key',
    metadata=(('x-grok-conv-id', 'my-conversation-id'),),
)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

metadata는 (key, value) 문자열 튜플의 시퀀스로 기본 xai_sdk.AsyncClient에 그대로 전달돼요. 그래서 캐시 히트 극대화에 대한 xAI SDK 자체 문서(maximizing cache hits)가 적용돼요. 클라이언트 범위이므로 provider를 통해 만든 모든 요청에 적용돼요. 고정된 x-grok-conv-id로 구성된 provider는 무관한 대화들 사이에 공유하면 안 돼요. 그러면 같은 캐시 노드에서 충돌하거든요. metadata가 대화별일 때는 대화별로 별도 provider를 쓰세요. api_host와 timeout처럼 미설정이면 생략되고, 커스텀 xai_sdk.AsyncClient가 넘겨지면 무시돼요.

아니면 커스텀 xai_sdk.AsyncClient로:

from xai_sdk import AsyncClient

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModel
from pydantic_ai.providers.xai import XaiProvider

xai_client = AsyncClient(api_key='your-api-key')
provider = XaiProvider(xai_client=xai_client)
model = XaiModel('grok-4.3', provider=provider)
agent = Agent(model)
...

이미지 생성

ImageGenerator를 xai: 이미지 모델과 함께 쓰면 공식 xAI SDK를 통해 직접 생성과 참조 이미지 편집이 가능해요.

from pydantic_ai import ImageGenerator
from pydantic_ai.images.xai import XaiImageGenerationSettings

generator = ImageGenerator(
    'xai:grok-imagine-image',
    settings=XaiImageGenerationSettings(aspect_ratio='16:9', xai_resolution='1k'),
)

xAI는 인라인·원격 참조 이미지와 UploadedFile로 표현된 xAI Files API ID를 받아요. 혼합 참조 입력은 SDK가 시퀀스를 재정렬할 필요가 없어야 해요. 공통 API와 지오메트리 동작은 image-generation 가이드를 보세요.

심사된 이미지

xAI는 조용히 심사해요. 이미지에 플래그를 붙이면 요청은 여전히 성공하고 플래그가 붙은 슬롯은 에러 대신 비어서 돌아와요. Pydantic AI는 플래그가 붙지 않은 이미지를 반환해서, 플래그가 붙은 이미지 하나가 당신이 요금을 낸 배치의 나머지를 버리지 않게 해줘요. 그리고 플래그가 붙은 위치를 provider_details['moderated_image_indices']로 보고해요.

그 키는 배치에서 xAI가 플래그를 붙인 0 기반 위치를 담고, 이미지가 하나 이상 플래그될 때만 존재해요. 그래서 len(result.images)에 플래그된 위치 수를 더하면 당신이 요청한 xai_n이 돼요. 모든 이미지가 플래그될 때만 ContentFilterError가 발생해요. 그때는 반환할 결과가 없으니까요.

X 검색

xAI 모델은 X(전 Twitter)에서 실시간 게시물과 콘텐츠를 검색하는 것을 지원해요. 권장하는 방법은 XSearch capability로 켜는 거예요. 크로스 provider 사용을 포함한 자세한 내용은 capability 문서를 보세요. 지원 옵션 전체 목록은 xAI X Search 문서를 보세요.

from datetime import datetime

from pydantic_ai import Agent
from pydantic_ai.capabilities import XSearch

agent = Agent(
    'xai:grok-4.3',
    capabilities=[
        XSearch(
            allowed_x_handles=['OpenAI', 'AnthropicAI', 'dasfacc'],
            from_date=datetime(2024, 1, 1),
            to_date=datetime(2024, 12, 31),
            enable_image_understanding=True,
            enable_video_understanding=True,
            include_output=True,
        )
    ],
)

result = agent.run_sync('What have AI companies been posting about?')
print(result.output)
"""
OpenAI announced their latest model updates, while Anthropic shared research on AI safety...
"""

XSearch capability가 받는 것:

• allowed_x_handles / excluded_x_handles: 최대 20개 X 핸들로 결과를 필터링(또는 제외)해요. 둘은 상호 배타적이에요.
• from_date / to_date: 주어진 datetime 범위 안에 만들어진 게시물로 결과를 제한해요(naive datetime은 UTC로 해석).
• enable_image_understanding (기본: False): 게시물에 첨부된 이미지를 분석해요.
• enable_video_understanding (기본: False): 게시물에 첨부된 비디오 콘텐츠를 분석해요.
• include_output (기본: False): 원시 X 검색 결과를 ModelResponse.native_tool_calls로 사용 가능한 NativeToolReturnPart에 포함시켜요. 이 값이 없으면 모델은 검색 결과를 내부적으로 쓰고 텍스트 요약만 반환해요. 켜면 검색된 게시물, 소스, 메타데이터에 프로그래매틱 접근이 가능해요.

capability의 대안으로, 더 낮은 수준의 XSearchTool을 capabilities=[NativeTool(XSearchTool(...))]로 직접 넘길 수 있어요. X Search Tool 문서를 보세요. 또는 XaiModelSettings.xai_include_x_search_output 모델 설정으로 원시 출력을 전역으로 켤 수도 있어요.

파일 첨부

사용자 프롬프트에 문서를 포함하면 xAI는 자동으로 지원되는 에이전트 모델에 attachment_search 도구를 사용 가능하게 해요. 모델이 그 도구를 쓰면 Pydantic AI가 그 생애주기를 모델 응답과 함께 노출해요. xAI는 각 파일을 48 MB로 제한해요. 지원되는 입력 형태는 문서 입력을 보세요.

NativeToolCallPart와 NativeToolReturnPart는 tool_name이 'attachment_search'이고, 호출의 provider_details['function_name']은 xAI가 실행한 작업의 자체 이름을 담아요(예: 'pdf_browse'). XaiModelSettings.xai_include_attachment_search_output을 True로 설정하면 xAI가 검색한 콘텐츠를 NativeToolReturnPart에 포함하도록 요청해요. 기본값은 False라서 켜지 않으면 그 옵션을 보내지 않아요.

Attachment search는 대화에 직접 첨부된 파일에 적용돼요. 영속 xAI 컬렉션을 검색하려면 대신 FileSearchTool을 쓰세요.

추론 노력

Grok 4.3은 reasoning_effort 값으로 'none', 'low', 'medium', 'high'를 지원해요. XaiModelSettings.xai_reasoning_effort로 직접 구성하거나, 크로스 provider ModelSettings.thinking 설정을 쓸 수 있어요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.3',
    model_settings=XaiModelSettings(xai_reasoning_effort='medium'),
)

xai_reasoning_effort='none'이나 thinking=False를 설정하면 Grok 4.3에서 추론을 끌 수 있어요. xAI는 몇몇 퇴역한 텍스트 모델 슬러그를 grok-4.3으로 리다이렉트해요. 예측 가능한 동작과 비용이 필요하면 grok-4.3과 명시적 추론 노력을 선택하세요. 자세한 내용은 xAI May 15 퇴역 가이드를 보세요.

Grok 4.5는 'low', 'medium', 'high'를 지원하지만 'none'은 지원하지 않아서 항상 추론해요. thinking=False는 조용히 무시되고 thinking=True는 'medium'으로 매핑돼요.

에이전트 턴

요청이 xAI의 서버 측 네이티브 도구(예: 웹 검색, 코드 실행, X 검색)를 쓰면, xAI는 최종 응답을 반환하기 전에 자체 루프를 실행해요. 그 도구들을 호출하고 결과를 처리하죠. XaiModelSettings.xai_max_turns로 그 서버 측 루프가 취할 수 있는 턴 수를 제한할 수 있어요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.3',
    model_settings=XaiModelSettings(xai_max_turns=5),
)

xai_max_turns는 xAI의 서버 측 네이티브 도구 루프만 다스려요. 일반 클라이언트 측 도구나 Pydantic AI의 자체 에이전트 루프에는 효과가 없어요. 그것들을 제한하려면 UsageLimits를 쓰세요.

병렬 도구 호출이 켜지면 단일 턴 안에서 여러 도구 호출이 일어날 수 있으므로 xai_max_turns가 이뤄진 총 도구 호출 수와 반드시 같지는 않아요.

멀티 에이전트 모델

xAI의 멀티 에이전트 모델(예: grok-4.20-multi-agent)은 답변 전에 여러 에이전트를 병렬로 사용해 질문을 연구해요. XaiModelSettings.xai_agent_count로 몇 개를 쓸지 고를 수 있는데, 4 또는 16을 받아요.

from pydantic_ai import Agent
from pydantic_ai.models.xai import XaiModelSettings

agent = Agent(
    'xai:grok-4.20-multi-agent',
    model_settings=XaiModelSettings(xai_agent_count=16),
)

에이전트가 많을수록 더 깊은 연구가 가능하지만, 그만큼 토큰과 지연 시간이 더 들어요. 다른 xAI 모델은 이 설정을 무시해요.

스트리밍 취소

cancel()은 다른 작업에서 실행 중인 활성 로컬 스트림 pull을 포함해 안전하게 중단해요. 현재 xai-sdk 릴리스는 그 취소를 사용해 활성 gRPC 읽기를 취소하지만, SDK는 문서화된 스트림별 RPC 핸들을 노출하지 않아요. 그래서 로컬 iterator가 닫힌 뒤 원격 생성이나 청구가 언제 멈추는지는 보장하지 않아요. xai-org/xai-sdk-python#142를 보세요.

더 알아보기 (Learn more)

• xAI X Search 문서 — 검색 옵션·파라미터
• xAI 모델 문서 — 모델 목록·추론 노력
• 멀티 에이전트 모델 — 병렬 연구 에이전트