> ## 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 クラスは、ユーザーとエージェント間の 1 回のやり取りを invoke_agent スパンとして記録します。
```python theme={"system"}
class Turn(BaseModel): ...
```
ユーザーとエージェント間の 1 回のやり取りです。invoke\_agent OTel スパンに対応します。
デフォルトでは、各ターンがそれぞれ独自の OTel トレースを開始するため (`continue_parent_trace=False`) 、
Conversations タブにはターンごとに 1 つのトレースが表示されます。外側のトレースがすでに
アクティブな状態で、エージェントの invocation をその中にネストしたい場合は、Conversation (または Turn に直接) で
`continue_parent_trace=True` を設定します。たとえば、fastapi でインストルメントされた
リクエスト内で実行する場合などが該当します。
`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(チャットスパン。このターンの子)を開始します。
`_current_llm` contextvar を設定します。これにより、コンテキストマネージャーを使用するかどうかにかかわらず、
`get_current_llm()` から LLM を参照できます。
```python theme={"system"}
def start_tool(*, name: str, arguments: str = '', tool_call_id: str = '') -> Tool: ...
```
ツール実行を開始します (このターンの子となる execute\_tool スパン) 。
start\_subagent
```python theme={"system"}
def start_subagent(
*,
name: str,
model: str = '',
system_instructions: Union[list[str], None] = None,
set_current: bool = True,
) -> SubAgent: ...
```
sub-agent の invocation を開始します (同じトレース内のネストされた invoke\_agent スパン) 。
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: ...
```
複数のターンフィールドを 1 回の呼び出しでまとめて設定します。
手動でインストルメントされたエージェントがターンに対してフィールドごとに行う代入 (`system_instructions`、`agent_id`、
...) を、1 回のキーワード引数呼び出しにまとめます。明示的に渡された
(`None` 以外の) フィールドのみが適用され、既存の値は保持されます。
`messages` と `output_messages` は、それぞれ独立してターンの
既存の入力メッセージと出力メッセージを置き換えます。この点で、入力メッセージを 1 件追加する
`Turn.user(...)` とは異なります。メソッドチェーン用に
`self` を返します。`LLM.record` に対応するメソッドです。
注: ストリーミング (`with`) パスでは、ターンのスパン名は `__enter__` 時点の
`agent_name` に基づいて決まります。そのため、スパン名に反映させたい場合は、`agent_name` を
`record` ではなく `start_turn` で設定してください。なお、`record` でも `gen_ai.agent.name`
属性は更新されます。
end
```python theme={"system"}
def end() -> None: ...
```
start
```python theme={"system"}
def start() -> Self: ...
```
このスパンを一度だけ開始します。コンテキストマネージャーとして開始 (エントリ) する場合も、同じパスが使用されます。
record\_error
```python theme={"system"}
def record_error(error: BaseException) -> Self: ...
```
スパンを終了せずにエラーを記録します。スパンを終了する準備ができたら `end()` を呼び出します。
set\_attributes
```python theme={"system"}
def set_attributes(attributes: dict[str, Any]) -> Self: ...
```
このスパンに任意の OTel 属性を設定します。
キーが 1 つでも複数でも dict を渡します。キーが 1 つの場合は
`span.set_attributes({"weave.tag": "value"})` のように呼び出します。OTel の
`Span.set_attributes` と同じ仕様です。
`start_*` ファクトリ、`start()`、または `with` によってスパンが開始された後、
スパンが終了する前に呼び出す必要があります。この期間外に呼び出した場合は
no-op となり、警告がログに記録されます。バッチ取り込みの場合は、オブジェクトの宣言済みフィールドに直接値を設定し、
`log_turn` / `log_conversation` に渡してください。