Amazon Bedrock

Bedrock 어댑터는 세 가지 API 경로를 통해 TanStack AI를 Amazon Bedrock에 연결합니다.

Converse (기본값) — @aws-sdk/client-bedrock-runtime을 기반으로 하는 Bedrock의 모델 비종속 API입니다. Anthropic Claude, Amazon Nova, Meta Llama, Mistral, DeepSeek, Cohere, AI21, OpenAI gpt-oss 모델을 포함한 폭넓은 채팅 카탈로그에 연결합니다.
Chat Completions (api: 'chat') — Bedrock의 OpenAI 호환 Chat Completions 엔드포인트입니다. 오픈 웨이트 모델(gpt-oss, DeepSeek V3.x, Gemma, Qwen, Mistral 오픈 모델, GLM 등)만 사용할 수 있습니다. Claude, Nova 또는 Llama에는 연결하지 않습니다.
Responses (api: 'responses') — Bedrock의 OpenAI 호환 Responses API이며 mantle만 지원합니다. 현재는 OpenAI gpt-oss 제품군을 지원합니다.

모든 경로는 스트리밍과 클라이언트 측 도구 호출을 지원합니다. 모델이 추론 출력을 생성하면(예: DeepSeek R1, gpt-oss) 해당 출력이 표시됩니다. Converse 경로에서는 요청 측 extended thinking 활성화(예: Claude thinking budget)가 아직 연결되지 않았으므로, 기본적으로 추론하는 모델의 출력만 표시됩니다.

설치

pnpm add @tanstack/ai-bedrock

추가 패키지는 필요하지 않습니다. SigV4 인증은 직접 의존성인 @aws-sdk/client-bedrock-runtime에서 처리합니다.

빠른 시작 (Converse — 기본값)

기본 bedrockText 호출은 Converse API를 사용하며 폭넓은 모델 카탈로그에 연결합니다.

// ignore: iterating a chat() stream and reading chunk.type/chunk.delta needs the
// AG-UI base event fields, which come from @ag-ui/core. It's a transitive dep of
// @tanstack/ai, so kiira (resolving @tanstack/ai from source under the dist->src
// heuristic) can't follow it and those base fields drop off StreamChunk. The code
// is correct (the same pattern is used throughout ai-client); see
// getting-started/quick-start-server for the type-checked consumption shape.
import { bedrockText } from '@tanstack/ai-bedrock'
import { chat } from '@tanstack/ai'

const adapter = bedrockText('us.anthropic.claude-haiku-4-5-20251001-v1:0', {
  region: 'us-east-1',
})

for await (const chunk of chat({
  adapter,
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
})) {
  if (chunk.type === 'TEXT_MESSAGE_CONTENT') process.stdout.write(chunk.delta ?? '')
}

명시적으로 { api: 'converse' }를 전달하는 것과 같습니다. bedrock-converse 어댑터를 반환합니다.

인증

Bedrock은 두 가지 인증 모드를 지원합니다.

API 키

Bedrock은 AWS Console에서 API 키를 발급합니다. 자세한 지침은 Bedrock API 키 가이드를 참조합니다.

다음 환경 변수 중 하나를 설정하면 어댑터가 자동으로 사용합니다.

BEDROCK_API_KEY=your-bedrock-api-key
# or the legacy name:
AWS_BEARER_TOKEN_BEDROCK=your-bedrock-api-key

SigV4 (AWS 자격 증명 체인)

IAM 역할, 인스턴스 프로필 또는 ~/.aws/credentials를 사용하는 워크로드에서는 auth: 'sigv4'를 설정합니다(또는 환경에 API 키가 없을 때 'auto'로 둡니다). SigV4는 @aws-sdk/client-bedrock-runtime을 통해 별도 설정 없이 작동하며 추가 패키지가 필요하지 않습니다.

AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
AWS_SESSION_TOKEN=...   # optional, for temporary credentials

인증 확인 순서 (`auth: 'auto'`, 기본값)

팩토리에 명시적으로 전달된 apiKey
BEDROCK_API_KEY 환경 변수
AWS_BEARER_TOKEN_BEDROCK 환경 변수
표준 AWS 인증 체인을 통한 SigV4

구성

BedrockClientConfig는 다음 옵션을 허용합니다.

옵션	유형	기본값	설명
`api`	`'converse' \| 'chat' \| 'responses'`	`'converse'`	사용할 베드록 API
`region`	`string`	`'us-east-1'`	AWS 리전 문자열 (예: `'us-west-2'`)
`auth`	`'apikey' \| 'sigv4' \| 'auto'`	`'auto'`	인증 모드
`apiKey`	`string`	—	명시적 API 키 (환경 변수를 덮어씁니다)
`baseURL`	`string`	—	계산된 기본 URL 을 완전히 덮어씁니다
`endpoint`	`'runtime' \| 'mantle'`	`'runtime'`	타겟할 Bedrock 엔드포인트 (Chat Completions 경로만)

