서버 도구

서버 도구는 Synthorai가 단일 요청 안에서 대신 실행하는 기능입니다: 모델이 요청하면 저희가 작업을 수행하고 결과는 같은 응답으로 돌아옵니다. tools에 항목 하나만 추가하면 됩니다 — 두 번째 엔드포인트도, 구현할 콜백도 없습니다.

사용 가능한 도구

모든 서버 도구는 synthorai: 접두사로 식별되므로 사용자의 도구 이름과 충돌하지 않습니다:

공통 계약

모든 서버 도구는 같은 방식으로 동작하므로 하나에서 배운 것이 다음에도 적용됩니다:

• 옵트인 전용. 도구를 tools에 넣지 않으면 아무것도 실행되지 않습니다. 도구가 없는 요청은 평범한 요청입니다.
• 한 번의 왕복. 도구 루프는 저희가 대신 수행하며, 도구 활동과 답변이 이미 포함된 단일 응답을 받습니다.
• 사용자의 도구도 그대로 동작. 서버 도구와 function 도구를 함께 선언할 수 있습니다 — 모델이 사용자의 도구를 호출하면 정직한 stop_reason: tool_use와 함께 제어를 돌려드립니다. (한 가지 예외: 저희가 주입하는 도구 이름은 예약되어 있습니다 — 아래 참조.)
• 호출당 과금, usage에 표시. 횟수는 usage.server_tool_use에, 요금은 usage.cost에 기록되어 모든 요청을 청구서와 대조할 수 있습니다.
• max_uses는 실질적 상한. 단일 요청이 지출할 수 있는 양을 제한하며 내부 재시도에도 유지됩니다.

토큰이 비용의 나머지 절반

대화 이어가기

받은 그대로의 assistant 메시지를 도구 블록을 포함해 messages에 다시 추가하세요. 후속 요청에서도 같은 서버 도구를 계속 선언하면 히스토리가 가장 풍부한 형태로 유지됩니다. 도구를 빼면 이전 도구 결과는 일반 텍스트로 평탄화되지만 모델은 여전히 내용을 볼 수 있습니다.

예약된 도구 이름

synthorai: 파라미터를 사용하는 동안 대응하는 순수 이름은 예약됩니다: synthorai:web_search와 나란히 web_search라는 자체 도구를 선언하면(또는 synthorai:web_fetch와 나란히 web_fetch를 선언하면) 도구 이름을 명시한 400이 반환됩니다. 이름을 바꾸거나 synthorai: 파라미터를 제거하세요.

이유는 저희가 서버 도구를 바로 그 이름으로 주입하기 때문입니다. 두 도구가 같은 이름으로 모델에 도달하면 어느 쪽 호출이 돌아온 것인지 아무도 구분할 수 없습니다 — 사용자 도구의 인자가 저희 검색 공급자에게 전송되거나 사용자의 호출이 유실될 수 있습니다. 요청을 거부하는 것이 유일하게 정직한 답입니다. 대응하는 synthorai: 파라미터 없이 어느 이름으로든 자체 도구를 선언하는 것은 영향받지 않습니다: 저희가 아무것도 주입하지 않으므로 아무것도 충돌하지 않습니다.

실패에는 과금되지 않습니다

호출당 요금은 결과를 낸 호출에 부과됩니다. 저희 네트워크를 떠나기 전에 거부된 호출 — 거부된 URL, 차단된 도메인, 미구성 백엔드 — 은 무료입니다. 공급자에 도달해 거기서 실패한 호출은 공급자가 저희에게 청구하므로 과금됩니다. 어느 쪽이든 해당 라운드는 max_uses 예산에 계산되므로, 깨진 URL을 재시도하는 모델이 무료로 반복할 수는 없습니다.

지원 엔드포인트

서버 도구는 /v1/messages, /v1/chat/completions, /v1/responses에서 동작합니다. 지원하지 않는 엔드포인트(Gemini 엔드포인트)로 synthorai: 파라미터를 보내면 그 사실을 알리는 400이 반환됩니다. 알 수 없는 도구를 업스트림에 넘기느니 거부하는 쪽을 택합니다. 넘길 경우 최선은 혼란스러운 서드파티 오류이고, 최악은 조용히 무시되어 검색은 일어나지 않은 채 요청한 것보다 조용히 덜 수행한 일반 요청으로 과금되는 것입니다.

사용 가능 여부

서버 도구는 API 키 단위로 활성화됩니다. 키에 활성화되지 않은 도구를 지정하면 조용히 무시되는 대신 도구 이름을 명시한 400이 반환됩니다. 활성화는 문의해 주세요.