에이전트 span에 속성 설정하기

CoreWeave Forge SDK로 에이전트를 계측하면 각 span 객체(Turn, LLM, Tool, SubAgent)에 맞춤형 메타데이터를 속성으로 추가할 수 있습니다. 속성은 span에 연결된 키-값 형식의 정보입니다. 속성을 사용하여 사용자 ID, 테넌트, 실험 이름, 환경 레이블 등의 컨텍스트 정보를 에이전트 span에 기록하면, CoreWeave Agent Lens UI에서 이 메타데이터를 기준으로 에이전트 활동을 필터링하고 그룹화할 수 있습니다. set_attributes()(Python) 또는 setAttributes()(TypeScript)를 사용하여 개별 span에 속성을 설정하거나, 대화에서 생성되는 모든 span에 적용되는 대화 수준 속성을 설정할 수 있습니다. set_attributes는 OpenTelemetry(OTel) span API의 Span.set_attributes 메서드와 동일한 방식으로 동작합니다. Agent Lens SDK는 OTel span을 생성하고 모든 속성을 저장하므로, 이 속성은 Agent Lens에서 언제든 쿼리할 수 있습니다. 이 페이지의 예시는 에이전트 트레이스하기의 설명에 따라 SDK를 설치하고 초기화했다고 가정합니다.

span에 속성 설정하기

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

Python
TypeScript

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

with tracing.start_conversation(agent_name="my-agent"):
    with tracing.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 { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({ agentName: 'my-agent' });
  const turn = tracing.startTurn({ userMessage: 'What is the weather in Tokyo?' });

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

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

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

Python
TypeScript

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

const turn = tracing.startTurn({ userMessage: 'What is the weather in Tokyo?' });
const tool = turn.startTool({ name: 'get_weather' });

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

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

대부분의 속성 키는 임의의 맞춤형 메타데이터이지만, Agent Lens는 두 가지 접두사를 예약하여 특별하게 처리합니다. weave.* 키는 Agent Lens 기본 제공 필드에 매핑되고, gen_ai.* 키는 OpenTelemetry GenAI 시맨틱 규칙 필드에 매핑됩니다. 앞의 예시에서 weave.display_name은 Agent Lens UI에 표시되는 span의 표시 이름을 설정하는 예약 키입니다. 필터링하거나 그룹화할 임의의 메타데이터에는 user_id나 tenant처럼 직접 정의한 키를 사용하세요. Agent Lens는 이러한 키를 필터링 가능한 맞춤형 속성으로 저장합니다.

span 실행 중 발생한 일 기록하기

속성을 사용하면 권한 프롬프트나 그 결과처럼 span이 실행되는 동안 발생한 일도 기록할 수 있습니다. 해당 일이 발생한 시점, 즉 span이 아직 기록 중일 때 속성을 설정하세요.

Python
TypeScript

with tracing.start_turn(user_message="Delete the old backups.") as turn:
    turn.set_attributes({"permission.scope": "filesystem.delete"})
    # ... 사용자에게 묻고 응답을 기다립니다 ...
    turn.set_attributes({"permission.granted": True})

const turn = tracing.startTurn({ userMessage: 'Delete the old backups.' });
turn.setAttributes({ 'permission.scope': 'filesystem.delete' });
// ... 사용자에게 묻고 응답을 기다립니다 ...
turn.setAttributes({ 'permission.granted': true });
turn.end();

속성은 값만 기록하며, 값이 설정된 시각은 기록하지 않습니다. span 내에서 어떤 일이 언제 발생했는지 알아야 한다면 permission.granted_at처럼 시각을 별도의 속성으로 기록하세요.

OpenTelemetry가 Span Event API를 사용 중단함에 따라 SDK의 add_event()(Python) 및 addEvent()(TypeScript) 메서드도 사용 중단되었습니다. 이 데이터는 속성으로 기록하세요.

대화의 모든 span에 속성 설정하기

span마다 속성을 하나씩 지정하는 방식은 span별 메타데이터에 적합하지만, 대화 전체에 적용되는 메타데이터도 있습니다. 대화에서 생성되는 모든 span에 동일한 속성을 적용하려면 대화를 시작할 때 attributes를 전달하세요. 배포 이름이나 환경처럼 대화 전체에 해당하는 메타데이터를 전파할 때 유용합니다.

Python
TypeScript

from coreweave.forge.agentlens import tracing

tracing.init("[YOUR-TEAM]/[YOUR-PROJECT]")

conversation = tracing.start_conversation(
    agent_name="my-agent",
    attributes={"deployment": "canary", "env": "production"},
)
# 이 대화의 모든 turn, LLM, 도구, 하위 에이전트 span에 이 속성이 포함됩니다.

import { tracing } from '@coreweave/forge-sdk/agentlens';

await tracing.init('[YOUR-TEAM]/[YOUR-PROJECT]');

await tracing.runIsolated(async () => {
  const conversation = tracing.startConversation({
    agentName: 'my-agent',
    attributes: { deployment: 'canary', env: 'production' },
  });
  // 이 대화의 모든 turn, LLM, 도구, 하위 에이전트 span에 이 속성이 포함됩니다.
});

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

속성을 설정할 수 있는 시점

속성은 span이 기록 중일 때, 즉 span이 시작된 후 종료되기 전에 설정하세요. Python에서는 with 블록 내부가, TypeScript에서는 start*() 호출 이후부터 end() 호출 이전까지가 이에 해당합니다. 아직 시작되지 않았거나 이미 종료된 span에서 set_attributes() 또는 이에 대응하는 TypeScript 메서드를 호출하면 아무 작업도 수행되지 않으며, 해결 방법을 알려 주는 경고가 로깅됩니다. 경고 없이 호출이 무시되는 경우는 트레이싱이 초기화되지 않았을 때뿐입니다.

실행 도중이 아니라 완료된 에이전트 활동을 한 번에 일괄 로깅하면서 속성을 연결하려면, span 객체에 선언된 필드를 직접 채운 다음 해당 객체를 log_turn 또는 log_conversation에 전달하세요. 자세한 내용은 에이전트 활동을 일괄 로깅하기를 참조하세요.

UI에서 속성 보기 및 필터링

속성 추가는 첫 단계에 불과합니다. 속성의 진정한 가치는 이를 활용해 에이전트 활동을 분석할 때 드러납니다. 에이전트 span에 속성을 기록하고 나면 Agent Lens 프로젝트의 Conversations 탭에서 해당 속성을 기준으로 에이전트 대화를 필터링하고 그룹화할 수 있습니다. 자세한 내용은 에이전트 활동 보기를 참조하세요.

​span에 속성 설정하기

​span 실행 중 발생한 일 기록하기

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

​속성을 설정할 수 있는 시점

​UI에서 속성 보기 및 필터링

span에 속성 설정하기

span 실행 중 발생한 일 기록하기

대화의 모든 span에 속성 설정하기

속성을 설정할 수 있는 시점

UI에서 속성 보기 및 필터링