작업 기록하기

작업 기록하기 (Recording Operations)

데코레이터를 사용해 코드를 계측(instrument)해서 작업(operations)·태스크·워크플로우를 추적하는 방법을 설명하는 문서예요. @operation, @workflow, @agent, @session 데코레이터의 사용법을 함께 살펴볼게요.

출처: 문서

본문

AgentOps를 최대한 활용하려면 작업을 추적하도록 코드를 적절히 계측(instrument)하는 것이 중요해요. AgentOps는 이를 쉽게 만들어 주는 데코레이터 세트를 제공해요.

데코레이터로 계측하기 (Using Decorators for Instrumentation)

AgentOps는 코드를 쉽게 계측할 수 있게 해주는 여러 데코레이터를 제공해요.

`@operation` / `@task` 데코레이터

@operation과 @task 데코레이터는 별칭(alias)으로, 특정 작업을 추적하기 위한 operation/task span을 만들어요.

from agentops.sdk.decorators import operation

@operation
def process_data(data):
    # 데이터 처리
    return result

이 데코레이터들은 파라미터와 함께 사용할 수도 있어요:

@operation(name="custom-operation-name", version=1)
def process_data(data):
    # 데이터 처리
    return result

에이전트 클래스 안에서 사용하면 작업(operations)은 에이전트 아래에 자동으로 중첩(nested)돼요:

from agentops.sdk.decorators import agent, operation

@agent
class MyAgent:
    @operation
    def perform_task(self, task):
        # 작업 구현
        return result

`@workflow` 데코레이터

@workflow 데코레이터는 여러 작업을 포함할 수 있는 워크플로우를 추적하기 위한 workflow span을 만들어요.

from agentops.sdk.decorators import workflow

@workflow
def my_workflow(data):
    # 워크플로우 구현
    return result

`@agent` 데코레이터

@agent 데코레이터는 에이전트 작업을 추적하기 위한 agent span을 만들어요.

from agentops.sdk.decorators import agent

@agent
class MyAgent:
    def __init__(self, name):
        self.name = name
        
    # 에이전트 메서드 작성

`@session` 데코레이터

@session 데코레이터는 다른 모든 span의 루트(root) 역할을 하는 session span을 만들어요.

from agentops.sdk.decorators import session

@session
def my_workflow():
    # 세션 코드 작성
    return result

자동 계측 (Automatic Instrumentation)

AgentOps는 인기 있는 LLM 프로바이더(OpenAI, Anthropic 등)에 대한 호출을 자동으로 계측해요. 이러한 호출은 자동으로 LLM span으로 추적되고, 에이전트와 operation span 안에 올바르게 중첩돼요.

모범 사례 (Best Practices)

올바른 데코레이터 사용하기 (Use the Right Decorator): 무엇을 계측하는지에 따라 적절한 데코레이터를 선택하세요:
- 애플리케이션의 루트에는 @session
- 에이전트 클래스에는 @agent
- 특정 작업에는 @operation
- 작업 시퀀스에는 @workflow
올바른 중첩 (Proper Nesting): span이 올바르게 중첩되도록 하세요:
- session span은 맨 위에 있어야 해요
- agent span은 session span의 자식이어야 해요
- operation span은 agent span의 자식이어야 해요
의미 있는 이름 (Meaningful Names): span에 의미 있는 이름을 사용해서 대시보드에서 식별하기 쉽게 하세요.
중요한 데이터 기록하기 (Record Important Data): 데코레이터는 함수 파라미터와 반환 값을 자동으로 기록하지만, 추가 컨텍스트를 위해 span에 커스텀 속성을 추가할 수도 있어요.

작업 기록하기