> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Turn
> Turn 클래스는 사용자와 에이전트 간의 한 차례 대화 교환을 invoke_agent span으로 기록합니다.
```python theme={"system"}
class Turn(BaseModel): ...
```
사용자와 에이전트 간의 한 차례 상호작용입니다. invoke\_agent OTel span에 매핑됩니다.
기본적으로 각 턴은 자체 OTel 트레이스를 시작하므로(`continue_parent_trace=False`)
Conversations 탭에는 턴마다 트레이스가 하나씩 표시됩니다. 외부 트레이스가 이미
활성 상태이고 에이전트 호출을 그 안에 중첩하려면(예: fastapi로 계측된 요청
내부) Conversation(또는 Turn에 직접)에 `continue_parent_trace=True`를
설정하세요.
`Turn`은 Pydantic 모델입니다. 생성할 때 아래 필드를 키워드 인수로 설정할 수 있습니다.
`Turn`은 컨텍스트 관리자이므로 `with` 문에서 사용할 수 있습니다.
필드
| 필드 | 유형 | 기본값 |
| - | - | - |
| `agent_name` | `str` | `''` |
| `model` | `str` | `''` |
| `agent_id` | `str` | `''` |
| `agent_description` | `str` | `''` |
| `agent_version` | `str` | `''` |
| `system_instructions` | `list[str]` | `[]` |
| `messages` | `list[Message]` | `[]` |
| `output_messages` | `list[Message]` | `[]` |
| `spans` | `list[Union[LLM, Tool, SubAgent]]` | `[]` |
| `continue_parent_trace` | `bool` | `False` |
| `started_at` | `Union[datetime, None]` | `None` |
| `ended_at` | `Union[datetime, None]` | `None` |
메서드
user
```python theme={"system"}
def user(content: str) -> Turn: ...
```
턴 도중에 사용자 메시지를 추가합니다.
start\_llm
```python theme={"system"}
def start_llm(
*,
model: str = '',
provider_name: str = '',
system_instructions: Union[list[str], None] = None,
) -> LLM: ...
```
LLM Call을 시작합니다(이 턴의 하위 항목인 chat span).
`_current_llm` contextvar를 설정하므로 컨텍스트 관리자 사용 여부와 관계없이
`get_current_llm()`으로 LLM에 접근할 수 있습니다.
```python theme={"system"}
def start_tool(*, name: str, arguments: str = '', tool_call_id: str = '') -> Tool: ...
```
도구 실행을 시작합니다(이 턴의 하위 span인 execute\_tool span).
start\_subagent
```python theme={"system"}
def start_subagent(
*,
name: str,
model: str = '',
system_instructions: Union[list[str], None] = None,
set_current: bool = True,
) -> SubAgent: ...
```
하위 에이전트 호출을 시작합니다(같은 트레이스 안에 중첩된 invoke\_agent span 생성).
record
```python theme={"system"}
def record(
*,
messages: Union[list[Message], None] = None,
output_messages: Union[list[Message], None] = None,
system_instructions: Union[list[str], None] = None,
agent_name: Union[str, None] = None,
model: Union[str, None] = None,
agent_id: Union[str, None] = None,
agent_description: Union[str, None] = None,
agent_version: Union[str, None] = None,
) -> Turn: ...
```
여러 턴 필드를 한 번의 호출로 설정합니다.
수동으로 계측한 에이전트가 턴에 필드별로 하나씩 수행하던
할당(`system_instructions`, `agent_id`,
...)을 단일 키워드 호출로 통합합니다. 명시적으로 전달한
(`None`이 아닌) 필드만 적용되며, 기존 값은 그대로 유지됩니다.
`messages`와 `output_messages`는 각각 독립적으로 턴의
기존 입력 메시지와 출력 메시지를 대체합니다. 입력 메시지 하나를 추가하는
`Turn.user(...)`와는 이 점이 다릅니다. 체이닝할 수 있도록 `self`를 반환합니다.
`LLM.record`와 같은 방식으로 동작합니다.
참고: 스트리밍(`with`) 경로에서는 `__enter__` 시점의 `agent_name`으로
턴 span의 이름이 정해집니다. 따라서 span 이름에 `agent_name`을 반영해야 한다면
`record` 대신 `start_turn`으로 `agent_name`을 설정하세요. 이 경우에도 `record`는
`gen_ai.agent.name`
속성을 업데이트합니다.
end
```python theme={"system"}
def end() -> None: ...
```
start
```python theme={"system"}
def start() -> Self: ...
```
이 span을 한 번 시작합니다. 컨텍스트 관리자로 진입할 때도 동일한 경로를 사용합니다.
record\_error
```python theme={"system"}
def record_error(error: BaseException) -> Self: ...
```
span을 종료하지 않고 실패를 기록합니다. span을 종료할 준비가 되면 `end()`를 호출하세요.
set\_attributes
```python theme={"system"}
def set_attributes(attributes: dict[str, Any]) -> Self: ...
```
이 span에 임의의 OTel 속성을 지정합니다.
키가 하나이든 여러 개이든 dict를 전달하세요. 키가 하나뿐이라면
`span.set_attributes({"weave.tag": "value"})`와 같이 사용합니다. OTel의
`Span.set_attributes`와 동일하게 동작합니다.
`start_*` 팩토리, `start()` 또는 `with`로 span을 시작한 후,
span이 종료되기 전에 호출해야 합니다. 이 윈도우 밖에서 호출하면
아무 작업도 수행하지 않고 경고만 로깅합니다. 일괄 수집 시에는 객체에 선언된 필드를
직접 채운 다음 `log_turn` / `log_conversation`에 전달하세요.