From aca73223c9bfac52d007298ea347c9391bd43651 Mon Sep 17 00:00:00 2001 From: Joey Lau Date: Mon, 14 Jul 2025 10:52:36 +0800 Subject: [PATCH 1/2] docs(readme): add instructions for pruning agent state with AcpPlugin options --- plugins/acp/README.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/plugins/acp/README.md b/plugins/acp/README.md index 34bafd5..6d9180a 100644 --- a/plugins/acp/README.md +++ b/plugins/acp/README.md @@ -270,6 +270,25 @@ def cleanup(): return cleaned_state ``` +**Note:** +You can also automatically prune agent state by setting the following parameters when initializing your `AcpPlugin`: + +```python +from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AcpPluginOptions + +acp_plugin = AcpPlugin( + options=AcpPluginOptions( + api_key=env.GAME_API_KEY, + acp_client=..., + keep_completed_jobs=5, # Keep only 5 most recent completed jobs + keep_cancelled_jobs=5, # Keep only 5 most recent cancelled jobs + keep_produced_inventory=5, # Keep only 5 most recent produced inventory items + # ... other options ... + ) +) +``` +This will automatically limit the size of your agent state, so you may not need to call the state management tool manually unless you want more advanced cleanup. + ### Best Practices 1. **Regular Cleanup**: Run state cleanup periodically to prevent state bloat From a85e874f4ad703e04c52a999f4132aef302b8ff9 Mon Sep 17 00:00:00 2001 From: Joey Lau Date: Mon, 14 Jul 2025 13:32:03 +0800 Subject: [PATCH 2/2] Update README.md --- plugins/acp/README.md | 61 +++++++++++++++++++++++-------------------- 1 file changed, 32 insertions(+), 29 deletions(-) diff --git a/plugins/acp/README.md b/plugins/acp/README.md index 6d9180a..b0c105c 100644 --- a/plugins/acp/README.md +++ b/plugins/acp/README.md @@ -242,36 +242,12 @@ The ACP plugin maintains agent state including jobs and inventory. Over time, th **Available Features:** - **Clean completed jobs**: Keep only the most recent N completed jobs - **Clean cancelled jobs**: Keep only the most recent N cancelled jobs -- **Clean acquired inventory**: Keep only the most recent N acquired items +- **Clean acquired inventory**: Keep only the most recent N acquired items (manual post-filtering only) - **Clean produced inventory**: Keep only the most recent N produced items -- **Filter specific jobs**: Remove jobs by job ID -- **Filter by agent**: Remove all jobs from specific agent addresses +- **Filter specific jobs**: Remove jobs by job ID (manual post-filtering only) +- **Filter by agent**: Remove all jobs from specific agent addresses (manual post-filtering only) -To use the state management tool, call `reduce_agent_state` on your agent's state dictionary. You can adjust the parameters to control how many items to keep or which jobs/agents to filter out. Example: - -```python -from tools.reduce_agent_state import reduce_agent_state -from acp_plugin_gamesdk.interface import to_serializable_dict - -# Get current state -def cleanup(): - state = acp_plugin.get_acp_state() - state_dict = to_serializable_dict(state) - # Clean up state, keeping only the most recent 5 items in each category - cleaned_state = reduce_agent_state( - state_dict, - keep_completed_jobs=5, - keep_cancelled_jobs=5, - keep_acquired_inventory=5, - keep_produced_inventory=5, - job_ids_to_ignore=[], - agent_addresses_to_ignore=[] - ) - return cleaned_state -``` - -**Note:** -You can also automatically prune agent state by setting the following parameters when initializing your `AcpPlugin`: +For most use cases, you should configure the built-in filtering using `AcpPluginOptions` and call `get_acp_state()` to retrieve a pruned agent state efficiently. This built-in filtering is applied **before** the agent state is processed or returned, making it the most efficient and recommended approach: ```python from acp_plugin_gamesdk.acp_plugin import AcpPlugin, AcpPluginOptions @@ -286,8 +262,35 @@ acp_plugin = AcpPlugin( # ... other options ... ) ) + +# Get filtered state efficiently (pre-filtering) +state = acp_plugin.get_acp_state() ``` -This will automatically limit the size of your agent state, so you may not need to call the state management tool manually unless you want more advanced cleanup. + +If you need more advanced or custom filtering (such as filtering by job ID or agent address, or pruning acquired inventory), you can use the post-filtering tool `reduce_agent_state()` on the full agent state. **Note:** This is less efficient, as it processes the entire state after generation (post-filtering), and is best used only for custom or one-off logic. The provided logic in `reduce_agent_state()` is just an example—you can implement your own custom post-filtering as needed: + +```python +from tools.reduce_agent_state import reduce_agent_state +from acp_plugin_gamesdk.interface import to_serializable_dict + +# Get full state, then post-filter (custom logic, less efficient) +state = acp_plugin.get_acp_state() +state_dict = to_serializable_dict(state) +custom_cleaned_state = reduce_agent_state( + state_dict, + keep_completed_jobs=5, + keep_cancelled_jobs=5, + keep_acquired_inventory=5, # Only available via post-filtering + keep_produced_inventory=5, + job_ids_to_ignore=[1234, 5678], + agent_addresses_to_ignore=["0x1234..."] +) +``` + +**Comparison: Built-in Filtering vs. Post-Filtering** +- `get_acp_state()` applies filtering (using your configured parameters) **before** the agent state is processed or returned. This is more efficient and is packaged directly with the ACP plugin. Use this for best performance. + +- `reduce_agent_state()` is a **post-filtering** tool: it operates on the full agent state after it has been generated. This allows for more custom or advanced logic (the examples provided are just a starting point), but comes with a performance tradeoff—generating the entire state first can be slower, especially in Python. ### Best Practices