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

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

> 에이전트 span에 맞춤형 속성을 추가하여 Agent Lens에서 활동을 필터링하고 분석하세요.

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](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)의 `Span.set_attributes` 메서드와 동일한 방식으로 동작합니다. Agent Lens SDK는 OTel span을 생성하고 모든 속성을 저장하므로, 이 속성은 Agent Lens에서 언제든 쿼리할 수 있습니다.

이 페이지의 예시는 [에이전트 트레이스하기](/ko/products/agent-lens/tracing/instrument#before-you-begin)의 설명에 따라 SDK를 설치하고 초기화했다고 가정합니다.

<h2 id="set-attributes-on-a-span">
  span에 속성 설정하기
</h2>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines theme={"system"}
    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();
    });
    ```
  </Tab>
</Tabs>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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"})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines theme={"system"}
    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();
    ```
  </Tab>
</Tabs>

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

<h2 id="record-what-happens-during-a-span">
  span 실행 중 발생한 일 기록하기
</h2>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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})
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines theme={"system"}
    const turn = tracing.startTurn({ userMessage: 'Delete the old backups.' });
    turn.setAttributes({ 'permission.scope': 'filesystem.delete' });
    // ... 사용자에게 묻고 응답을 기다립니다 ...
    turn.setAttributes({ 'permission.granted': true });
    turn.end();
    ```
  </Tab>
</Tabs>

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

<Note>
  OpenTelemetry가 [Span Event API를 사용 중단](https://opentelemetry.io/blog/2026/deprecating-span-events/)함에 따라 SDK의 `add_event()`(Python) 및 `addEvent()`(TypeScript) 메서드도 사용 중단되었습니다. 이 데이터는 속성으로 기록하세요.
</Note>

<h2 id="set-attributes-on-every-span-in-a-conversation">
  대화의 모든 span에 속성 설정하기
</h2>

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

<Tabs>
  <Tab title="Python">
    ```python lines theme={"system"}
    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에 이 속성이 포함됩니다.
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript lines theme={"system"}
    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에 이 속성이 포함됩니다.
    });
    ```
  </Tab>
</Tabs>

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

<h2 id="when-you-can-set-attributes">
  속성을 설정할 수 있는 시점
</h2>

속성은 span이 기록 중일 때, 즉 span이 시작된 후 종료되기 전에 설정하세요. Python에서는 `with` 블록 내부가, TypeScript에서는 `start*()` 호출 이후부터 `end()` 호출 이전까지가 이에 해당합니다.

아직 시작되지 않았거나 이미 종료된 span에서 `set_attributes()` 또는 이에 대응하는 TypeScript 메서드를 호출하면 아무 작업도 수행되지 않으며, 해결 방법을 알려 주는 경고가 로깅됩니다.

경고 없이 호출이 무시되는 경우는 트레이싱이 초기화되지 않았을 때뿐입니다.

<Tip>
  실행 도중이 아니라 완료된 에이전트 활동을 한 번에 일괄 로깅하면서 속성을 연결하려면, span 객체에 선언된 필드를 직접 채운 다음 해당 객체를 `log_turn` 또는 `log_conversation`에 전달하세요. 자세한 내용은 [에이전트 활동을 일괄 로깅하기](/ko/products/agent-lens/tracing/batch-logging)를 참조하세요.
</Tip>

<h2 id="view-and-filter-attributes-in-the-ui">
  UI에서 속성 보기 및 필터링
</h2>

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