docs: update translated document pages (#2527)

Author: github-actions[bot]

docs/ja/running_agents.md

@@ -4,9 +4,9 @@ search:
 ---
 # 세션
 
-Agents SDK는 여러 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하기 위한 내장 세션 메모리를 제공하므로, 턴 사이에 `.to_input_list()`를 수동으로 처리할 필요가 없습니다.
+Agents SDK 는 내장된 세션 메모리를 제공하여 여러 번의 에이전트 실행에 걸쳐 대화 기록을 자동으로 유지하므로, 턴 사이에 `.to_input_list()` 를 수동으로 처리할 필요가 없습니다.
 
-세션은 특정 세션의 대화 기록을 저장하여, 명시적인 수동 메모리 관리 없이도 에이전트가 컨텍스트를 유지할 수 있게 합니다. 이는 에이전트가 이전 상호작용을 기억하길 원하는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때 특히 유용합니다.
+세션은 특정 세션의 대화 기록을 저장하여, 에이전트가 명시적인 수동 메모리 관리 없이도 컨텍스트를 유지할 수 있게 합니다. 이는 채팅 애플리케이션이나 멀티턴 대화를 구축할 때, 에이전트가 이전 상호작용을 기억하길 원하는 경우에 특히 유용합니다.
 
 ## 빠른 시작
 
@@ -49,19 +49,80 @@ print(result.final_output)  # "Approximately 39 million"
 
 ## 동작 방식
 
-세션 메모리가 활성화되면:
+세션 메모리가 활성화되어 있을 때:
 
-1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 아이템 앞에 추가합니다
+1. **각 실행 전**: 러너가 세션의 대화 기록을 자동으로 가져와 입력 아이템 앞에 덧붙입니다
 2. **각 실행 후**: 실행 중 생성된 모든 새 아이템(사용자 입력, 어시스턴트 응답, 도구 호출 등)이 자동으로 세션에 저장됩니다
-3. **컨텍스트 보존**: 동일한 세션으로 이후 실행을 할 때마다 전체 대화 기록이 포함되어, 에이전트가 컨텍스트를 유지할 수 있습니다
+3. **컨텍스트 보존**: 동일한 세션으로 이어지는 각 실행에는 전체 대화 기록이 포함되어, 에이전트가 컨텍스트를 유지할 수 있습니다
 
-이를 통해 `.to_input_list()`를 수동으로 호출하고 실행 사이의 대화 상태를 관리할 필요가 없어집니다.
+이로써 `.to_input_list()` 를 수동으로 호출하고 실행 간 대화 상태를 관리할 필요가 없어집니다.
+
+## 준비된 입력 커스터마이징
+
+세션을 전달하면, 러너는 보통 모델 입력을 다음과 같이 준비합니다:
+
+1. 세션 히스토리(`session.get_items(...)` 에서 가져옴)
+2. 새 턴 입력
+
+모델 호출 전에 해당 병합 단계를 커스터마이징하려면 [`RunConfig.session_input_callback`][agents.run.RunConfig.session_input_callback] 을 사용하세요. 콜백은 두 개의 리스트를 받습니다:
+
+-   `history`: 가져온 세션 히스토리(이미 input-item 형식으로 정규화됨)
+-   `new_input`: 현재 턴의 새 입력 아이템
+
+모델에 보낼 최종 입력 아이템 리스트를 반환하세요.
+
+```python
+from agents import Agent, RunConfig, Runner, SQLiteSession
+
+
+def keep_recent_history(history, new_input):
+    # Keep only the last 10 history items, then append the new turn.
+    return history[-10:] + new_input
+
+
+agent = Agent(name="Assistant")
+session = SQLiteSession("conversation_123")
+
+result = await Runner.run(
+    agent,
+    "Continue from the latest updates only.",
+    session=session,
+    run_config=RunConfig(session_input_callback=keep_recent_history),
+)
+```
+
+세션이 아이템을 저장하는 방식은 바꾸지 않으면서, 히스토리의 커스텀 프루닝(pruning), 재정렬, 선택적 포함이 필요할 때 사용하세요.
+
+## 가져오는 히스토리 제한
+
+각 실행 전에 가져올 히스토리 양을 제어하려면 [`SessionSettings`][agents.memory.SessionSettings] 를 사용하세요.
+
+-   `SessionSettings(limit=None)` (기본값): 사용 가능한 모든 세션 아이템을 가져옵니다
+-   `SessionSettings(limit=N)`: 가장 최근의 `N` 개 아이템만 가져옵니다
+
+실행별로 [`RunConfig.session_settings`][agents.run.RunConfig.session_settings] 를 통해 적용할 수 있습니다:
+
+```python
+from agents import Agent, RunConfig, Runner, SessionSettings, SQLiteSession
+
+agent = Agent(name="Assistant")
+session = SQLiteSession("conversation_123")
+
+result = await Runner.run(
+    agent,
+    "Summarize our recent discussion.",
+    session=session,
+    run_config=RunConfig(session_settings=SessionSettings(limit=50)),
+)
+```
+
+세션 구현이 기본 세션 설정을 노출하는 경우, `RunConfig.session_settings` 는 해당 실행에서 `None` 이 아닌 값들을 오버라이드합니다. 이는 긴 대화에서, 세션의 기본 동작을 바꾸지 않으면서도 가져오기 크기에 상한을 두고 싶을 때 유용합니다.
 
 ## 메모리 작업
 
 ### 기본 작업
 
-세션은 대화 기록을 관리하기 위한 여러 작업을 지원합니다:
+세션은 대화 기록 관리를 위한 여러 작업을 지원합니다:
 
 ```python
 from agents import SQLiteSession
@@ -88,7 +149,7 @@ await session.clear_session()
 
 ### 수정 시 pop_item 사용
 
-`pop_item` 메서드는 대화에서 마지막 아이템을 되돌리거나 수정하려는 경우 특히 유용합니다:
+`pop_item` 메서드는 대화에서 마지막 아이템을 되돌리거나 수정하고 싶을 때 특히 유용합니다:
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -119,11 +180,11 @@ print(f"Agent: {result.final_output}")
 
 ## 세션 유형
 
-SDK는 다양한 사용 사례를 위한 여러 세션 구현을 제공합니다:
+SDK 는 다양한 사용 사례를 위해 여러 세션 구현을 제공합니다:
 
 ### OpenAI Conversations API 세션
 
-`OpenAIConversationsSession`을 통해 [OpenAI의 Conversations API](https://platform.openai.com/docs/api-reference/conversations)를 사용합니다.
+`OpenAIConversationsSession` 을 통해 [OpenAI's Conversations API](https://platform.openai.com/docs/api-reference/conversations) 를 사용합니다.
 
 ```python
 from agents import Agent, Runner, OpenAIConversationsSession
@@ -157,9 +218,9 @@ result = await Runner.run(
 print(result.final_output)  # "California"
 ```
 
-### OpenAI Responses 압축 세션
+### OpenAI Responses compaction 세션
 
-`OpenAIResponsesCompactionSession`을 사용하면 Responses API(`responses.compact`)로 세션 기록을 압축할 수 있습니다. 이는 기본 세션을 감싸는 래퍼이며, `should_trigger_compaction`에 따라 각 턴 이후 자동으로 압축할 수 있습니다.
+`OpenAIResponsesCompactionSession` 을 사용하면 Responses API(`responses.compact`) 로 세션 히스토리를 압축(compact)할 수 있습니다. 이는 하위 세션을 래핑하며, `should_trigger_compaction` 에 따라 각 턴 후 자동으로 압축할 수 있습니다.
 
 #### 일반적인 사용(자동 압축)
 
@@ -178,13 +239,13 @@ result = await Runner.run(agent, "Hello", session=session)
 print(result.final_output)
 ```
 
-기본적으로 후보 임계값에 도달하면 각 턴 이후 압축이 실행됩니다.
+기본적으로 후보 임계값에 도달하면 각 턴 후 압축이 실행됩니다.
 
-#### 자동 압축은 스트리밍을 차단할 수 있음
+#### 자동 압축은 스트리밍을 블로킹할 수 있음
 
-압축은 세션 기록을 지우고 다시 쓰므로, SDK는 압축이 끝날 때까지 실행이 완료된 것으로 간주하지 않습니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()`가 몇 초 동안 열린 상태로 유지될 수 있습니다.
+압축은 세션 히스토리를 비우고 다시 쓰므로, SDK 는 실행이 완료되었다고 간주하기 전에 압축이 끝나길 기다립니다. 스트리밍 모드에서는 압축이 무거운 경우 마지막 출력 토큰 이후에도 `run.stream_events()` 가 몇 초 동안 열려 있을 수 있다는 뜻입니다.
 
-지연이 낮은 스트리밍이나 빠른 턴 전환이 필요하다면 자동 압축을 비활성화하고, 턴 사이(또는 유휴 시간)에 직접 `run_compaction()`을 호출하세요. 자체 기준에 따라 언제 압축을 강제할지 결정할 수 있습니다.
+낮은 지연의 스트리밍이나 빠른 턴 전환이 필요하다면 자동 압축을 비활성화하고, 턴 사이(또는 유휴 시간)에 직접 `run_compaction()` 을 호출하세요. 자체 기준에 따라 언제 압축을 강제할지 결정할 수 있습니다.
 
 ```python
 from agents import Agent, Runner, SQLiteSession
@@ -207,7 +268,7 @@ await session.run_compaction({"force": True})
 
 ### SQLite 세션
 
-SQLite를 사용하는 기본 경량 세션 구현입니다:
+SQLite 를 사용하는 기본 경량 세션 구현입니다:
 
 ```python
 from agents import SQLiteSession
@@ -228,7 +289,7 @@ result = await Runner.run(
 
 ### 비동기 SQLite 세션
 
-`aiosqlite` 기반의 SQLite 영속성이 필요하면 `AsyncSQLiteSession`을 사용하세요.
+`aiosqlite` 기반 SQLite 영속성이 필요할 때 `AsyncSQLiteSession` 을 사용하세요.
 
 ```bash
 pip install aiosqlite
@@ -245,7 +306,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### Redis 세션
 
-여러 워커 또는 서비스 간에 공유되는 세션 메모리가 필요하면 `RedisSession`을 사용하세요.
+여러 워커나 서비스에 걸쳐 공유되는 세션 메모리가 필요하면 `RedisSession` 을 사용하세요.
 
 ```bash
 pip install openai-agents[redis]
@@ -265,7 +326,7 @@ result = await Runner.run(agent, "Hello", session=session)
 
 ### SQLAlchemy 세션
 
-SQLAlchemy가 지원하는 어떤 데이터베이스든 사용할 수 있는 프로덕션 준비 세션입니다:
+SQLAlchemy 가 지원하는 어떤 데이터베이스든 사용할 수 있는 프로덕션 준비 세션입니다:
 
 ```python
 from agents.extensions.memory import SQLAlchemySession
@@ -283,13 +344,13 @@ engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/db")
 session = SQLAlchemySession("user_123", engine=engine, create_tables=True)
 ```
 
-자세한 문서는 [SQLAlchemy Sessions](sqlalchemy_session.md)를 참고하세요.
+자세한 문서는 [SQLAlchemy Sessions](sqlalchemy_session.md) 를 참고하세요.
 
 
 
 ### 고급 SQLite 세션
 
-대화 분기, 사용량 분석, structured outputs 쿼리를 지원하는 강화된 SQLite 세션입니다:
+대화 브랜칭, 사용량 분석, structured queries 를 제공하는 강화된 SQLite 세션입니다:
 
 ```python
 from agents.extensions.memory import AdvancedSQLiteSession
@@ -309,9 +370,9 @@ await session.store_run_usage(result)  # Track token usage
 await session.create_branch_from_turn(2)  # Branch from turn 2
 ```
 
-자세한 문서는 [Advanced SQLite Sessions](advanced_sqlite_session.md)를 참고하세요.
+자세한 문서는 [Advanced SQLite Sessions](advanced_sqlite_session.md) 를 참고하세요.
 
-### 암호화된 세션
+### 암호화 세션
 
 어떤 세션 구현에도 적용 가능한 투명한 암호화 래퍼입니다:
 
@@ -336,33 +397,33 @@ session = EncryptedSession(
 result = await Runner.run(agent, "Hello", session=session)
 ```
 
-자세한 문서는 [Encrypted Sessions](encrypted_session.md)를 참고하세요.
+자세한 문서는 [Encrypted Sessions](encrypted_session.md) 를 참고하세요.
 
 ### 기타 세션 유형
 
-몇 가지 내장 옵션이 더 있습니다. `examples/memory/` 및 `extensions/memory/` 아래의 소스 코드를 참고하세요.
+몇 가지 내장 옵션이 더 있습니다. `examples/memory/` 와 `extensions/memory/` 아래의 소스 코드를 참고하세요.
 
 ## 세션 관리
 
-### 세션 ID 명명
+### 세션 ID 네이밍
 
-대화를 정리하는 데 도움이 되는 의미 있는 세션 ID를 사용하세요:
+대화를 정리하는 데 도움이 되는 의미 있는 세션 ID 를 사용하세요:
 
 -   사용자 기반: `"user_12345"`
 -   스레드 기반: `"thread_abc123"`
 -   컨텍스트 기반: `"support_ticket_456"`
 
 ### 메모리 영속성
 
--   임시 대화에는 인메모리 SQLite(`SQLiteSession("session_id")`)를 사용하세요
--   영속 대화에는 파일 기반 SQLite(`SQLiteSession("session_id", "path/to/db.sqlite")`)를 사용하세요
--   `aiosqlite` 기반 구현이 필요하면 비동기 SQLite(`AsyncSQLiteSession("session_id", db_path="...")`)를 사용하세요
--   공유되고 지연이 낮은 세션 메모리가 필요하면 Redis 백엔드 세션(`RedisSession.from_url("session_id", url="redis://...")`)을 사용하세요
--   SQLAlchemy가 지원하는 기존 데이터베이스를 사용하는 프로덕션 시스템에는 SQLAlchemy 기반 세션(`SQLAlchemySession("session_id", engine=engine, create_tables=True)`)을 사용하세요
--   내장 텔레메트리, 트레이싱, 데이터 격리를 갖추고 30개 이상의 데이터베이스 백엔드를 지원하는 프로덕션 클라우드 네이티브 배포에는 Dapr 상태 저장소 세션(`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`)을 사용하세요
--   OpenAI Conversations API에 기록을 저장하고 싶다면 OpenAI 호스트하는 스토리지(`OpenAIConversationsSession()`)를 사용하세요
--   투명한 암호화 및 TTL 기반 만료로 어떤 세션이든 감싸려면 암호화된 세션(`EncryptedSession(session_id, underlying_session, encryption_key)`)을 사용하세요
--   더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django)을 대상으로 커스텀 세션 백엔드 구현을 고려하세요
+-   임시 대화에는 인메모리 SQLite (`SQLiteSession("session_id")`) 를 사용하세요
+-   영속 대화에는 파일 기반 SQLite (`SQLiteSession("session_id", "path/to/db.sqlite")`) 를 사용하세요
+-   `aiosqlite` 기반 구현이 필요하면 비동기 SQLite (`AsyncSQLiteSession("session_id", db_path="...")`) 를 사용하세요
+-   공유되고 지연이 낮은 세션 메모리가 필요하면 Redis 기반 세션 (`RedisSession.from_url("session_id", url="redis://...")`) 을 사용하세요
+-   SQLAlchemy 가 지원하는 기존 데이터베이스를 사용하는 프로덕션 시스템에는 SQLAlchemy 기반 세션 (`SQLAlchemySession("session_id", engine=engine, create_tables=True)`) 을 사용하세요
+-   내장 텔레메트리, 트레이싱, 데이터 격리를 갖춘 30+ 데이터베이스 백엔드 지원이 필요한 프로덕션 클라우드 네이티브 배포에는 Dapr state store 세션 (`DaprSession.from_address("session_id", state_store_name="statestore", dapr_address="localhost:50001")`) 을 사용하세요
+-   히스토리를 OpenAI Conversations API 에 저장하고 싶다면 OpenAI 호스트하는 스토리지 (`OpenAIConversationsSession()`) 를 사용하세요
+-   투명한 암호화와 TTL 기반 만료를 위해 어떤 세션이든 래핑하려면 암호화 세션 (`EncryptedSession(session_id, underlying_session, encryption_key)`) 을 사용하세요
+-   더 고급 사용 사례를 위해 다른 프로덕션 시스템(예: Django) 용 커스텀 세션 백엔드 구현을 고려하세요
 
 ### 여러 세션
 
@@ -523,11 +584,11 @@ result = await Runner.run(
 
 | Package | Description |
 |---------|-------------|
-| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django가 지원하는 어떤 데이터베이스(PostgreSQL, MySQL, SQLite 등)에서도 사용할 수 있는 Django ORM 기반 세션 |
+| [openai-django-sessions](https://pypi.org/project/openai-django-sessions/) | Django 가 지원하는 어떤 데이터베이스(PostgreSQL, MySQL, SQLite 등)에도 사용할 수 있는 Django ORM 기반 세션 |
 
-세션 구현을 만들었다면, 여기에 추가할 수 있도록 문서 PR을 제출해 주세요!
+세션 구현을 만들었다면, 여기에 추가할 수 있도록 문서 PR 을 제출해 주세요!
 
-## API 레퍼런스
+## API 참조
 
 자세한 API 문서는 다음을 참고하세요:
 
@@ -536,8 +597,8 @@ result = await Runner.run(
 -   [`OpenAIResponsesCompactionSession`][agents.memory.openai_responses_compaction_session.OpenAIResponsesCompactionSession] - Responses API 압축 래퍼
 -   [`SQLiteSession`][agents.memory.sqlite_session.SQLiteSession] - 기본 SQLite 구현
 -   [`AsyncSQLiteSession`][agents.extensions.memory.async_sqlite_session.AsyncSQLiteSession] - `aiosqlite` 기반 비동기 SQLite 구현
--   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 백엔드 세션 구현
+-   [`RedisSession`][agents.extensions.memory.redis_session.RedisSession] - Redis 기반 세션 구현
 -   [`SQLAlchemySession`][agents.extensions.memory.sqlalchemy_session.SQLAlchemySession] - SQLAlchemy 기반 구현
--   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr 상태 저장소 구현
--   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 분기 및 분석 기능을 갖춘 강화된 SQLite
+-   [`DaprSession`][agents.extensions.memory.dapr_session.DaprSession] - Dapr state store 구현
+-   [`AdvancedSQLiteSession`][agents.extensions.memory.advanced_sqlite_session.AdvancedSQLiteSession] - 브랜칭과 분석을 포함한 강화된 SQLite
 -   [`EncryptedSession`][agents.extensions.memory.encrypt_session.EncryptedSession] - 어떤 세션에도 적용 가능한 암호화 래퍼