에이전트 span에 속성과 이벤트 설정

Weave SDK로 에이전트를 instrument할 때, 각 span 객체(Turn, LLM, Tool, SubAgent)는 맞춤형 메타데이터를 attach하는 메서드를 제공합니다. 이러한 메서드를 사용해 사용자 ID, 테넌트, experiment name 또는 environment 레이블과 같은 컨텍스트 정보를 에이전트 span에 설정한 다음, Weights & Biases UI에서 해당 메타데이터로 agent 활동을 filter하고 group할 수 있습니다. 이 메타데이터는 두 가지 형태로 제공됩니다:

Attributes: span 전체의 키-값 속성입니다. set_attributes() (Python) 또는 setAttributes() (TypeScript)를 사용하여 단일 span에 속성을 설정하거나, 대화에서 내보내는 모든 span에 적용되는 대화 전체 속성을 설정하세요.
Events: span의 lifetime 동안 발생하는 시점 마커로, 예를 들어 권한 프롬프트나 라이프사이클 전환과 같은 것입니다. add_event() (Python) 또는 addEvent() (TypeScript)를 사용하세요.

이 메서드는 OpenTelemetry (OTel) span API를 반영합니다: set_attributes는 OTel의 Span.set_attributes를, add_event는 OTel의 Span.add_event를 반영합니다. Weave SDK는 OTel spans를 내보내고 모든 속성을 저장하므로 Weave에서 쿼리할 수 있습니다.

span에 속성 설정

set_attributes() (Python) 또는 setAttributes() (TypeScript)를 사용하여 단일 span에 임의의 속성을 설정하세요. 키가 하나이든 여러 개이든 딕셔너리나 객체를 전달하세요. 이 메서드는 span을 반환하므로 호출을 체인할 수 있습니다.

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

with weave.start_conversation(agent_name="my-agent"):
    with weave.start_turn(user_message="What is the weather in Tokyo?") as turn:
        # 이 turn span에 속성 설정
        turn.set_attributes({"user_id": "12345", "tenant": "acme", "env": "production"})

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const conversation = weave.startConversation({ agentName: 'my-agent' });
const turn = weave.startTurn({ agentName: 'my-agent' });

// 이 turn span에 속성 설정
turn.setAttributes({ user_id: '12345', tenant: 'acme', env: 'production' });

turn.end();
conversation.end();

동일한 메서드는 모든 span 클래스에서 사용할 수 있습니다. 예를 들어 개별 도구 Call이나 LLM Call에 태그를 지정할 수 있습니다:

Python
TypeScript

with weave.start_turn(user_message="What is the weather in Tokyo?") as turn:
    with turn.tool(name="get_weather") as tool:
        tool.set_attributes({"weave.display_name": "Weather lookup"})

const turn = weave.startTurn({ agentName: 'my-agent' });
const tool = turn.startTool({ name: 'get_weather' });

tool.setAttributes({ 'weave.display_name': 'Weather lookup' });

tool.end();
turn.end();

대부분의 속성 키는 맞춤형 메타데이터이지만 Weave는 특수 처리를 위해 두 개의 접두사를 예약합니다. weave.* 아래의 키는 내장 Weave 필드에 매핑되고, gen_ai.* 아래의 키는 OpenTelemetry GenAI 의미 규칙 필드에 매핑됩니다. 앞의 예시에서 weave.display_name은 Agents 및 Traces UI에서 span의 표시 이름을 설정하는 예약 키입니다. 필터링하고 그룹화할 수 있는 임의의 메타데이터의 경우 user_id 또는 tenant와 같은 자체 키를 사용하세요. Weave는 이를 필터링 가능한 맞춤형 속성으로 저장합니다.

대화의 모든 span에 속성 설정

속성을 span 하나씩 설정하는 것은 span별 메타데이터에 잘 맞지만, 일부 메타데이터는 전체 대화에 적용됩니다. 대화가 내보내는 모든 span에 동일한 속성을 적용하려면 대화를 시작할 때 attributes를 전달하세요. 이는 인테그레이션 ID나 배포 환경과 같은 대화 전체 메타데이터를 전파하는 데 유용합니다.

Python
TypeScript

import weave

weave.init("[TEAM-NAME]/[PROJECT-NAME]")

conversation = weave.start_conversation(
    agent_name="my-agent",
    attributes={"weave.integration.name": "my-harness", "env": "production"},
)
# 이 세션의 모든 turn, LLM, 도구, 하위 에이전트 span에 이러한 속성이 포함됩니다.

import * as weave from 'weave';

await weave.init('[TEAM-NAME]/[PROJECT-NAME]');

const conversation = weave.startConversation({
  agentName: 'my-agent',
  attributes: { 'weave.integration.name': 'my-harness', env: 'production' },
});
// 이 대화의 모든 turn, LLM, 도구, 하위 에이전트 span에 이러한 속성이 포함됩니다.

span별 속성과 마찬가지로, 대화 속성에는 직접 정의한 맞춤형 키를 사용하세요. 에이전트 이름, 대화 이름, 모델과 같은 시맨틱 규칙 필드는 attributes가 아닌 유형 지정 매개변수(agent_name, conversation_name, model)를 통해 설정하세요. 예약된 gen_ai.* 및 weave.* 접두사로 시작하는 키는 사용하지 마세요. Weave는 수집 과정에서 이러한 키를 유형 지정 필드로 추출하므로, 예약된 키에 맞춤형 값을 지정하는 것은 지원되지 않습니다.

속성을 설정할 수 있는 경우

span이 기록 중일 때, 즉 span이 시작된 후 종료되기 전에 속성을 설정하세요. Python에서는 with 블록 내부입니다. TypeScript에서는 start*() 이후 end() 이전입니다. 아직 시작되지 않았거나 이미 종료된 span에서 set_attributes() 또는 TypeScript의 해당 메서드를 호출하면, 호출은 no-op이며 수정 방법을 알려주는 경고를 로깅합니다. OTel이 설치되지 않았거나 Weave가 비활성화된 경우에만 호출이 조용히(경고 없이) 처리됩니다.

라이브 실행이 아닌 단일 배치로 완료된 에이전트 활동을 로깅할 때 속성을 첨부하려면, span 객체에 선언된 필드를 직접 채우고 객체를 log_turn 또는 log_conversation에 전달하세요. 배치로 에이전트 활동 로깅 참조.

UI에서 속성 뷰 및 필터링

속성 추가는 첫 단계일 뿐입니다. 그 가치는 에이전트 활동을 분석하는 데 사용되는 데서 옵니다. 에이전트 span에 속성을 설정한 후, Weave 프로젝트의 Agents 탭에서 해당 속성으로 에이전트 대화를 필터링하고 그룹화할 수 있습니다. 자세한 내용은 에이전트 활동 뷰를 참조하세요.

​span에 속성 설정

​대화의 모든 span에 속성 설정

​속성을 설정할 수 있는 경우

​UI에서 속성 뷰 및 필터링

span에 속성 설정

대화의 모든 span에 속성 설정

속성을 설정할 수 있는 경우

UI에서 속성 뷰 및 필터링