데코레이터

데코레이터 (Decorators)

함수와 클래스에 붙이기만 하면 손쉽게 계측(instrumenting)할 수 있게 해주는, 마법 같은 도구라고 보시면 돼요. AgentOps가 제공하는 데코레이터들을 함께 알아볼게요.

출처: 문서

본문

데코레이터는 그 위에 놓인 함수나 클래스를 감싸서(wrap) 동작해요. 아마 여러분도 이미 본 적이 있을 거예요. 데코레이터를 사용하면 여러분이 하는 작업은 아주 적으면서도 코드에 많은 기능을 추가할 수 있어요.

@example_decorator()
def hello_world():
   ...

AgentOps는 AI 에이전트 워크플로우를 추적하고 모니터링하기 위해 코드를 쉽게 계측할 수 있게 해주는 데코레이터 세트를 제공해요. 이 데코레이터들은 계층적으로 정리된 span(작업 단위)을 만들어 서로 다른 유형의 작업을 추적합니다.

`@session`

@session 데코레이터는 다른 모든 span의 루트(root)가 되는 session span을 만들어요. 최상위에 세션이 없으면 어떤 span도 존재할 수 없어요.

from agentops.sdk.decorators import session

@session
def my_workflow():
    # Your session code here
    return result

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

@session(name="custom-session-name", version=1)
def my_workflow():
    # Your session code here
    return result

`@agent`

@agent 데코레이터는 에이전트 작업을 추적하기 위한 agent span을 만들어요. agent span은 보통 session span의 자식(child)이자 operation span의 부모(parent)예요.

from agentops.sdk.decorators import agent

@agent
class MyAgent:
    def __init__(self, name):
        self.name = name
        
    # Agent methods here

에이전트의 사용자 지정 이름을 정할 수도 있어요:

@agent(name="research-assistant")
class MyAgent:
    # Agent implementation

`@operation` / `@task`

@operation과 @task 데코레이터는 동일한 별칭(alias)으로, 특정 작업을 추적하는 operation/task span을 만들어요. 이 span들은 보통 agent span의 자식입니다.

from agentops.sdk.decorators import agent, operation

@agent
class MyAgent:
    @operation
    def perform_task(self, task):
        # Operation implementation
        return result

operation은 agent 클래스 밖에서도 사용할 수 있어요:

from agentops.sdk.decorators import operation

@operation
def process_data(data):
    # Process the data
    return result

`@workflow`

@workflow 데코레이터는 여러 개의 operation을 포함할 수 있는 워크플로우를 추적하는 workflow span을 만들어요.

from agentops.sdk.decorators import workflow

@workflow
def my_workflow(data):
    # Workflow implementation
    return result

중첩과 계층 구조 (Nesting and Hierarchy)

데코레이터는 컨텍스트 전파(context propagation)를 자동으로 관리해서, span이 부모 span 안에 올바르게 중첩되도록 보장해요. 전형적인 계층 구조는 다음과 같습니다:

Session (root)
Agent
Operation/Task
Nested Operations

올바른 중첩 예시를 볼게요:

from agentops.sdk.decorators import session, agent, operation

@agent
class MyAgent:
    @operation
    def nested_operation(self, message):
        return f"Processed: {message}"
        
    @operation
    def main_operation(self):
        result = self.nested_operation("test message")
        return result

@session
def my_session():
    agent = MyAgent()
    return agent.main_operation()
    
# Run the session
result = my_session()

추가 기능 (Additional Features)

데코레이터는 몇 가지 추가 기능을 제공해요:

입력/출력 기록 (Input/Output Recording): 데코레이터는 데코레이트된 함수의 입력 인자와 출력 결과를 자동으로 기록해요.
예외 처리 (Exception Handling): 데코레이트된 함수 안에서 예외가 발생하면 span에 기록돼요.
다양한 함수 유형 지원 (Support for Different Function Types): 데코레이터는 여러 유형의 함수를 처리해요.
- 일반 동기 함수 (Regular synchronous functions)
- 비동기 함수 (async/await 사용)
- 제너레이터 함수 (yield 사용)
- 비동기 제너레이터 함수 (async와 yield 사용)
사용자 지정 속성 (Custom Attributes): 데코레이터 파라미터를 사용해서 span에 사용자 지정 속성을 추가할 수 있어요.

데코레이터