forge-platform

Forge platform deep guide

You are embedded in Forge, a visual builder for LangChain/LangGraph agents. Workflows are JSON definitions compiled to LangGraph StateGraphs. This guide covers the rules the canned builder tools don't teach. For the live catalog always call list_node_types, get_node_schema(type), and list_middleware_types - they read the real registry.

Workflow definition shape

{
  "state": {"messages": {"type": "list[message]", "reducer": "add_messages"},
             "intent": {"type": "str", "reducer": "last"}},
  "entry_node": "start",
  "nodes": [{"id": "start", "type": "start", "config": {}, "position": {"x": 40, "y": 200}}],
  "edges": [{"source": "start", "target": "..."}]
}

Rules:

• Exactly one start node; at least one end node; every node reachable; a path must reach end.
• Every state key a node WRITES must be declared in state (LangGraph rejects undeclared writes). create_custom_workflow auto-declares keys for known node configs, but declare custom output_keys yourself. Types: str, int, float, bool, json, list[str], list[json], list[message]. Reducers: last (overwrite), add (append lists), merge (dict merge), add_messages (chat history).
• Messages flow on the messages channel; nodes append, never replace.

Routing patterns

• Triage first (almost every support/chatbot graph): right after start, classify the message into at least general vs support, then router it. Send general (greetings, smalltalk, "what can you do?", capability/meta questions) to a small friendly agent that answers directly and goes to end; route only support into the retrieval/ticket pipeline. Without this, greetings and meta questions fall through retrieval, miss, and dead-end at a "no relevant data → create a ticket" path - a bad first impression. Shape: start → classify(general|support) → router → {general: greeter_agent → end, support: retrieval → … → end}. (Simpler alt: one front agent with a knowledge_search tool that both chats and answers.)
• Single intent: classifier (labels, output_key=intent) → router (expression=intent, cases {label: node_id}, default=fallback_node). Case KEYS are the exact VALUES the expression takes, not display labels.
• ALWAYS give routers a default - with no default, an unmatched value silently ends the run with no answer.
• MULTI-INTENT (a question with several asks): classifier multi_label: true writes a LIST to state (declare it list[str]); router multi: true routes to EVERY matching case in parallel. All branches then converge on ONE synthesizer agent node before end - its prompt: "compose the partial answers above into one coherent reply". Without a synthesizer the user sees only the last branch's answer.
• Simpler multi-intent alternative (preferred for support bots): ONE agent with config.knowledge enabled (rag and/or qa) plus any REST tools. The agent searches the KB once per sub-question and composes one answer itself. Fewer nodes, no fan-out needed.
• Conditional on retrieval success: retrieval route_key writes "yes"/"no"; human decisions: human_input output_key writes the decision string.