> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# OpenAI 응답 API

이 OpenAI 호환 Agent 지원 인터페이스를 통해 Mastra Agent를 응답 API로 사용할 수 있습니다. Mastra Agent를 통해 응답을 생성, 검색, 스트리밍 및 삭제하는 방법을 제공합니다.

이 경로는 Mastra Agent, Memory 및 스토리지를 기반으로 하는 Agent 지원 어댑터입니다. 요청을 처리할 Mastra Agent를 선택하려면 `agent_id`를 사용하세요. 단일 요청에 한해 Agent에 구성된 Model을 재정의하려면 `model`을 전달하고, 이미 Agent에 구성된 Model을 사용하려면 생략할 수 있습니다. 저장된 응답은 `conversation_id`도 반환합니다. Mastra에서 이는 원시 Memory `threadId`입니다. 이 API는 현재 실험적입니다.

## 사용예

```typescript
import { MastraClient } from '@mastra/client-js'

const client = new MastraClient({
  baseUrl: 'http://localhost:4111',
})

const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  store: true,
})

console.log(response.output_text)
```

## 행동 양식

### 수명주기

#### `create(params)`

응답을 만듭니다.

```typescript
const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
})
```

**반환:** `stream`이 생략되거나 `false`이면 `Promise<ResponsesResponse>`입니다. `stream: true`이면 `create()`는 SSE 스타일 이벤트 페이로드의 비동기 이터러블을 반환합니다.

```typescript
const stream = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Summarize this ticket',
  stream: true,
})

for await (const event of stream) {
  if (event.type === 'response.output_text.delta') {
    process.stdout.write(event.delta)
  }
}
```

스트리밍 응답에는 Tool 이벤트도 포함될 수 있습니다. Tool 호출 스트림은 `response.output_item.added`, `response.function_call_arguments.delta`, `response.function_call_arguments.done`, `response.output_item.done` 이벤트를 사용합니다. Tool 결과는 `<toolCallId>:output` ID가 있는 `function_call_output` 항목으로 표시됩니다. **보고:** `Promise<ResponsesStream>`.

#### `retrieve(responseId, requestContext?)`

저장된 응답을 검색합니다.

```typescript
const response = await client.responses.retrieve('msg_123')
```

**보고:** `Promise<ResponsesResponse>`.

#### `delete(responseId, requestContext?)`

저장된 응답을 삭제합니다.

```typescript
const deleted = await client.responses.delete('msg_123')
```

**보고:** `Promise<{ id: string; object: "response"; deleted: true }>`

#### `stream(params)`

스트리밍 응답을 생성합니다.

```typescript
const stream = await client.responses.stream({
  agent_id: 'support-agent',
  input: 'Say hello',
})

for await (const event of stream) {
  console.log(event.type)
}
```

**보고:** `Promise<ResponsesStream>`.

## 저장된 응답 및 대화

저장된 응답에는 `response.id`와 `conversation_id`가 모두 포함됩니다.

- `response.id`응답 ID입니다. 저장된 Agent 지원 응답의 경우 이는 지속형 보조자 메시지 ID입니다.
- `conversation_id`원시 Mastra 스레드 ID입니다.

이전에 저장된 응답부터 계속하려면 `previous_response_id`를 사용하세요. 알려진 스레드를 직접 지정하려면 `conversation_id`를 사용하세요.

```typescript
const first = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Start a support thread',
  store: true,
})

const second = await client.responses.create({
  agent_id: 'support-agent',
  conversation_id: first.conversation_id!,
  input: 'Add a follow-up to the same thread',
  store: true,
})
```

