跳到主要内容

请求

图标​

功能​

获得选定目标实体的对象，支持访问其属性或调用其行为流程

提示

请求是实体间交互最重要的方式，相当于Ask Someone ('s Property, or to do Something)，建模应用广泛。

  • Web3的DeFi领域中，一个用户在DEX中交易代币，可视作用户Agent请求智能合约Agent按需求参数调用合约的Swap方法。
  • 草原生态系统中，一只狼捕食一只羊，可视作狼Agent请求被捕羊Agent的Die内置行为。
  • 元胞自动机，一个元胞Cell个体请求周围元胞Cell的状态来决定自己的下一步状态。

运行机制​

选定目标实体​

在一个多实体的系统中，如果想找到目标实体（们），需要指定以下3个方面信息，系统将依次执行：

  1. 指定实体范围
  2. 指定过滤条件
  3. 确定最终目标
建议

锁定目标实体的过程是请求的关键，理解其工作机制有助于掌握组件的用法.

理解示例1

一个草原生态系统为例，要模拟狼找到捕食的羊，狼可能需：

  1. 指定空间半径范围内所有邻居实体
  2. 过滤出是羊种群的，且其速度小于某值的所有个体
  3. 最后确定最肥的那只个体
理解示例2

DeFi领域的代币交易，要在一个DEX中想以尽量低的手续费、以USDC为本金购买需要的X代币，使用请求组件找到对应币对个体（DEX已经建模为一个Agent种群，每个个体就对应一种币对池）以便下一步的调用交易需要：

  1. 指定范围是DEX种群所有个体
  2. 过滤出凡是"交易对"（实体属性）为"X-USDC"的个体
  3. 确定其中"手续费率"（实体属性）最低的那个个体
  • 系统会输出请求到的目标实体列表，详见下输出数据
  • 筛选目标实体是请求组件必然运行的部分，在此基础上可以选择是否访问其属性和调用其行为

访问目标实体属性​

在确定目标实体后，可以选择访问其属性，但仅限于目标实体是1个对象时

请求调用目标实体行为​

  • 在确定目标实体后，可以选择调用其行为

  • 能够被请求调用的行为必须是被动的、独立流程

  • 数据传递

    如果被请求调用流程中有接口，调用对象会出现相应端口，数据传递的方法详见流程的数据传递章节

  • 请注意

    当目标实体为多个时，如果调用流程有端口返回输出值，那么虽然当前Trigger的运行会让每个目标实体都运行目标流程并返回输出值，但因为后返回结果覆盖先返回的结果，所以最终仅能得到按运行顺序最后一个个体的返回结果，当然你可以结合调试断点及其调用堆栈查看每个个体当时返回的中间结果

    提示

    如果被调用流程通过端口返回1个Number，而你希望使用一个Value格式的变量V存储该值

    • 目标对象仅为1个实体时，当请求调用它时，端口就会返回这个值，而你可以按预期存储在V中
    • 但当目标对象为多个时，每个对象都会返回输出值，因此负责接受该值的变量V接收了多次从而最终只保存了最后执行流程的个体返回结果，由于运行顺序有随机性，这意味着可能每次运行时结果会不同
    • 由于系统的结果图表输出只反应当前Tick结束时所有的状态，所以你无法在V的图表看到其它个体的结果
    • 但是你可以合理使用控制中心的调试断点、调用堆栈及其局部变量功能查看其它个体的中间结果
    • 所以有类似需求时推荐采用其它适合的方式建模，比如你可以为被调用者建立上级List变量，让被调用流程自己Append输出值到该List，以获取所有数据

边界事件​

  • 请求实体时不一定成功，比如目标实体压根不存在、过滤条件设置错误等都会使请求失败，导致报错
  • 一旦为请求动作设置边界事件，相当于设置了请求异常应对机制
  • 请求只能配合错误边界事件使用，表示系统一旦未找到任何目标实体，流程Trigger将立即流向边界事件分支

对象设置方法​

Ask_image3.png

选定目标实体​

指定实体范围​

Ask_image4.png

  • 表达式输入栏，需要返回Entity或者[Entity]格式的值
请求范围表达式示例
  • wolf.Individuals 狼种群的所有个体
  • sheep.FilterEntities(self.GetNeighbors(1.5)) 以自己为中心半径1.5内的所有羊
  • GetRelatives(cooperation, 1) 和自己有直接（半径1）合作关系（名为cooperation的Link对象）的Agent实体（这里可以省略Self关键字；只有Agent能够作为网络节点）
  • sheep.Individuals.copy().extend(cattle.Individuals)羊和牛种群的所有个体

指定过滤条件​

Ask_image5.png

  • 过滤实体种群

    下拉菜单选择模型中现有的实体对象，是快速特定过滤，当然也可以选择任意种群表示不用过滤

  • 自定义过滤条件表达式

    Ask_image6.png

    • 点击添加过滤条件按钮，会增加一行输入框，在其中输入条件表达式
    • 所有表达式之间可以使用开关选择 与/或 的关系
    • 表达式用于过滤当前所有目标个体，所以应与当前目标对象个体相关（关键字默认使用Entity，也可以自定义为其他），且能够返回一个布尔值，建模时通常我们使用关于Entity.property_name的条件表达式来实现根据实体的属性过滤
    • 对每个表达式系统将逐一匹配所有目标个体计算结果，最终保留能返回True的那些作为目标对象
      提示
      • 过滤机制本质上相当于一个map(filter_method, [entity_object])函数，过滤方法就是条件表达式，过滤对象就是已经在范围内的实体列表，map函数会应用过滤方法对对象列表的每个对象进行计算得到一个[bool]格式的结果，过滤就是根据此结果决定目标对象的
      • 建模中最常用的方式是对其属性的判断，如：Entity.Color == "red" 表示颜色为红色的那些个体

确定最终目标​

Ask_image7.png

提示
  • 经过以上两步，我们得到了既在范围内、又满足过滤条件的那些个体集
  • 但这并不意味着事情结束了，因为还需要明确最终输出的要求，如需要的是个体还是集合列表？如果是集合需要几个？是哪几个？如何确定那几个？
  • 所以需要确定最终目标

  • 确定输出形式

    选择个体/个体集，即对应返回目标实体的格式是Entity/[Entity]

  • 选择方法

    以下拉菜单选择方法得到最终的目标

    • 所有

      取所有，无需后续设置

      Ask_image8.png

    • 随机取

      Ask_image9.png

      • 输出为个体时选择随机就无需后续设置了，输出选择为集合时需要指定选择数量（表达式）
      • 数量表达式接受返回自然数的Number格式表达式
      • 当前过滤结果不足以取到Number指定的数量的个体时会全部取

    • 最大值

      取按照指定表达式计算值最大的实体

      Ask_image10.png

      • 保留数量

        • 如果输出实体集合，那么还需要输入个数n（类似随机取）
        • 如果符合条件的个体数量不足设定个数n就会取全部

      • 排序依据

        • 选择取最大值后，需要在排序依据输入框给出排序依据表达式
        • 应输入关于目标实体属性（格式为"Entity.property_name"）的、并且能返回Number格式的表达式

    • 最小值

      取按照指定的排序依据表达式计算结果最小的实体，使用方法同取最大值

    • 中位数

      取按照指定的排序依据表达式计算结果中位数的实体，使用方法同取最大值

    • 总和限定

      取按指定的加总依据表达式计算结果的总和不超过指定限定值的实体。系统会随机挑选待选实体个体，累加表达式计算结果，直到超出限定值为止。

      Ask_image11.png

      • 限定值

        ​输入返回Number的表达式

      • 加总依据

        ​应输入关于目标实体属性（格式为"Entity.property_name"）的、并且能返回Number格式的表达式

模型案例：总和限定的使用

一个驾驶最大载重140的车辆司机可挑选3种包裹的重量分别为60，70，80装车

Ask_image11+0.1.png

Ask_image11+0.2.png

选择请求模式​

Ask_image11+1.png

选择：获取选定对象/访问对象属性/调用对象行为

请求获取选定对象​

无需更多配置

请求访问目标属性​

仅限于选定对象是1个的时候

Ask_image12.png

  • 添加属性

    点击添加属性按钮会出现下拉选择框，可以从中选择目标属性，因此系统支持一次请求访问多个属性

  • 添加引用到画布

    点击右侧的按钮可以当前画布请求组件附近自动添加该属性的引用，以方便建模

    提示

    当然也可以拖放一个空引用组件到相同画布后，再选择引用目标为请求的属性，操作等价。

请求调用目标行为​

Ask_image15.png

  • 操作

    • 选择目标行为：在行为选择下拉菜单中选择目标行为
    • 跳转到原型：选型下拉框右侧有跳转按钮点，击可以将当前画布视图聚焦到目标对象

      Ask_image16.png

  • 说明

    • 一次请求只能调用一个行为
    • 被调用行为只能是目标对象的被动的、独立流程
    • 组件在画布中的样式会由正方形更改为与调用类似的长方形，此时用法类似于调用

      Ask_image17.png

    • 当被调用流程具有端口时，数据传递详见相关章节

组件的数据输出​

1. 选定的实体对象​

  • 格式Entity或[Entity]
  • 在本组件动作后计算式中以"This.Entity"形式访问
  • 在本流程后继对象计算表达中以"ask_component_name.Entity"形式访问

2. 请求到的属性​

  • 在本组件动作后计算式中以"This.property_name"形式访问
  • 在本流程后继对象计算表达中以"ask_component_name.property_name"形式访问

3. 请求调用的端口数据​

同调用组件，略

提示

对上述三种情况，系统在公式或表达式中的识别优先级2和3（不会同时出现）高于1。

案例​

模型案例
  • 2个DeFi用户分别从一个恒定积AMM DEX中购买WETH代币和出售WBTC代币，DEX的2个个体分别负责2种代币对
  • DEX的两种币对池初始情况如下图
  • 交易后WETH价格因为购买而升高，WBTC价格因为出售而降低

Ask_image18.png