# 监控模块

agentUniverse监控模块，主要围绕agent运行时的模型调用/token开销等进行数据追踪与记录。针对**目前框架已开放的模型调用追踪能力和agent调用追踪能力**，本文将详细介绍如何使用这两个功能。

## 监控配置

在agentUniverse的主配置文件`config.toml`中配置监控模块配置信息，如下：

```toml
[MONITOR]
activate = true
dir = './monitor'
```

- **`activate`**: 监控模块总开关，默认关闭，设置为true后将开启agent运行时的LLM调用追踪功能和agent调用追踪功能。
- **`dir`**: 监控模块对应的本地记录存储目录，默认为运行时，上一层级下的monitor目录，用户可自定义配置目录路径。

### 模型粒度配置

针对LLM调用追踪能力，agentUniverse同样支持模型粒度配置，当监控模块主开关打开后，可以通过LLM的yaml文件选择关闭特定模型调用追踪功能。

比如用户自定义的`demo_llm`模型，tracing设置为false，则关闭该模型的调用追踪功能。

```yaml
name: 'demo_llm'
description: 'demo openai'
model_name: 'gpt-4o'
max_tokens: 1000
max_retries: 2
tracing: false
metadata:
  type: 'LLM'
  module: 'agentuniverse.llm.default.default_openai_llm'
  class: 'DefaultOpenAILLM'
```

特别说明：agentUniverse主配置文件的监控模块总开关**优先级最高**，若activate配置为false的情况下，模型粒度配置不生效。

### Agent粒度配置

针对agent调用追踪能力，agentUniverse同样支持agent粒度配置，当监控模块主开关打开后，可以通过agent的yaml文件选择关闭特定agent调用追踪功能。

比如用户自定义的`demo_agent`智能体，tracing设置为false，则关闭该智能体的调用追踪功能。

```yaml
info:
  name: 'demo_agent'
  description: 'demo agent'
profile:
  tracing: false
  prompt_version: demo_agent_prompt.cn
  llm_model:
    name: 'qwen_llm'
action:
  tool:
    - 'google_search_tool'
memory:
  name: ''
metadata:
  type: 'AGENT'
  module: 'sample_standard_app.intelligence.agentic.agent.agent_instance.demo_agent'
  class: 'DemoAgent'
```

特别说明：agentUniverse主配置文件的监控模块总开关**优先级最高**，若activate配置为false的情况下，agent粒度配置不生效。

## 监控模块说明

### 模型调用追踪

用户若使用当前agentUniverse支持的**默认模型类**，则如上文所述配置完成后即可使用该功能。

#### trace_llm装饰器

若用户根据agentUniverse的模型基类LLM做自定义扩展，实现自定义模型调用，则需要在自定义模型类的调用方法call/acall中增加@trace_llm装饰器功能。

如下自定义模型示例代码：

```python
from typing import Any, Iterator, Union, AsyncIterator

from agentuniverse.llm.llm import LLM, LLMOutput
from agentuniverse.base.annotation.trace import trace_llm


class DemoLLM(LLM):

    @trace_llm
    def call(self, messages: list, **kwargs: Any) -> Union[LLMOutput, Iterator[LLMOutput]]:
        pass

    @trace_llm
    async def acall(self, *args: Any, **kwargs: Any) -> Union[LLMOutput, AsyncIterator[LLMOutput]]:
        pass
```

agentUniverse通过`@trace_llm`装饰器实现，agent在调用对应LLM
call/acall方法时，采集模型prompt和response，将信息json序列化后存储到上文监控配置对应的本地存储目录下，以jsonl文件的形式按小时为单位分割。

#### 具体效果

调用agentUniverse sample工程中的demo_rag_agent，使用qwen-turbo模型，query为分析下巴菲特减持比亚迪的原因，模型调用追踪功能捕捉到的数据如下：

```json
{
  "source": "QWenOpenAIStyleLLM.acall",
  "date": "2024-06-24 16:27:14",
  "llm_input": {
    "messages": [
      {
        "role": "system",
        "content": "你是一位精通信息分析的ai助手。\\n 你的目标是判断问题对应的答案是否提供了有价值的信息，并对问题的答案做出建议和评价"
      },
      {
        "role": "user",
        "content": "你需要遵守的规则是:\\n1. 必须使用中文结合查询的背景信息结合你所拥有的知识回答用户提出的问题。\\n2. 结构化答案生成，必要时通过空行提升阅读体验。\\n 需要回答的问题是: 分析下巴菲特减持比亚迪的原因\\n"
      }
    ]
  },
  "kwargs": {
    "model": "qwen-turbo",
    "stream": false,
    "n": 1,
    "temperature": 0.5,
    "max_tokens": 1000
  },
  "llm_output": "巴菲特减持比亚迪股票的原因可以从几个方面来分析：\\n\\n1. **投资策略调整**：尽管巴菲特通常倾向于长期持有优质股票，但投资组合管理需要灵活性。他可能会根据市场动态、行业趋势和个人评估的变化，适时调整持仓以优化资产配置或分散风险。\\n\\n2. **估值与预期回报**：减持可能反映了巴菲特对比亚迪当前股价与他内在价值评估的差距。尽管比亚迪业绩强劲，但如果他认为股价过高，可能会选择部分兑现利润。\\n 综上所述，巴菲特减持比亚迪股票可能是基于上述因素的综合考虑，但具体原因只有巴菲特和芒格本人了解。值得注意的是，尽管减持，他们对比亚迪的长期看好并未改变，这从芒格的演讲和持续的股东大会支持可以看出。"
}
```

- **`source`**: agent运行时LLM的调用来源
- **`date`**: LLM调用时间
- **`llm_input`**: LLM调用message及模型参数
- **`llm_output`**: LLM输出文本段信息

