langgoap.goapify_tool

Contents

langgoap.goapify_tool#

goapify_tool(tool, *, preconditions=None, effects=None, cost=1.0, resources=None, duration=None, max_retries=0, effect_validator=None, result_key=None)[source]#

Wrap a LangChain BaseTool into a LangGOAP ActionSpec.

The resulting action’s execute callable invokes tool with the state dict filtered to match the tool’s declared input schema (if any) and returns the declared effects dict. Passing no preconditions/effects yields an action with empty pre/eff — legal but rarely useful, which is why create_goap_agent() emits a warning in that case.

Parameters:

  • tool (BaseTool) – Any LangChain BaseTool instance (e.g. produced by the @tool decorator).

  • preconditions (dict[str, Any] | None) – World-state conditions required before the tool runs. Keys must be hashable scalars.

  • effects (dict[str, Any] | None) – World-state changes produced by executing the tool. These boolean/scalar flags are what A* reasons over.

  • cost (float) – Static action cost for A* search. Defaults to 1.0.

  • resources (dict[str, float] | None) – Per-run resource usage for CSP optimization (e.g. {"cost_usd": 0.02, "tokens": 500}).

  • duration (timedelta | None) – Estimated wall-clock duration for temporal scheduling.

  • max_retries (int) – Number of retries before the executor blacklists the action.

  • effect_validator (Callable[[dict[str, Any], dict[str, Any]], bool] | None) – Optional postcondition checker.

  • result_key (str | None) –

    When set, the tool’s raw return value is stored in world_state[result_key] after execution so that downstream actions can read it. Planning is unaffected — A* continues to reason over the boolean flags in effects. Typical usage:

    search = goapify_tool(
    search_tool,
    effects={"search_done": True},
    result_key="search_results",
)
# After execution: world_state["search_results"] == <raw output>

    result_key must not overlap with any key in effects — a collision would silently overwrite the planning flag with raw tool output, corrupting the world state A* reasons over.

Returns:

A frozen ActionSpec ready to feed into GoapGraph.

Raises:

  • TypeError – If tool is not a BaseTool instance.

  • ValueError – If result_key matches a key already declared in effects. This would silently overwrite the planning flag with raw tool output at execution time.

Return type:

ActionSpec

Contents