endpoint 옵션은 api: 'chat'일 때만 적용됩니다. runtime 엔드포인트(bedrock-runtime)는 폭넓은 오픈 웨이트 카탈로그를 제공하며, mantle은 대안입니다. Responses API는 항상 mantle을 대상으로 합니다.

Converse API (기본값)

bedrockText(model) 또는 bedrockText(model, { api: 'converse' })는 @aws-sdk/client-bedrock-runtime을 기반으로 하는 bedrock-converse 어댑터를 반환합니다. Bedrock의 모델 비종속 대화형 API이며 대부분의 사용 사례에 권장되는 경로입니다.

모델 범위: Anthropic Claude, Amazon Nova, Meta Llama, Mistral, DeepSeek, Cohere, AI21, OpenAI gpt-oss 및 계정에서 액세스할 수 있는 기타 모델입니다. 아래의 모델 사용 가능 여부를 참조합니다.

import { bedrockText } from '@tanstack/ai-bedrock'
import { chat } from '@tanstack/ai'

// Claude via Converse
const claudeAdapter = bedrockText('us.anthropic.claude-haiku-4-5-20251001-v1:0', {
  region: 'us-east-1',
})

// Amazon Nova via Converse
const novaAdapter = bedrockText('us.amazon.nova-pro-v1:0', {
  region: 'us-east-1',
})

// Meta Llama via Converse
const llamaAdapter = bedrockText('us.meta.llama4-maverick-17b-instruct-v1:0', {
  region: 'us-east-1',
})

명시적 API 키 (Converse)

import { createBedrockText } from '@tanstack/ai-bedrock'

const adapter = createBedrockText(
  'us.anthropic.claude-haiku-4-5-20251001-v1:0',
  'your-bedrock-api-key',
  { region: 'us-west-2' },
)

채팅 완성 API (`api: 'chat'`)

Bedrock의 OpenAI 호환 Chat Completions 엔드포인트를 사용하려면 api: 'chat'을 설정합니다. bedrock 어댑터를 반환합니다.

모델 범위: 오픈 웨이트 모델만 해당합니다 — gpt-oss, DeepSeek V3.x, Gemma, Qwen, Mistral 오픈 모델, GLM 등입니다. 이 엔드포인트에서는 Claude, Nova 및 Llama를 사용할 수 없습니다. 현재 목록은 AWS API 호환성 매트릭스를 참조합니다.

// ignore: see the Converse quick-start above — iterating a chat() stream and
// reading chunk.type/chunk.delta needs @ag-ui/core base fields kiira can't
// resolve transitively through @tanstack/ai source.
import { bedrockText } from '@tanstack/ai-bedrock'
import { chat } from '@tanstack/ai'

const adapter = bedrockText('openai.gpt-oss-20b-1:0', {
  region: 'us-east-1',
  api: 'chat',
})

for await (const chunk of chat({
  adapter,
  messages: [{ role: 'user', content: 'What is the capital of France?' }],
})) {
  if (chunk.type === 'TEXT_MESSAGE_CONTENT') process.stdout.write(chunk.delta ?? '')
}

응답 API (`api: 'responses'`)

Bedrock의 OpenAI 호환 Responses API를 사용하려면 api: 'responses'를 설정합니다. bedrock-responses 어댑터를 반환합니다. 이 API는 mantle만 지원합니다.

모델 범위: 현재는 OpenAI gpt-oss 제품군입니다. Responses API는 상태를 유지하므로 서버 측에서 대화를 계속하려면 modelOptions를 통해 previous_response_id와 store를 전달합니다.

추론: 추론 델타는 thinking 콘텐츠로 스트리밍됩니다. Mantle에서 제공하는 모델은 2025년 7월 이전 이벤트 이름인 response.reasoning.delta를 여전히 생성할 수 있습니다(OpenAI 사양에서는 response.reasoning_text.delta를 사용하도록 제거됨). 어댑터는 두 이름을 모두 인식하고 동일하게 매핑합니다.

// ignore: see the Converse quick-start above — iterating a chat() stream and
// reading chunk.type/chunk.delta needs @ag-ui/core base fields kiira can't
// resolve transitively through @tanstack/ai source.
import { bedrockText } from '@tanstack/ai-bedrock'
import { chat } from '@tanstack/ai'

const adapter = bedrockText('openai.gpt-oss-120b-1:0', {
  region: 'us-east-1',
  api: 'responses',
})

for await (const chunk of chat({
  adapter,
  messages: [{ role: 'user', content: 'Summarize the Bedrock pricing page.' }],
})) {
  if (chunk.type === 'TEXT_MESSAGE_CONTENT') process.stdout.write(chunk.delta ?? '')
}

임베딩

InvokeModel을 통해 Titan 또는 Cohere 임베딩 모델로 임베딩 벡터를 생성합니다.

import { embed } from "@tanstack/ai";
import { bedrockEmbedding } from "@tanstack/ai-bedrock";

const result = await embed({
  adapter: bedrockEmbedding("amazon.titan-embed-text-v2:0"),
  input: ["a red guitar", "a blue drum kit"],
  dimensions: 512, // 256 | 512 | 1024
});

console.log(result.embeddings[0]?.vector);

