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

# SubAgent

> SubAgent クラスは、委譲されたエージェントの invocation を、ネストされた invoke_agent スパンとして記録します。

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

ターン内で委譲されたエージェントの invocation です。

同じトレース内のネストされた invoke\_agent OTel スパンに対応します。

`SubAgent` は Pydantic モデルです。インスタンスを作成する際に、以下の任意のフィールドをキーワード引数として指定できます。

`SubAgent` はコンテキストマネージャーであり、`with` 文で使用できます。

<h2 id="fields">
  フィールド
</h2>

| フィールド | タイプ | デフォルト |
| - | - | - |
| `name` | `str` | `''` |
| `model` | `str` | `''` |
| `agent_id` | `str` | `''` |
| `agent_description` | `str` | `''` |
| `agent_version` | `str` | `''` |
| `system_instructions` | `list[str]` | `[]` |
| `input_messages` | `list[Message]` | `[]` |
| `output_messages` | `list[Message]` | `[]` |
| `tool_name` | `str` | `''` |
| `tool_call_id` | `str` | `''` |
| `tool_call_arguments` | `JSONString` | `''` |
| `tool_call_result` | `JSONString` | `''` |
| `started_at` | `Union[datetime, None]` | `None` |
| `ended_at` | `Union[datetime, None]` | `None` |

<h2 id="methods">
  メソッド
</h2>

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

このサブエージェント内で LLM Call を開始します。

`_current_llm` contextvar を設定するため、コンテキストマネージャーを使用するかどうかにかかわらず、
`get_current_llm()` から LLM を参照できます。
SubAgent のコンテキストに入っている場合は、LLM の OTel 親をこの SubAgent のスパンに固定します。

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

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

このサブエージェント内でツール実行を開始します。

SubAgent に入っている場合は、Tool の OTel 親をこの SubAgent のスパンに固定します。

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

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

このサブエージェントの配下に、ネストされたサブエージェントを開始します。

この SubAgent がエンターされている場合、ネストされた SubAgent の OTel 親をこの SubAgent のスパンに固定します。

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

```python theme={"system"}
def record(
    *,
    name: Union[str, None] = None,
    model: Union[str, None] = None,
    system_instructions: Union[list[str], None] = None,
    input_messages: Union[list[Message], None] = None,
    output_messages: Union[list[Message], None] = None,
    tool_name: Union[str, None] = None,
    tool_call_id: Union[str, None] = None,
    tool_call_arguments: Union[str, None] = None,
    tool_call_result: Union[str, None] = None,
    agent_id: Union[str, None] = None,
    agent_description: Union[str, None] = None,
    agent_version: Union[str, None] = None,
) -> SubAgent: ...
```

複数のサブエージェントフィールドを 1 回の呼び出しで設定します。

手動でインストルメントされたエージェントでは、サブエージェントに対してフィールドごとに代入 (`system_instructions`、`agent_id`、
...) を行う必要がありますが、このメソッドはそれらを 1 回のキーワード引数による呼び出しにまとめます。明示的に渡された
(`None` 以外の) フィールドのみが適用され、既存の値は保持されます。メソッドチェーン用に
`self` を返します。`Turn.record` / `LLM.record` と同様の動作です。

注: ストリーミング (`with`) パスでは、サブエージェントのスパン名は `__enter__` の時点で
`name` から決定されます。そのため、スパン名に反映させたい場合は、`record` ではなく `start_subagent`
/ `turn.subagent` で `name` を設定してください。なお、`record` を使用した場合でも `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(*, set_current: bool = True) -> Self: ...
```

このサブエージェントのスパンを開始します。`with` を使わずに `__enter__` を呼び出すのと同じです。

サブエージェントが並行して実行される可能性がある場合は、`start_subagent` に `set_current=False` を渡してください。`end()` は `ContextVar.reset` を使ってデタッチするため、
重なり合うスパンが LIFO の順序どおりに終了しないと、アンビエントなコンテキストスタックが
警告なしに破損します。その結果、残った兄弟スパンがカレントではなくなり、
最後のデタッチでは、すでに終了したスパンが復元されてしまいます。
`start_llm` / `start_tool` / `start_subagent` で作成した子スパンは、
いずれの場合もこのスパンの下にネストされます。これらのファクトリーが
明示的な親コンテキストを引き渡すためです。

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

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

スパンを終了せずにエラーを記録します。スパンを終了する準備ができたら `end()` を呼び出します。

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

```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` に渡してください。