> ## 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(Turn, LLM, Tool, SubAgent)에 맞춤형 속성을 attach하고 이벤트를 기록하여 Weave에서 에이전트 활동을 필터링하고 분석하세요.

export const AgentLensBanner = ({href}) => <Tip>
    <strong>This workflow is also available in CoreWeave Agent Lens.</strong> Agent Lens is the Forge experience built for tracing, monitoring, and analyzing AI agents, with automated insights into agent failures and user intents. It uses the same trace data as Weights & Biases Weave, so the traces you already send appear there with nothing to migrate.{' '}
    <a href={href || '/products/agent-lens'}>{href ? 'See how to do this in Agent Lens' : 'Learn about Agent Lens'}</a>.
  </Tip>;

<AgentLensBanner href="/ko/products/agent-lens/tracing/attributes-and-events" />

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](https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-spans/)를 반영합니다: `set_attributes`는 OTel의 `Span.set_attributes`를, `add_event`는 OTel의 `Span.add_event`를 반영합니다. Weave SDK는 OTel spans를 내보내고 모든 속성을 저장하므로 Weave에서 쿼리할 수 있습니다.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

span이 기록 중일 때, 즉 span이 시작된 후 종료되기 전에 속성을 설정하세요. Python에서는 `with` 블록 내부입니다. TypeScript에서는 `start*()` 이후 `end()` 이전입니다.

아직 시작되지 않았거나 이미 종료된 span에서 `set_attributes()` 또는 TypeScript의 해당 메서드를 호출하면, 호출은 no-op이며 수정 방법을 알려주는 경고를 로깅합니다.

OTel이 설치되지 않았거나 Weave가 비활성화된 경우에만 호출이 조용히(경고 없이) 처리됩니다.

<Tip>
  라이브 실행이 아닌 단일 배치로 완료된 에이전트 활동을 로깅할 때 속성을 첨부하려면, span 객체에 선언된 필드를 직접 채우고 객체를 `log_turn` 또는 `log_conversation`에 전달하세요. [배치로 에이전트 활동 로깅](/ko/products/wandb/weave/guides/tracking/trace-agents-batch) 참조.
</Tip>

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

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