langgoap.create_goap_agent

langgoap.create_goap_agent#

create_goap_agent(tools, goal, *, llm=None, preconditions=None, effects=None, resources=None, costs=None, result_keys=None, max_retries=None, durations=None, effect_validators=None, **graph_kwargs)[source]#

Create a compiled GOAP agent from a list of LangChain tools and a goal.

NL-at-invocation-time limitation: the returned CompiledStateGraph only exposes LangGraph’s invoke({"goal": GoalSpec, "world_state": dict}) and ainvoke interfaces. It does not have invoke_nl(), because that method lives on the GoapGraph builder, not on the compiled graph. For single-shot NL execution pass goal=request_string directly (NL interpretation happens once at construction). For repeated NL-driven invocations against the same tool set, construct a GoapGraph directly and use invoke_nl().

Parameters:

  • tools (list[BaseTool]) – The LangChain tools the agent may call.

  • goal (str | GoalSpec) – A GoalSpec, or a natural-language string. If a string, llm must be provided.

  • llm (BaseChatModel | None) – Chat model used to interpret a string goal. Ignored when goal is already a GoalSpec.

  • preconditions (dict[str, dict[str, Any]] | None) – Optional mapping of tool name → preconditions dict. Missing tools get empty preconditions.

  • effects (dict[str, dict[str, Any]] | None) – Optional mapping of tool name → effects dict. Missing tools get empty effects.

  • resources (dict[str, dict[str, float]] | None) – Optional mapping of tool name → resources dict.

  • costs (dict[str, float] | None) – Optional mapping of tool name → action cost override.

  • result_keys (dict[str, str] | None) – Optional mapping of tool name → world-state key that should receive the tool’s raw return value at execution time. Use this to wire one tool’s output into the next tool’s input — e.g. {"research_topic": "brief"} makes the return value of research_topic available to a downstream write_article(brief) tool via world_state["brief"]. Planning is unaffected; A* still reasons over the boolean flags in effects. A key here must not collide with any key declared for the same tool in effects (see goapify_tool()).

  • max_retries (dict[str, int] | None) – Optional mapping of tool name → planner-level retry budget. 0 (default) blacklists the action on its first failure; N allows N extra planner-level replans before blacklisting (i.e. N + 1 total failures). This is the knob that lets a transient failure trigger replanning without giving up entirely.

  • durations (dict[str, timedelta] | None) – Optional mapping of tool name → datetime.timedelta. Used by the CSP scheduler when computing parallel execution windows. Tools with no entry default to instantaneous actions.

  • effect_validators (dict[str, Callable[[dict[str, Any], dict[str, Any]], bool]] | None) – Optional mapping of tool name → callable (pre_state, post_state) -> bool invoked after execution. Returning False signals the action did not produce its declared effects (soft failure → replan).

  • **graph_kwargs (Any) – Forwarded to GoapGraph.compile() (e.g. checkpointer, store).

Returns:

A compiled CompiledStateGraph ready for .invoke() or .ainvoke().

Raises:

ValueError – If goal is a string but llm is None.

Return type:

CompiledStateGraph