SubAgent - CoreWeave Docs

class SubAgent(BaseModel): ...

턴 내에서 위임된 에이전트 호출입니다. 동일한 트레이스 안에 중첩된 invoke_agent OTel span에 매핑됩니다. SubAgent는 Pydantic 모델입니다. 생성할 때 아래 필드를 키워드 인수로 설정할 수 있습니다. SubAgent는 컨텍스트 관리자이므로 with 문에서 사용할 수 있습니다.

필드

필드	유형	기본값
`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`

메서드

start_llm

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

start_tool

def start_tool(*, name: str, arguments: str = '', tool_call_id: str = '') -> Tool: ...

이 하위 에이전트 내에서 도구 실행을 시작합니다. SubAgent에 진입한 상태이면 Tool의 OTel 부모를 이 SubAgent의 span으로 고정합니다.

start_subagent

def start_subagent(
    *,
    name: str,
    model: str = '',
    set_current: bool = True,
) -> SubAgent: ...

이 하위 에이전트 아래에 중첩된 하위 에이전트를 시작합니다. 이 SubAgent에 진입한 상태이면 중첩된 SubAgent의 OTel 부모를 이 SubAgent의 span으로 고정합니다.

record

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 속성을 업데이트합니다.

end

def end() -> None: ...

start

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 아래에 중첩됩니다. 이 팩토리들은 부모 컨텍스트를 명시적으로 전달하기 때문입니다.

record_error

def record_error(error: BaseException) -> Self: ...

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

set_attributes

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

​필드

​메서드

​start_llm

​start_tool

​start_subagent

​record

​end

​start

​record_error

​set_attributes

필드

메서드