> ## 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 클래스는 위임된 에이전트 호출을 중첩된 invoke_agent span으로 기록합니다.

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

턴 내에서 위임된 에이전트 호출입니다.

동일한 트레이스 안에 중첩된 invoke\_agent OTel span에 매핑됩니다.

`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을 시작합니다.

컨텍스트 관리자 사용 여부와 관계없이 `get_current_llm()`으로 LLM을 조회할 수 있도록
`_current_llm` contextvar를 설정합니다.
SubAgent에 진입한 경우, LLM의 OTel 부모를 이 SubAgent의 span으로
고정합니다.

<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의 span으로
고정합니다.

<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의 span으로
고정합니다.

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

여러 하위 에이전트 필드를 한 번의 호출로 설정합니다.

수동으로 계측한 에이전트에서 하위 에이전트에 필드별로 하나씩 수행해야 하는
할당(`system_instructions`, `agent_id`,
...)을 단일 키워드 호출로 통합합니다. 명시적으로 전달된
(`None`이 아닌) 필드만 적용되며, 기존 값은 그대로 유지됩니다. 메서드 체이닝을 위해
`self`를 반환합니다. `Turn.record` / `LLM.record`와 같은 방식으로 동작합니다.

참고: 스트리밍(`with`) 경로에서는 `__enter__` 시점의 `name`으로 하위 에이전트 span의
이름이 지정됩니다. 따라서 span 이름에 `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: ...
```

이 하위 에이전트의 span을 시작합니다. `with` 없이 `__enter__`를 호출하는 것과 같습니다.

하위 에이전트가 동시에 실행될 수 있는 경우에는 `start_subagent`에 `set_current=False`를 전달하세요.
`end()`는 `ContextVar.reset`을 통해 분리(detach)를 수행하므로, 서로 겹치는 span이
LIFO 순서와 다르게 종료되면 주변 컨텍스트 스택이 오류 없이 손상됩니다. 이렇게 되면 남아 있는
형제 span이 더 이상 현재 span으로 유지되지 않고, 마지막 분리 작업에서는 이미 종료된 span이 복원됩니다.
`start_llm` / `start_tool` / `start_subagent`로 생성한 자식 span은
어느 경우든 이 span 아래에 중첩됩니다. 이 팩토리들은 부모 컨텍스트를
명시적으로 전달하기 때문입니다.

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

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

span을 종료하지 않고 실패를 기록합니다. 종료할 준비가 되면 `end()`를 호출하세요.

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

```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`에 전달하세요.