Titan Multimodal은 텍스트와 이미지를 각각 또는 하나의 벡터로 결합하여 임베딩합니다. 파트를 배열 안에 중첩하여 결합합니다(채팅 메시지의 content가 사용하는 것과 동일한 Array<ContentPart> 형태). 바깥 배열은 항목 목록이므로 다음 코드는 하나의 결합된 항목을 임베딩합니다.

import { embed } from "@tanstack/ai";
import { bedrockEmbedding } from "@tanstack/ai-bedrock";

const productPhoto = "iVBORw0KGgo..."; // base64 image data

const result = await embed({
  adapter: bedrockEmbedding("amazon.titan-embed-image-v1"),
  input: [
    [
      { type: "text", content: "a red guitar" },
      {
        type: "image",
        source: {
          type: "data",
          value: productPhoto,
          mimeType: "image/png",
        },
      },
    ],
  ],
  dimensions: 1024, // 256 | 384 | 1024
});

Bedrock의 Cohere Embed v3도 지원합니다(텍스트 전용, 배치 처리, inputType 필요):

import { embed } from "@tanstack/ai";
import { bedrockEmbedding } from "@tanstack/ai-bedrock";

const result = await embed({
  adapter: bedrockEmbedding("cohere.embed-english-v3"),
  input: ["a red guitar", "a blue drum kit"],
  modelOptions: { inputType: "search_document" },
});

Titan 모델에는 일괄 처리 API가 없습니다. N개 항목의 배치는 낮은 동시성 제한 아래 N회의 InvokeModel 호출로 실행됩니다. Titan Multimodal은 원격 이미지 URL을 가져오지 않으므로 base64 데이터(또는 data: URI)를 전달합니다.

전체 API는 임베딩 가이드를 참조합니다.

모델 사용 가능 여부

어댑터에는 확인된 모델 ID를 수동으로 초기화한 스냅샷 카탈로그(src/model-catalog.generated.ts)가 포함됩니다. AWS 자격 증명으로 ListFoundationModels를 호출하는 유지 관리 스크립트 scripts/fetch-bedrock-models.ts를 사용하여 이 카탈로그를 새로 고칠 수 있습니다.

실제 모델 사용 가능 여부는 AWS 계정의 모델 액세스 구성과 대상 리전에 따라 달라집니다. 사용하기 전에 Amazon Bedrock 콘솔에서 모델 액세스를 활성화합니다.

전체 모델 목록과 각 모델이 지원하는 API 엔드포인트는 AWS API 호환성 매트릭스를 참조합니다.

지원 기능

스트리밍 채팅 완성
클라이언트 측 도구 호출
추론 출력(모델이 생성하면 extended thinking이 표시되며, Converse의 요청 측 활성화는 아직 연결되지 않음)
멀티모달 입력(텍스트, 이미지, 문서 — 모델에 따라 다름)
JSON schema / 구조화된 출력

API 참조

`bedrockText(model, config?)`

환경 변수 인증을 사용하는 Bedrock 어댑터를 생성합니다.

model — 모델 ID(예: 'us.anthropic.claude-haiku-4-5-20251001-v1:0')
config.api — 'converse' (기본값), 'chat' 또는 'responses'
config.region — AWS 리전 문자열(기본값 'us-east-1')
config.auth — 'auto' (기본값), 'apikey' 또는 'sigv4'
config.apiKey — 명시적 API 키(환경 변수보다 우선)
config.baseURL — 기본 URL 재정의
config.endpoint — 'runtime' (기본값) 또는 'mantle'(Chat Completions 경로만 해당)

chat() 또는 generate()와 함께 사용할 채팅 어댑터를 반환합니다.

`api` 값	어댑터 이름	기반 SDK
`'converse'` (default)	`bedrock-converse`	`@aws-sdk/client-bedrock-runtime`
`'chat'`	`bedrock`	`openai` (OpenAI-compatible)
`'responses'`	`bedrock-responses`	`openai` (OpenAI-compatible)

`createBedrockText(model, apiKey, config?)`

환경 변수 조회를 건너뛰고 명시적 API 키로 Bedrock 어댑터를 생성합니다.

다음 단계

Amazon Bedrock API 키 — API 키 생성 및 관리
Amazon Bedrock 모델 액세스 — 계정에서 모델 활성화
AWS API 호환성 매트릭스 — API별 사용 가능 모델
Converse API 참조 — 기본 Converse API 문서
스트리밍 가이드 — 스트리밍 응답 알아보기
도구 가이드 — 도구 호출 알아보기

설치​

빠른 시작 (Converse — 기본값)​

인증​

API 키​

SigV4 (AWS 자격 증명 체인)​

인증 확인 순서 (auth: 'auto', 기본값)​

구성​

Converse API (기본값)​

명시적 API 키 (Converse)​

채팅 완성 API (api: 'chat')​

응답 API (api: 'responses')​

임베딩​

모델 사용 가능 여부​

지원 기능​

API 참조​

bedrockText(model, config?)​

createBedrockText(model, apiKey, config?)​

다음 단계​

설치