Skip to content

Commit 9910e10

Browse files
tylerryu-oaitylerryu-oai
committed
added korean translation
1 parent 8cf5356 commit 9910e10

27 files changed

+2384
-14
lines changed

‎docs/src/content/docs/ko/extensions/ai-sdk.mdx‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
---
2+
title: Vercel의 AI SDK로 모든 모델 사용하기
3+
description: Connect your Agents SDK agents to any model through the Vercel's AI SDK
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import aiSdkSetupExample from '../../../../../../examples/docs/extensions/ai-sdk-setup.ts?raw';
8+
9+
<Aside type="caution">
10+
이 어댑터는 아직 베타 단계입니다. 특히 규모가 작은 모델 제공자의 경우 문제를
11+
겪을 수 있습니다. 문제가 있으면 [GitHub
12+
이슈](https://github.com/openai/openai-agents-js/issues)로 보고해 주세요.
13+
신속히 수정하겠습니다.
14+
</Aside>
15+
16+
기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려면, [Vercel의 AI SDK](https://sdk.vercel.ai/)에서 지원하는 다양한 모델을 이 어댑터를 통해 Agents SDK에 연결할 수 있습니다.
17+
18+
## 설정
19+
20+
<Steps>
21+
22+
1. extensions 패키지를 설치하여 AI SDK 어댑터를 설치합니다:
23+
24+
```bash
25+
npm install @openai/agents-extensions
26+
```
27+
28+
2. [Vercel의 AI SDK](https://sdk.vercel.ai/docs/models/overview)에서 원하는 모델 패키지를 선택해 설치합니다:
29+
30+
```bash
31+
npm install @ai-sdk/openai@"^1.0.0"
32+
```
33+
34+
3. 에이전트에 연결하기 위해 어댑터와 모델을 가져옵니다:
35+
36+
```typescript
37+
import { openai } from '@ai-sdk/openai';
38+
import { aisdk } from '@openai/agents-extensions';
39+
```
40+
41+
4. 에이전트가 사용할 모델 인스턴스를 초기화합니다:
42+
43+
```typescript
44+
const model = aisdk(openai('o4-mini'));
45+
```
46+
47+
</Steps>
48+
49+
<Aside type="caution">
50+
Vercel의 AI SDK는 최근 v2로 마이그레이션했지만, openai agent extensions 는
51+
아직 v2와 호환되지 않습니다. 따라서 Vercel의 AI SDK v1 버전을 설치해야 합니다.
52+
</Aside>
53+
54+
## 예제
55+
56+
<Code lang="typescript" code={aiSdkSetupExample} title="AI SDK 설정" />
57+
58+
## 제공자 메타데이터 전달
59+
60+
메시지와 함께 제공자별 옵션을 보내야 한다면, `providerMetadata`를 통해 전달하세요. 이 값들은 기반이 되는 AI SDK 모델로 직접 전달됩니다. 예를 들어, Agents SDK에서 다음과 같은 `providerData`는
61+
62+
```ts
63+
providerData: {
64+
anthropic: {
65+
cacheControl: {
66+
type: 'ephemeral';
67+
}
68+
}
69+
}
70+
```
71+
72+
다음과 같이 변환됩니다
73+
74+
```ts
75+
providerMetadata: {
76+
anthropic: {
77+
cacheControl: {
78+
type: 'ephemeral';
79+
}
80+
}
81+
}
82+
```
83+
84+
AI SDK 통합을 사용할 때.

‎docs/src/content/docs/ko/extensions/twilio.mdx‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
---
2+
title: Twilio와 실시간 에이전트 사용
3+
description: Connect your Agents SDK agents to Twilio to use voice agents
4+
---
5+
6+
import { Aside, Steps, Code } from '@astrojs/starlight/components';
7+
import twilioBasicExample from '../../../../../../examples/docs/extensions/twilio-basic.ts?raw';
8+
import twilioServerExample from '../../../../../../examples/realtime-twilio/index.ts?raw';
9+
10+
Twilio는 전화 통화의 원문 오디오를 WebSocket 서버로 전송하는 [Media Streams API](https://www.twilio.com/docs/voice/media-streams)를 제공합니다. 이 설정은 여러분의 [Overview](/openai-agents-js/ko/guides/voice-agents)를 Twilio에 연결하는 데 사용할 수 있습니다. Twilio에서 오는 이벤트를 Realtime Session에 연결하기 위해 기본 Realtime Session 트랜스포트를 `websocket` 모드로 사용할 수 있습니다. 그러나, 전화 통화는 웹 기반 대화보다 자연스럽게 지연이 더 크므로, 올바른 오디오 포맷을 설정하고 자체 인터럽션(중단 처리) 타이밍을 조정해야 합니다.
11+
12+
설정 경험을 개선하기 위해, 인터럽션(중단 처리)과 오디오 포워딩을 포함해 Twilio와의 연결을 대신 처리하는 전용 전송 계층을 만들었습니다.
13+
14+
<Aside type="caution">
15+
이 어댑터는 아직 베타 단계입니다. 드문 엣지 케이스나 버그를 겪을 수 있습니다.
16+
문제를 발견하시면 [GitHub
17+
issues](https://github.com/openai/openai-agents-js/issues)를 통해 보고해
18+
주세요. 빠르게 수정하겠습니다.
19+
</Aside>
20+
21+
## 설정
22+
23+
<Steps>
24+
25+
1. **Twilio 계정과 Twilio 전화번호가 있는지 확인하세요.**
26+
27+
2. **Twilio에서 오는 이벤트를 받을 수 있는 WebSocket 서버를 설정하세요.**
28+
29+
로컬에서 개발 중이라면, 이는 여러분이 다음과 같은 로컬 터널을 구성해야 함을 의미합니다. 이는 여러분이 다음과 같은 로컬 터널을 구성해야 함을 의미합니다: [`ngrok`](https://ngrok.io/) 또는
30+
[Cloudflare Tunnel](https://developers.cloudflare.com/pages/how-to/preview-with-cloudflare-tunnel/)
31+
을 사용해 로컬 서버에 Twilio가 접근할 수 있도록 해야 합니다. `TwilioRealtimeTransportLayer`를
32+
사용해 Twilio에 연결할 수 있습니다.
33+
34+
3. **extensions 패키지를 설치하여 Twilio 어댑터를 설치하세요:**
35+
36+
```bash
37+
npm install @openai/agents-extensions
38+
```
39+
40+
4. **`RealtimeSession`에 연결하기 위해 어댑터와 모델을 임포트하세요:**
41+
42+
<Code
43+
lang="typescript"
44+
code={twilioBasicExample.replace(
45+
/\n\s+\/\/ @ts-expect-error - this is not defined/g,
46+
'',
47+
)}
48+
/>
49+
50+
5. **`RealtimeSession`을 Twilio에 연결하세요:**
51+
52+
```typescript
53+
session.connect({ apiKey: 'your-openai-api-key' });
54+
```
55+
56+
</Steps>
57+
58+
`RealtimeSession`에서 기대되는 모든 이벤트와 동작(도구 호출, 가드레일 등)이 그대로 작동합니다. `RealtimeSession`을 음성 에이전트와 함께 사용하는 방법에 대한 자세한 내용은 [Overview](/openai-agents-js/ko/guides/voice-agents)를 참고하세요.
59+
60+
## 팁과 고려사항
61+
62+
1. **속도가 핵심입니다.**
63+
64+
Twilio에서 필요한 모든 이벤트와 오디오를 받으려면, WebSocket 연결에 대한 참조를 얻는 즉시
65+
`TwilioRealtimeTransportLayer` 인스턴스를 생성하고 바로 이어서 `session.connect()`를 호출하세요.
66+
67+
2. **Twilio 원문 이벤트에 접근하세요.**
68+
69+
Twilio가 전송하는 원문 이벤트에 접근하려면, `RealtimeSession` 인스턴스에서 `transport_event`
70+
이벤트를 구독하면 됩니다. Twilio에서 오는 모든 이벤트는 타입이 `twilio_message`이며,
71+
원문 이벤트 데이터가 담긴 `message` 프로퍼티를 포함합니다.
72+
73+
3. **디버그 로그를 확인하세요.**
74+
75+
문제 상황에서 더 많은 정보가 필요할 때가 있습니다. `DEBUG=openai-agents*` 환경 변수를 사용하면
76+
Agents SDK의 모든 디버그 로그가 출력됩니다. 또는 `DEBUG=openai-agents:extensions:twilio*`를
77+
사용해 Twilio 어댑터에 대한 디버그 로그만 활성화할 수 있습니다.
78+
79+
## 전체 예제 서버
80+
81+
아래는 Twilio로부터 요청을 수신하고 이를 `RealtimeSession`으로 전달하는, 엔드투엔드 WebSocket 서버의 예제입니다.
82+
83+
<Code
84+
lang="typescript"
85+
code={twilioServerExample}
86+
title="Example server using Fastify"
87+
/>

‎docs/src/content/docs/ko/guides/agents.mdx‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
title: 에이전트
3+
description: Learn more about how to define agents in the OpenAI Agents SDK for JavaScript / TypeScript
4+
---
5+
6+
import { Code } from '@astrojs/starlight/components';
7+
import simpleAgent from '../../../../../../examples/docs/agents/simpleAgent.ts?raw';
8+
import agentWithTools from '../../../../../../examples/docs/agents/agentWithTools.ts?raw';
9+
import agentWithContext from '../../../../../../examples/docs/agents/agentWithContext.ts?raw';
10+
import agentWithAodOutputType from '../../../../../../examples/docs/agents/agentWithAodOutputType.ts?raw';
11+
import agentWithHandoffs from '../../../../../../examples/docs/agents/agentWithHandoffs.ts?raw';
12+
import agentWithDynamicInstructions from '../../../../../../examples/docs/agents/agentWithDynamicInstructions.ts?raw';
13+
import agentWithLifecycleHooks from '../../../../../../examples/docs/agents/agentWithLifecycleHooks.ts?raw';
14+
import agentCloning from '../../../../../../examples/docs/agents/agentCloning.ts?raw';
15+
import agentForcingToolUse from '../../../../../../examples/docs/agents/agentForcingToolUse.ts?raw';
16+
17+
에이전트는 OpenAI Agents SDK의 기본 구성 요소입니다. **에이전트**는 다음으로 구성된 대규모 언어 모델(LLM)입니다:
18+
19+
- **Instructions** – 모델에게 _자신이 누구인지_ 와 _어떻게 응답해야 하는지_ 알려주는 시스템 프롬프트
20+
- **Model** – 호출할 OpenAI 모델과 선택적 모델 튜닝 매개변수
21+
- **Tools** – 작업을 수행하기 위해 LLM이 호출할 수 있는 함수 또는 API 목록
22+
23+
<Code lang="typescript" code={simpleAgent} title="기본 에이전트 정의" />
24+
25+
이 페이지의 나머지 부분에서는 모든 에이전트 기능을 자세히 설명합니다.
26+
27+
---
28+
29+
## 기본 구성
30+
31+
`Agent` 생성자는 단일 구성 객체를 받습니다. 가장 자주 사용하는 속성은 다음과 같습니다.
32+
33+
| 속성 | 필수 | 설명 |
34+
| --------------- | ------ | -------------------------------------------------------------------------------------------------- |
35+
| `name` | 예 | 짧고 사람이 읽을 수 있는 식별자 |
36+
| `instructions` | 예 | 시스템 프롬프트(문자열 **또는** 함수 – [Dynamic instructions](#dynamic-instructions) 참조) |
37+
| `model` | 아니오 | 모델 이름 **또는** 사용자 정의 [`Model`](/openai-agents-js/openai/agents/interfaces/model/) 구현 |
38+
| `modelSettings` | 아니오 | 튜닝 매개변수(temperature, top_p, 등) |
39+
| `tools` | 아니오 | 모델이 호출할 수 있는 [`Tool`](/openai-agents-js/openai/agents/type-aliases/tool/) 인스턴스의 배열 |
40+
41+
<Code lang="typescript" code={agentWithTools} title="도구가 있는 에이전트" />
42+
43+
---
44+
45+
## 컨텍스트
46+
47+
에이전트는 **컨텍스트 타입에 대해 제네릭**입니다 – 즉, `Agent<TContext, TOutput>`. _컨텍스트_ 는 여러분이 생성해 `Runner.run()`에 전달하는 의존성 주입 객체입니다. 이는 모든 도구, 가드레일, 핸드오프 등으로 전달되며 상태를 저장하거나 공유 서비스(데이터베이스 연결, 사용자 메타데이터, 기능 플래그 등)를 제공하는 데 유용합니다.
48+
49+
<Code
50+
lang="typescript"
51+
code={agentWithContext}
52+
title="컨텍스트가 있는 에이전트"
53+
/>
54+
55+
---
56+
57+
## 출력 타입
58+
59+
기본적으로 에이전트는 **일반 텍스트**(`string`)를 반환합니다. 모델이 구조화된 객체를 반환하도록 하려면 `outputType` 속성을 지정하면 됩니다. SDK는 다음을 허용합니다:
60+
61+
1. [Zod](https://github.com/colinhacks/zod) 스키마(`z.object({...})`)
62+
2. JSON‑schema와 호환되는 임의의 객체
63+
64+
<Code
65+
lang="typescript"
66+
code={agentWithAodOutputType}
67+
title="Zod를 사용한 구조화된 출력"
68+
/>
69+
70+
`outputType`이 제공되면 SDK는 일반 텍스트 대신 자동으로
71+
[structured outputs](https://platform.openai.com/docs/guides/structured-outputs)를 사용합니다.
72+
73+
---
74+
75+
## 핸드오프
76+
77+
에이전트는 `handoffs` 속성을 통해 다른 에이전트에 **위임**할 수 있습니다. 일반적인 패턴은 대화를 보다 전문화된 하위 에이전트로 라우팅하는 _분류 에이전트(트리아지 에이전트)_ 를 사용하는 것입니다.
78+
79+
<Code
80+
lang="typescript"
81+
code={agentWithHandoffs}
82+
title="핸드오프가 있는 에이전트"
83+
/>
84+
85+
이 패턴에 대한 자세한 내용은 [Handoffs](/openai-agents-js/ko/guides/handoffs)에서 확인할 수 있습니다.
86+
87+
---
88+
89+
## 동적 instructions
90+
91+
`instructions`는 문자열 대신 **함수**가 될 수 있습니다. 이 함수는 현재 `RunContext`와 에이전트 인스턴스를 받아 문자열 _또는_ `Promise<string>`을 반환할 수 있습니다.
92+
93+
<Code
94+
lang="typescript"
95+
code={agentWithDynamicInstructions}
96+
title="동적 instructions가 있는 에이전트"
97+
/>
98+
99+
동기 및 `async` 함수 모두 지원됩니다.
100+
101+
---
102+
103+
## 수명 주기 후크
104+
105+
고급 사용 사례의 경우 이벤트를 리스닝하여 에이전트 수명 주기를 관찰할 수 있습니다
106+
107+
<Code
108+
lang="typescript"
109+
code={agentWithLifecycleHooks}
110+
title="수명 주기 후크가 있는 에이전트"
111+
/>
112+
113+
---
114+
115+
## 가드레일
116+
117+
가드레일을 사용하면 사용자 입력과 에이전트 출력을 검증하거나 변환할 수 있습니다. 이는 `inputGuardrails` 및 `outputGuardrails` 배열을 통해 구성합니다. 자세한 내용은 [Guardrails](/openai-agents-js/ko/guides/guardrails)를 참조하세요.
118+
119+
---
120+
121+
## 에이전트 복제/복사
122+
123+
기존 에이전트의 약간 수정된 버전이 필요하신가요? 완전히 새로운 `Agent` 인스턴스를 반환하는 `clone()` 메서드를 사용하세요.
124+
125+
<Code lang="typescript" code={agentCloning} title="에이전트 복제" />
126+
127+
---
128+
129+
## 도구 사용 강제
130+
131+
도구를 제공해도 LLM이 반드시 호출하는 것은 아닙니다. `modelSettings.tool_choice`로 도구 사용을 **강제**할 수 있습니다:
132+
133+
1. `'auto'`(기본값) – LLM이 도구 사용 여부를 결정
134+
2. `'required'` – LLM이 반드시 도구를 호출해야 함(어떤 도구를 쓸지는 선택 가능)
135+
3. `'none'` – LLM은 도구를 **호출하면 안 됨**
136+
4. 특정 도구 이름(예: `'calculator'`) – LLM은 해당 도구를 반드시 호출해야 함
137+
138+
<Code lang="typescript" code={agentForcingToolUse} title="도구 사용 강제" />
139+
140+
### 무한 루프 방지
141+
142+
도구 호출 후 SDK는 자동으로 `tool_choice`를 `'auto'`로 재설정합니다. 이는 모델이 도구를 반복해서 호출하려는 무한 루프에 빠지는 것을 방지합니다. 이 동작은 `resetToolChoice` 플래그로 오버라이드하거나 `toolUseBehavior`를 구성하여 변경할 수 있습니다:
143+
144+
- `'run_llm_again'`(기본값) – 도구 결과로 LLM을 다시 실행
145+
- `'stop_on_first_tool'` – 첫 번째 도구 결과를 최종 답변으로 처리
146+
- `{ stopAtToolNames: ['my_tool'] }` – 나열된 도구 중 하나가 호출되면 중지
147+
- `(context, toolResults) => ...` – 실행을 종료해야 하는지 여부를 반환하는 사용자 정의 함수
148+
149+
```typescript
150+
const agent = new Agent({
151+
...,
152+
toolUseBehavior: 'stop_on_first_tool',
153+
});
154+
```
155+
156+
---
157+
158+
## 다음 단계
159+
160+
- [Running Agents](/openai-agents-js/ko/guides/running-agents)를 학습하세요
161+
- [Tools](/openai-agents-js/ko/guides/tools), [Guardrails](/openai-agents-js/ko/guides/guardrails), [Models](/openai-agents-js/ko/guides/models)를 살펴보세요
162+
- 사이드바의 **@openai/agents** 아래에서 전체 TypeDoc 레퍼런스를 확인하세요

0 commit comments

Comments
 (0)