> ## 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

> La classe Turn enregistre un échange entre l’utilisateur et l’agent sous la forme d’un span invoke_agent.

```python theme={"system"}
class Turn(BaseModel): ...
```

Un échange entre l’utilisateur et l’agent. Correspond à un span OTel invoke\_agent.

Par défaut, chaque tour de conversation démarre sa propre trace OTel (`continue_parent_trace=False`)
afin que l’onglet Conversations affiche une trace par tour de conversation. Définissez `continue_parent_trace=True`
sur la Conversation (ou directement sur le Turn) lorsqu’une trace externe est déjà
active et que vous souhaitez y imbriquer l’appel d’agent, par exemple dans
une requête instrumentée par fastapi.

`Turn` est un modèle Pydantic. Vous pouvez définir chacun des champs ci-dessous comme argument nommé lors de sa construction.

`Turn` est un gestionnaire de contexte et peut être utilisé dans une instruction `with`.

<h2 id="fields">
  Champs
</h2>

| Champ | Type | Par défaut |
| - | - | - |
| `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` |

<h2 id="methods">
  Méthodes
</h2>

<h3 id="user">
  user
</h3>

```python theme={"system"}
def user(content: str) -> Turn: ...
```

Ajoute un message utilisateur au cours d’un tour de conversation.

<h3 id="start_llm">
  start\_llm
</h3>

```python theme={"system"}
def start_llm(
    *,
    model: str = '',
    provider_name: str = '',
    system_instructions: Union[list[str], None] = None,
) -> LLM: ...
```

Démarre un appel LLM (span de chat, enfant de ce tour de conversation).

Définit la contextvar `_current_llm` afin que le LLM soit accessible via
`get_current_llm()`, qu’un gestionnaire de contexte soit utilisé ou non.

<h3 id="start_tool">
  start\_tool
</h3>

```python theme={"system"}
def start_tool(*, name: str, arguments: str = '', tool_call_id: str = '') -> Tool: ...
```

Démarre l’exécution d’un outil (span execute\_tool, enfant de ce tour de conversation).

<h3 id="start_subagent">
  start\_subagent
</h3>

```python theme={"system"}
def start_subagent(
    *,
    name: str,
    model: str = '',
    system_instructions: Union[list[str], None] = None,
    set_current: bool = True,
) -> SubAgent: ...
```

Démarre un appel de sous-agent (span invoke\_agent imbriqué, dans la même trace).

<h3 id="record">
  record
</h3>

```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: ...
```

Définit plusieurs champs du tour de conversation en un seul appel.

Regroupe en un seul appel à arguments nommés les affectations champ par champ qu'un agent instrumenté manuellement
devrait sinon effectuer sur un tour de conversation (`system_instructions`, `agent_id`,
...). Seuls les champs explicitement transmis
(différents de `None`) sont appliqués ; les valeurs existantes sont conservées.
`messages` et `output_messages` remplacent, indépendamment l'un de l'autre, les messages
d'entrée et de sortie existants du tour de conversation. Contrairement à
`Turn.user(...)`, qui ajoute un seul message d'entrée. Renvoie
`self` pour permettre le chaînage. Reprend le fonctionnement de `LLM.record`.

Remarque : sur le chemin de streaming (`with`), le span du tour de conversation est nommé d'après
`agent_name` lors de `__enter__`. Si le nom du span doit refléter cette valeur, définissez donc `agent_name` via
`start_turn` plutôt que via `record` ; `record` met tout de même à jour l'attribut
`gen_ai.agent.name`.

<h3 id="end">
  end
</h3>

```python theme={"system"}
def end() -> None: ...
```

<h3 id="start">
  start
</h3>

```python theme={"system"}
def start() -> Self: ...
```

Démarre ce span une seule fois ; l’entrée dans le gestionnaire de contexte emprunte le même chemin.

<h3 id="record_error">
  record\_error
</h3>

```python theme={"system"}
def record_error(error: BaseException) -> Self: ...
```

Enregistre un échec sans terminer le span ; appelez `end()` le moment venu.

<h3 id="set_attributes">
  set\_attributes
</h3>

```python theme={"system"}
def set_attributes(attributes: dict[str, Any]) -> Self: ...
```

Ajoute des attributs OTel arbitraires à ce span.

Passez un dict, que vous ayez une seule clé ou plusieurs ; pour une seule clé,
utilisez `span.set_attributes({"weave.tag": "value"})`. Équivalent de la méthode
`Span.set_attributes` d'OTel.

Doit être appelée après le démarrage du span par une fabrique `start_*`, par `start()` ou par `with`,
et avant sa fin. En dehors de cet intervalle, l’appel n’a aucun effet (no-op) et
journalise un avertissement. Pour l’ingestion par lots, renseignez directement les champs déclarés de l’objet
et passez-le à `log_turn` / `log_conversation`.