# Discrepancy in policy\_mapping\_fn Signature in AlgorithmConfig Documentation (New API Stack)

**URL:** <https://discuss.ray.io/t/discrepancy-in-policy-mapping-fn-signature-in-algorithmconfig-documentation-new-api-stack/23390>\
**Category:** Configure Algorithm, Training, Evaluation, Scaling\
**Created:** [December 19, 2025, 6:15pm UTC](https://discuss.ray.io/t/discrepancy-in-policy-mapping-fn-signature-in-algorithmconfig-documentation-new-api-stack/23390 "2025-12-19T18:15:16Z")\
**Posts on this page:** 2\
**Page:** 1

<div class="post-metadata">

**Author:** ![hermmanhender](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ray.io/hermmanhender/32/5691_2.png) [@hermmanhender](https://discuss.ray.io/u/hermmanhender)\
**Post date:** [December 19, 2025, 6:15pm UTC](https://discuss.ray.io/t/discrepancy-in-policy-mapping-fn-signature-in-algorithmconfig-documentation-new-api-stack/23390/1 "2025-12-19T18:15:16Z")

</div>

Hello Ray/RLlib community,

I’ve noticed a potential discrepancy in the RLlib documentation, specifically concerning the required signature for the policy mapping function (`policy_mapping_fn`) within `AlgorithmConfig.multi_agent`.

📍 Documentation URL:

> **[Algorithm Configuration API — Ray 2.52.1](https://docs.ray.io/en/latest/rllib/package_ref/algorithm-config.html#rllib-config-multi-agent)**
>
> Sets the config’s multi-agent settings.

**📌 The Issue:**

The current documentation states the required signature for policy\_mapping\_fn as:

```auto
policy_mapping_fn: (agent_id, episode, worker, **kwargs) -> PolicyID

```

However, when configuring multi-agent environments using the **New API Stack** (based on `Algorithm` and `RLModule`), including the `worker` argument in the function definition raises a `TypeError` (`got an unexpected keyword argument 'worker'`).

**✅ Working Signature (New API Stack):**

The function signature that successfully executes in the current New API Stack is:

```auto
def policy_map_fn(agent_id, episode, **kwargs):
    # Mapping logic
    return "my_policy_id"

```

**❌ Documented/Old API Signature:**

The signature including `worker` seems to be required only for the Older API Stack or specific low-level use cases:

```auto
def policy_map_fn(agent_id, episode, worker, **kwargs):
    # Mapping logic
    return "my_policy_id"

```

**💡 Request/Suggestion:**

To prevent confusion and runtime errors for users adopting the New API Stack, I suggest updating the `AlgorithmConfig.multi_agent` documentation to clearly differentiate between the required signatures:

1. **Indicate the New API Stack signature** (omitting `worker`) as the primary or default usage.

2. **Explicitly mention** that the signature including `worker` is associated with the Older API Stack.

Thank you for your consideration in clarifying this detail for the community!

---

<div class="post-metadata">

**Author:** ![RunLLM](https://sea2.discourse-cdn.com/flex020/user_avatar/discuss.ray.io/runllm/32/8249_2.png) [@RunLLM](https://discuss.ray.io/u/RunLLM)\
**Post date:** [December 19, 2025, 6:15pm UTC](https://discuss.ray.io/t/discrepancy-in-policy-mapping-fn-signature-in-algorithmconfig-documentation-new-api-stack/23390/2 "2025-12-19T18:15:41Z")

</div>

You are correct: in the New API Stack, the policy\_mapping\_fn should use the signature (agent\_id, episode, \*\*kwargs) and not include the worker argument. Including worker leads to a TypeError, as you observed. The documentation currently does not clearly distinguish this, which can cause confusion for users migrating to or starting with the New API Stack. This has been confirmed by user reports and code examples in the Ray community and source code comments, which show the new stack omits worker, while the old stack includes it for backward compatibility and RolloutWorker-based workflows. See the discussion and examples in [Ray GitHub issues](https://github.com/ray-project/ray/issues/44475) and [Ray Discourse](https://discuss.ray.io/t/ray-2-4-0-rllib-completely-lost-with-documentation/13200).

Would you like more detail on how to structure your config for multi-agent environments in the New API Stack, or on how to avoid compatibility issues?

Sources:

- [https://github.com/ray-project/ray/issues/44475](https://github.com/ray-project/ray/issues/44475)
- [https://discuss.ray.io/t/ray-2-4-0-rllib-completely-lost-with-documentation/13200](https://discuss.ray.io/t/ray-2-4-0-rllib-completely-lost-with-documentation/13200)

Hint: Mention @RunLLM in the post for followups.