openai-agents-python/docs/ko/quickstart.md
2026-11-10 07:54:51 +00:00

228 lines
No EOL
7.3 KiB
Markdown

---
search:
exclude: true
---
# 빠른 시작
## 프로젝트 및 가상 환경 생성 {#create-a-project-and-virtual-environment}
이 작업은 한 번만 수행하면 됩니다.
```bash
mkdir my_project
cd my_project
python -m venv .venv
```
### 가상 환경 활성화 {#activate-the-virtual-environment}
새 터미널 세션을 시작할 때마다 수행합니다.
macOS 또는 Linux:
```bash
source .venv/bin/activate
```
Windows:
```cmd
.venv\Scripts\activate
```
### Agents SDK 설치 {#install-the-agents-sdk}
```bash
pip install openai-agents # or `uv add openai-agents`, etc
```
### OpenAI API 키 설정 {#set-an-openai-api-key}
키가 없다면 [다음 안내](https://platform.openai.com/docs/quickstart#create-and-export-an-api-key)에 따라 OpenAI API 키를 생성하세요.
다음 명령은 현재 터미널 세션에 키를 설정합니다.
macOS 또는 Linux:
```bash
export OPENAI_API_KEY=sk-...
```
Windows PowerShell:
```powershell
$env:OPENAI_API_KEY = "sk-..."
```
Windows 명령 프롬프트:
```cmd
set "OPENAI_API_KEY=sk-..."
```
## 첫 번째 에이전트 생성 {#create-your-first-agent}
에이전트는 instructions, 이름, 특정 모델과 같은 선택적 구성으로 정의됩니다.
```python
from agents import Agent
agent = Agent(
name="History Tutor",
instructions="You answer history questions clearly and concisely.",
)
```
## 첫 번째 에이전트 실행 {#run-your-first-agent}
[`Runner`][agents.run.Runner]을 사용하여 에이전트를 실행하고 [`RunResult`][agents.result.RunResult]을 반환받습니다.
```python
import asyncio
from agents import Agent, Runner
agent = Agent(
name="History Tutor",
instructions="You answer history questions clearly and concisely.",
)
async def main():
result = await Runner.run(agent, "When did the Roman Empire fall?")
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
```
두 번째 턴에서는 `result.to_input_list()`을 `Runner.run(...)`에 다시 전달하거나, [세션](sessions/index.md)을 연결하거나, `conversation_id` / `previous_response_id`을 사용해 OpenAI 서버 관리 상태를 재사용할 수 있습니다. [에이전트 실행](running_agents.md) 가이드에서는 이러한 접근 방식을 비교합니다.
다음 기준을 활용하세요.
| 원하는 사항 | 시작 방법 |
| --- | --- |
| 완전한 수동 제어 및 제공자 독립적인 기록 | `result.to_input_list()` |
| SDK를 통한 기록 불러오기 및 저장 | [`session=...`](sessions/index.md) |
| OpenAI가 관리하는 서버 측 연속 실행 | `previous_response_id` 또는 `conversation_id` |
장단점과 정확한 동작은 [에이전트 실행](running_agents.md#choose-a-memory-strategy)을 참조하세요.
작업이 주로 프롬프트, 도구, 대화 상태로 구성되는 경우 일반 `Agent`과 `Runner`을 함께 사용하세요. 에이전트가 격리된 작업 공간에서 실제 파일을 검사하거나 수정해야 한다면 [샌드박스 에이전트 빠른 시작](sandbox_agents.md)으로 이동하세요.
## 에이전트에 도구 제공 {#give-your-agent-tools}
에이전트에 정보를 조회하거나 작업을 수행할 수 있는 도구를 제공할 수 있습니다.
```python
import asyncio
from agents import Agent, Runner
from agents.decorators import tool
@tool
def history_fun_fact() -> str:
"""Return a short history fact."""
return "Sharks are older than trees."
agent = Agent(
name="History Tutor",
instructions="Answer history questions clearly. Use history_fun_fact when it helps.",
tools=[history_fun_fact],
)
async def main():
result = await Runner.run(
agent,
"Tell me something surprising about ancient life on Earth.",
)
print(result.final_output)
if __name__ == "__main__":
asyncio.run(main())
```
## 에이전트 추가 {#add-a-few-more-agents}
다중 에이전트 패턴을 선택하기 전에 최종 답변을 누가 담당할지 결정하세요.
- **핸드오프**: 전문 에이전트가 해당 턴의 일부에 대한 대화를 넘겨받습니다.
- **Agents as tools**: 오케스트레이터가 제어권을 유지하면서 전문 에이전트를 도구로 호출합니다.
이 빠른 시작에서는 첫 번째 예제로 가장 간단한 **핸드오프**를 계속 사용합니다. 관리자 스타일 패턴은 [에이전트 오케스트레이션](multi_agent.md) 및 [도구: Agents as tools](tools.md#agents-as-tools)을 참조하세요.
추가 에이전트도 같은 방식으로 정의할 수 있습니다. `handoff_description`은 라우팅 에이전트에 언제 위임해야 하는지에 대한 추가 컨텍스트를 제공합니다.
```python
from agents import Agent
history_tutor_agent = Agent(
name="History Tutor",
handoff_description="Specialist agent for historical questions",
instructions="You answer history questions clearly and concisely.",
)
math_tutor_agent = Agent(
name="Math Tutor",
handoff_description="Specialist agent for math questions",
instructions="You explain math step by step and include worked examples.",
)
```
## 핸드오프 정의 {#define-your-handoffs}
에이전트에는 작업을 해결하는 동안 선택할 수 있는 발신 핸드오프 옵션 목록을 정의할 수 있습니다.
```python
triage_agent = Agent(
name="Triage Agent",
instructions="Route each homework question to the right specialist.",
handoffs=[history_tutor_agent, math_tutor_agent],
)
```
## 에이전트 오케스트레이션 실행 {#run-the-agent-orchestration}
러너는 개별 에이전트 실행, 모든 핸드오프 및 모든 도구 호출을 처리합니다.
```python
import asyncio
from agents import Runner
async def main():
result = await Runner.run(
triage_agent,
"Who was the first president of the United States?",
)
print(result.final_output)
print(f"Answered by: {result.last_agent.name}")
if __name__ == "__main__":
asyncio.run(main())
```
## 참조 코드 예제 {#reference-examples}
리포지토리에는 동일한 핵심 패턴을 보여 주는 전체 스크립트가 포함되어 있습니다.
- 첫 번째 실행을 위한 [`examples/basic/hello_world.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/hello_world.py)
- 함수 도구를 위한 [`examples/basic/tools.py`](https://github.com/openai/openai-agents-python/tree/main/examples/basic/tools.py)
- 다중 에이전트 라우팅을 위한 [`examples/agent_patterns/routing.py`](https://github.com/openai/openai-agents-python/tree/main/examples/agent_patterns/routing.py)
## 트레이스 확인 {#view-your-traces}
에이전트 실행 중 발생한 작업을 검토하려면 [OpenAI 대시보드의 트레이스 뷰어](https://platform.openai.com/traces)로 이동하여 에이전트 실행의 트레이스를 확인하세요.
## 다음 단계 {#next-steps}
더 복잡한 에이전트 워크플로를 구축하는 방법을 알아보세요.
- [에이전트](agents.md) 구성 방법 알아보기
- [에이전트 실행](running_agents.md) 및 [세션](sessions/index.md) 알아보기
- 실제 작업 공간에서 작업해야 하는 경우 [샌드박스 에이전트](sandbox_agents.md) 알아보기
- [도구](tools.md), [가드레일](guardrails.md), [모델](models/index.md) 알아보기