에이전트를
실제로 움직이는
Python 실행 도구.
에이전트, 도구, handoff, guardrail, session, tracing을 조합해 에이전트형 애플리케이션을 만드는 오픈소스 SDK입니다.
이 레포, 나한테 필요한가?
실행은 미검증
- 무엇인가
- Python용 에이전트 애플리케이션 SDK [C-001]
- 핵심 가치
- 실행 루프·도구·위임·기억·추적을 한 구조에서 조합 [C-002—006]
- 진입 조건
- Python 3.10+ · API 키 · 코드 작성 [C-008·012]
- 먼저 확인
- 단순 호출이나 노코드 목적에는 필요 이상으로 클 수 있음 [FIT]
이걸로 실제로 할 수 있는 일
기능 이름보다 사용자가 완성할 수 있는 실행 흐름을 기준으로 정리했습니다.
도구를 쓰는 업무 에이전트
Python 함수, 호스팅 도구, MCP 등을 연결해 검색·조회·처리 같은 행동을 실행 흐름 안에 넣을 수 있습니다.
전문가에게 넘기는 멀티에이전트 흐름
분류 에이전트가 전문 에이전트로 제어를 넘기는 handoff와, 총괄이 전문가를 도구처럼 호출하는 패턴을 구성할 수 있습니다.
대화를 기억하고 추적하는 앱
session으로 여러 실행 사이의 이력을 유지하고, tracing으로 모델·도구·handoff·guardrail 이벤트를 살펴볼 수 있습니다.
기능보다 중요한 건
지금 내 상황과의 적합성.
아래 평가는 공식 기능과 시작 조건에서 도출한 GitExplain의 판단입니다.
- Python 코드를 읽고 예제를 수정할 수 있다
- 역할·도구·상태가 있는 AI 워크플로가 필요하다
- 실행 과정을 tracing으로 관찰하고 싶다
- 코드 없이 완성되는 노코드 빌더를 원한다
- 한 번의 단순 모델 호출이면 충분하다
- JavaScript·TypeScript만으로 프로젝트를 운영한다
어떻게 움직이나
Runner가 모델 응답과 도구 실행을 이어가며, 필요하면 다른 에이전트로 제어를 넘기고 session·tracing이 흐름을 기록합니다.
이 도식은 공식 개념을 이해하기 쉽게 단순화한 것이며, 모든 실행이 정확히 이 순서로 고정되는 것은 아닙니다. [C-002—006]
가장 짧은 시작 경로
- 01Python 3.10+ 환경 준비
가상환경을 만들고 활성화합니다.
- 02SDK 설치
pip install openai-agents또는uv add openai-agents - 03API 키 설정
공식 quickstart는
OPENAI_API_KEY환경 변수를 사용합니다. - 04Agent를 만들고 Runner로 실행
처음에는 단일 에이전트로 시작한 뒤 도구와 handoff를 추가하는 편이 이해하기 쉽습니다.
GitExplain은 이번 검수에서 설치 명령과 샘플 코드를 직접 실행하지 않았습니다.
from agents import Agent, Runner
agent = Agent(
name="Assistant",
instructions="Answer clearly."
)
result = Runner.run_sync(
agent,
"What can you help with?"
)
print(result.final_output)AI에게 설명과 설치를 한 번에 맡기기
공식 문서를 다시 확인하고 내 운영체제와 환경을 먼저 질문하도록 만든 프롬프트입니다. 설치 명령을 무작정 실행하지 않고, 변경 내용과 되돌리는 방법까지 설명하게 합니다.
API 키와 비밀 값은 채팅에 직접 붙여 넣지 마세요.
아래 내용을 Codex 같은 코딩 에이전트에 붙여 넣으면 공식 문서를 다시 확인한 뒤 내 환경에 맞는 설치를 안내합니다.
너는 내 로컬 개발 환경에서 오픈소스 저장소를 안전하게 설명하고 설치하는 시니어 엔지니어야.
저장소: https://github.com/openai/openai-agents-python
GitExplain 요약: 에이전트, 도구, handoff, guardrail, session, tracing을 조합해 에이전트형 애플리케이션을 만드는 Python SDK야.
해야 할 일:
1. 최신 README, 공식 Quickstart, pyproject.toml을 먼저 읽고 현재 기본 브랜치 기준으로 설명해줘.
2. 이 SDK로 무엇을 만들 수 있는지 비개발자도 이해할 수 있게 짧게 설명해줘.
3. 내 운영체제, Python 버전, 패키지 관리 도구를 먼저 질문해줘.
4. 가상환경 생성부터 openai-agents 설치까지 단계별로 제시하고 각 명령이 바꾸는 것을 설명해줘.
5. OPENAI_API_KEY는 채팅이나 코드에 직접 적게 하지 말고 환경 변수와 .env 예시로 안내해줘.
6. 공식 최소 예제를 실행해 설치 성공 여부를 확인하고, 실패하면 원인과 되돌리는 방법을 알려줘.
7. GitExplain 요약과 공식 문서가 다르면 공식 문서를 우선하고 차이를 명시해줘.
8. 파괴적인 명령은 내 명시적 승인 전에는 실행하지 마.도입 전에 놓치기 쉬운 점
tracing은 기본 활성화입니다. 민감한 입력을 다룬다면 기록 범위와 조직의 데이터 정책을 먼저 확인해야 합니다.
[C-006·013]입출력 guardrail과 tool guardrail은 적용 위치가 다릅니다. handoff 자체에는 함수 도구용 guardrail이 그대로 적용되지 않습니다.
[C-007]최근 릴리스, 별 수, SECURITY.md의 존재만으로 안정성이나 취약점 부재를 판단할 수 없습니다.
[QA]근거 원장
바뀔 수 있는 정보는 원문과 확인 시각을 함께 남깁니다.