### Agent调用追踪

#### trace_agent装饰器

agentUniverse通过`@trace_agent`装饰器实现，agent在调用run方法时，采集agent输入和输出，将信息json序列化后存储到上文监控配置对应的本地存储目录下，以jsonl文件的形式按小时及单智能体为单位分割。

#### 具体效果

调用agentUniverse sample工程中的demo_rag_agent，query为分析下巴菲特减持比亚迪的原因，agent调用追踪功能捕捉到的数据如下：

```json
{
  "source": "demo_rag_agent",
  "date": "2024-06-27 19:26:46",
  "agent_input": {
    "kwargs": {
      "input": "分析下巴菲特减持比亚迪的原因"
    }
  },
  "agent_output": {
    "chat_history": [
      {
        "content": "分析下巴菲特减持比亚迪的原因",
        "type": "human"
      },
      {
        "content": "巴菲特减持比亚迪的原因可能涉及多个方面：\n\n1. **投资回报与资产配置**：随着比亚迪股价的大幅上涨，特别是新能源汽车业务的强劲表现，巴菲特可能认为已经达到其预期的回报，需要将资本转向其他潜在收益更高的投资。\n\n2. **芒格影响减弱**：芒格去世后，巴菲特作为伯克希尔·哈撒韦的唯一决策者，投资策略可能会有所调整，这可能影响他对比亚迪的投资态度。\n\n3. **资本结构调整**：巴菲特可能寻求更均衡的投资组合，通过减持比亚迪来优化伯克希尔·哈撒韦的整体资产配置。\n\n4. **风险控制**：持股比例降低至5%以下后，巴菲特的减持速度可能会加快，这可能是为了降低单一投资的风险。\n\n5. **市场动态**：在比亚迪股价下跌时未大幅减持，可能表明他之前是在等待一个更合适的市场时机。\n\n综合以上分析，巴菲特减持比亚迪的原因可能包含对投资回报的追求、对公司估值的判断以及个人投资策略的更新。然而，具体原因还需更多官方信息来确认。",
        "type": "ai"
      }
    ],
    "background": "针对巴菲特减持比亚迪的原因，目前市场依然处于猜想的状态，但从近年来的投资举动来看，也大概可以看出巴菲特减持比亚迪的一些想法。 我们可以从巴菲特 ... 为何巴菲特减持比亚迪？ 综合多家媒体的分析报道，巴菲特减持比亚迪股份可能是出于多种考虑，包括为了更好地配置资本、实现投资回报、投资策略的调整以及 ... 有私募人士分析认为，巴菲特从2008年建仓至今，比亚迪在新能源汽车的快速渗透下，营收和利润也达到了空前的规模，股价近30倍的涨幅，伯克希尔减持比亚迪 ... 对于巴菲特减持原因，相关人士表示，“公司在和对方沟通。”问及公司估值是否偏高，上述人士表示，“公司经营状况良好，销量、利润等保持增长。” 6月18日， ... 据证券时报e公司报道，中泰国际策略分析师颜招骏认为，巴菲特减持应该是看到长线的基本面发生变化或估值已经大幅偏离内在价值。一旦持股比例降至5%， ... 在比亚迪股票处于大幅下跌的阶段，伯克希尔哈撒韦则采取了观望的态度，减持力度并未有太明显。对股神巴菲特来说，在股价处于高位的时候获利了结、锁定 ... 相较于常规动力电池，刀片电池内部体积利用率增长了50%以上，整体体积能量密度可以媲美高能量密度的三元锂电池，能够在保证安全的前提下，提升新能源车的 ... ... 巴菲特第一次减持比亚迪了。从最初的19.92%到现在的5.99%，巴菲特对比亚迪的投资似乎正在逐步减少。有分析师指出，一旦持股比例降至5%，巴菲特的减持速度可能会加快。 巴菲特减持比亚迪的真实原因如何？对此，有各种各样的分析。 有的从地缘 ... 有的从地缘政治切入，有的从芒格去世后，巴菲特独掌大权后的风格切换进行分析， ... 市场分析认为，巴菲特的减持可能是为了更好地配置资本，并且进行获利了结。巴菲特本人也曾表示，减持比亚迪是为了找到这些资金更好的配置用途。同时， ...",
    "date": "2024-06-27",
    "input": "分析下巴菲特减持比亚迪的原因",
    "output": "巴菲特减持比亚迪的原因可能涉及多个方面：\n\n1. **投资回报与资产配置**：随着比亚迪股价的大幅上涨，特别是新能源汽车业务的强劲表现，巴菲特可能认为已经达到其预期的回报，需要将资本转向其他潜在收益更高的投资。\n\n2. **芒格影响减弱**：芒格去世后，巴菲特作为伯克希尔·哈撒韦的唯一决策者，投资策略可能会有所调整，这可能影响他对比亚迪的投资态度。\n\n3. **资本结构调整**：巴菲特可能寻求更均衡的投资组合，通过减持比亚迪来优化伯克希尔·哈撒韦的整体资产配置。\n\n4. **风险控制**：持股比例降低至5%以下后，巴菲特的减持速度可能会加快，这可能是为了降低单一投资的风险。\n\n5. **市场动态**：在比亚迪股价下跌时未大幅减持，可能表明他之前是在等待一个更合适的市场时机。\n\n综合以上分析，巴菲特减持比亚迪的原因可能包含对投资回报的追求、对公司估值的判断以及个人投资策略的更新。然而，具体原因还需更多官方信息来确认。"
  }
}
```

- **`source`**: Agent运行时的调用来源（智能体名称）
- **`date`**: Agent调用时间
- **`agent_input`**: Agent调用输入参数
- **`agent_output`**: Agent输出参数