기반이 되는 OpenAI Responses API 대화를 직접 생성, 조회, 삭제 또는 검사하려면 [`client.conversations`](https://mastra.zisheng.pro/ko/reference/client-js/conversations)를 사용하세요.

## 함수 호출(Tool)

`response.tools`요청에 사용할 수 있는 구성된 기능 정의가 포함되어 있습니다.

Model이 함수를 호출하면 해당 활동은 최종 어시스턴트 `message`와 함께 `function_call` 및 `function_call_output` 항목으로 `response.output`에 포함됩니다. `stream: true`이면 함수 호출도 Responses 스트림 이벤트로 내보냅니다. 부분 인수 청크는 `response.function_call_arguments.delta` 이벤트에서 읽고, 최종 인수 페이로드와 Tool 이름은 `response.function_call_arguments.done`에서 읽는 것이 좋습니다. 완료된 `function_call` 및 `function_call_output` 항목은 `response.output_item.done` 이벤트에서 읽으세요. Tool 출력 항목은 `<toolCallId>:output` ID를 사용합니다.

## 구조화된 출력

JSON 출력을 원하면 `text.format`을 사용하세요.

- `json_object`JSON 모드를 활성화합니다.
- `json_schema`스키마가 제한된 구조화된 출력을 가능하게 합니다.

두 형식 모두 어시스턴트 메시지 콘텐츠에 JSON을 반환합니다. 엄격한 스키마 적용이 필요하면 `json_schema`를 사용하세요. 유효한 JSON 출력만 필요하면 `json_object`를 사용하세요.

```typescript
const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Return a structured support ticket summary.',
  text: {
    format: {
      type: 'json_schema',
      name: 'ticket_summary',
      schema: {
        type: 'object',
        properties: {
          summary: { type: 'string' },
          priority: { type: 'string' },
        },
        required: ['summary', 'priority'],
        additionalProperties: false,
      },
    },
  },
})
```

## 공급자 지원 요청

Responses 계층에서 Mastra가 정규화하지 않는 Provider별 옵션이 필요하면 `providerOptions`를 사용하세요.

```typescript
const response = await client.responses.create({
  agent_id: 'support-agent',
  input: 'Continue this exchange',
  providerOptions: {
    openai: {
      previousResponseId: 'resp_123',
    },
  },
})
```

## 응답 형태

반환된 응답 객체에는 다음이 포함됩니다.

- `id`: 응답 ID
- `output`: `message`, `function_call`, `function_call_output` 같은 출력 항목
- `output_text`: 어시스턴트 텍스트 출력을 결합하는 편의 getter
- `tools`: 요청에 구성된 Tool 정의
- `conversation_id`: 저장된 응답의 원시 스레드 ID
- `text`: 요청된 텍스트 출력 형식(제공된 경우)

## 매개변수

**agent\_id** (`string`): 최초 요청에 필요합니다. 요청을 실행할 Mastra Agent를 선택합니다. 저장된 후속 turn은 previous\_response\_id로 계속할 때 이를 생략할 수 있습니다.

**model** (`string`): 이 요청에 적용할 선택적 Model 재정의입니다(예: openai/gpt-5). 생략하면 Mastra는 선택한 Agent에 구성된 Model을 사용합니다.

**input** (`string | Array<{ role: 'system' | 'developer' | 'user' | 'assistant'; content: string | Array<{ type: 'input_text' | 'text' | 'output_text'; text: string }> }>`): 필수입니다. 응답에 사용할 입력 텍스트 또는 메시지 배열입니다.

**instructions** (`string`): 이 요청에 적용할 선택적 지침 재정의입니다.

**text** (`{ format: { type: 'json_object' } | { type: 'json_schema'; name: string; schema: Record<string, unknown>; description?: string; strict?: boolean } }`): 선택적 텍스트 출력 형식입니다. JSON 모드에는 json\_object를, 스키마로 제약된 구조화 출력에는 json\_schema를 사용하세요.

**providerOptions** (`Record<string, Record<string, unknown> | undefined>`): 기반 Model 호출에 그대로 전달되는 선택적 Provider별 옵션입니다.

**stream** (`boolean`): true이면 Responses API 이벤트의 비동기 이터러블을 반환합니다.

**store** (`boolean`): true이면 선택한 Agent의 Memory를 통해 응답을 유지합니다.

**conversation\_id** (`string`): 선택적 대화 식별자입니다. Mastra에서 이는 원시 Memory 스레드 ID입니다.

**previous\_response\_id** (`string`): 이전에 저장된 응답부터 저장된 응답 체인을 계속합니다.

**requestContext** (`RequestContext | Record<string, any>`): Mastra 서버로 전달되는 선택적 요청 컨텍스트입니다.