X 검색
X 검색 (X Search)
XSearch 캐퍼빌리티는 에이전트에 X(트위터) 게시물 검색 기능을 더해 줘요. 네이티브 측이 XSearchTool로 뒷받침되는 provider-adaptive tool입니다 — 설정 옵션은 X Search Tool을 참고하세요.
출처: 문서
본문
Web Search나 Web Fetch와 달리 기본 비-xAI 폴백이 없어요. X 검색은 xAI 모델에서만 네이티브로 제공됩니다. 에이전트가 xAI 모델에서 실행되지 않는다면 fallback_subagent_model을 XSearchTool을 지원하는 xAI 모델로 명시적으로 설정하면, 검색 요청이 그 모델에 서브에이전트 도구로 위임됩니다:
from pydantic_ai import Agent
from pydantic_ai.capabilities import XSearch
agent = Agent(
'anthropic:claude-sonnet-4-6',
capabilities=[XSearch(fallback_subagent_model='xai:grok-4.3')],
)
fallback_model은 더 이상 사용되지 않아요.
fallback_model은fallback_subagent_model의 이전 이름입니다. 파이썬과 에이전트 스펙 모두에서 계속 동작하며 경고를 냅니다. 두 이름을 함께 전달하면 거부됩니다: 캐퍼빌리티를 만들 때는UserError, 스펙을 로드할 때는 스펙 로더가 그것을 감싼ValueError가 발생해요.
native=는 팩토리일 수 있습니다. RunContext를 받아 XSearchTool 또는 None을 반환하는 callable이요 — XSearchNativeTool은 fallback_subagent_model 서브에이전트가 받아들이는 타입입니다. 이것은 매 모델 요청마다, 그리고 서브에이전트가 실행될 때 다시 해석되므로 일회성 사이드 이펙트가 없게 해야 해요. 두 해석 모두 같은 런에 속하며 같은 deps를 지니지만, RunContext는 공유하지 않습니다. 서브에이전트는 자신의 도구 호출에서 해석하므로 tool_call_id와 tool_name이 None 대신 그 호출을 가리키고, messages는 지금까지의 런을 담아요. 양쪽에서 일치해야 하는 설정은 ctx.deps에서 읽으세요. 서브에이전트에서는 include_output 같은 캐퍼빌리티 수준 필드가 팩토리 결과를 덮어씁니다. Dynamic Configuration을 참고하세요.
None을 반환하는 팩토리
None은fallback_subagent_model이 설정되지 않았을 때만 그 요청에 대해 도구를 생략합니다.fallback_subagent_model이 있으면, 팩토리가None을 반환할 때 — 심지어XSearchTool을 네이티브로 지원하는 모델에서도 — 서브에이전트 도구가 모델에 제공되고, 그것을 호출하면 기본 설정으로 X를 검색하는 대신UserError가 발생합니다.
Temporal과의 지속 실행
fallback_subagent_model 서브에이전트의 도구 호출은 Temporal activity 안에서 실행되므로, 거기서 해석되는 native= 팩토리는 제한된 TemporalRunContext를 받아요. ctx.messages를 읽거나 Temporal이 전달하지 않는 다른 어떤 필드를 읽으면 UserError가 발생합니다. ctx.deps는 경계를 넘어가므로 팩토리는 deps만 읽게 하세요. 사용 가능한 필드는 Agent Run Context and Dependencies를 참고하세요. DBOS와 Prefect는 실시간 RunContext를 전달하므로 영향을 받지 않아요.