Multi-Agent State Validation & Guardrails

This is a classic case of unvalidated raw text crossing an agent boundary — the Writer agent is choking because it's receiving something like "Sure! Here are the keywords: {...}" instead of a clean payload it can parse. Here's how to fix it with the guardrail pattern.

1. Architectural Topography

               +-----------------------+

               |   Research Agent (N)  |

               +-----------+-----------+

                           |

                           v (Outputs raw text w/ embedded JSON)
             +-------------+-------------+

             |  Deterministic State Gate | <------------------------+

             +-------------+-------------+                          |

                           |                                        |

                 [Validates as KeywordPayload?]                     |
                /                         \                         |
             (Yes)                        (No)                      |
              /                             \                       |
             v                               v                      |
   +-------------------+          +---------------------+           |

   | Context Pruner /  |          | Retry Counter       |           |
   | State Extraction  |          | Under Cap (N <= 3)? |           |

   +---------+---------+          +----------+----------+           |

             |                               |                      |

             v                               | (Yes)                | (No)
   +-------------------+                     v                      v

   | SEO Writer (N+1)  |          +---------------------+ +-------------------+

   +-------------------+          | Inject Error Trace  | | Raise Exception / |

                                  | Loop Back to N       | | Halt Pipeline     |

                                  +----------+----------+ +-------------------+

                                             |

                                             +----------------------+

The core fix: the Writer agent should

never see the Researcher's raw output. It only ever receives a payload that has already passed through the AgentStateGate.

2. Reference Code Implementation

Define a strict schema for exactly what the Writer needs — nothing more:

from typing import List
from pydantic import BaseModel, ConfigDict, Field

class KeywordPayload(BaseModel):
    """
    The ONLY shape of data the Writer Agent is allowed to receive.
    extra='forbid' catches cases where the Researcher hallucinates 
    extra fields (e.g. 'notes', 'confidence_level') not in this contract.
    """
    model_config = ConfigDict(extra="forbid")
    
    primary_keyword: str = Field(..., min_length=1)
    secondary_keywords: List[str] = Field(default_factory=list, max_length=15)
    search_intent: str  # e.g. "informational", "transactional", "navigational"
    target_word_count: int = Field(default=1200, ge=300, le=5000)

Now wrap the Researcher call with the guardrail engine from the skill:

from agent_state_gate import AgentStateGate, EscalateToHumanError  # from skill reference code

def research_agent_call(messages: list[dict]) -> str:
    """
    Your actual Research Agent invocation — LangGraph node, CrewAI task, 
    raw API call, whatever framework you're using.
    """
    response = call_your_llm_framework(messages)
    return response  # raw text, possibly with conversational wrapping

def run_pipeline(topic: str):
    gate = AgentStateGate(target_schema=KeywordPayload, max_retries=3)

    initial_messages = [
        {
            "role": "system",
            "content": (
                "You are a Research Agent. Return ONLY a JSON object matching "
                "this schema, with no conversational text, preamble, or markdown "
                "fences:\n" + KeywordPayload.model_json_schema().__repr__()
            )
        },
        {"role": "user", "content": f"Research keywords for the topic: {topic}"}
    ]

    try:
        # This blocks conversational bloat from ever reaching the Writer
        validated_payload = gate.execute_with_guardrails(
            agent_invoke_fn=research_agent_call,
            initial_messages=initial_messages
        )
    except EscalateToHumanError as e:
        # Ceiling hit — don't let a malformed payload limp forward
        print(f"HITL escalation required: {e}")
        return None

    # Only the pruned, validated dict crosses into the Writer's context
    return seo_writer_agent(validated_payload)

def seo_writer_agent(payload: dict) -> str:
    """
    The Writer never touches raw Researcher output — only this clean dict,
    matching KeywordPayload exactly.
    """
    writer_messages = [
        {"role": "system", "content": "You are an SEO Blog Writer Agent."},
        {"role": "user", "content": f"Write a blog post using this brief: {json.dumps(payload)}"}
    ]
    return call_your_llm_framework(writer_messages)

The _extract_json method in AgentStateGate (from the skill) already handles the most common failure pattern — a Researcher saying "Sure, here's what I found:\njson\n{...}" — by stripping markdown fences and regex-matching the outermost {...} block before validation even runs. That alone probably fixes 80% of your crashes.

3. Edge Case Remediation Matrix

One practical tip specific to your setup: put the schema itself in the Researcher's

original system prompt (not just the retry-correction message) via KeywordPayload.model_json_schema(). Most "conversational wrapper" crashes come from the model never being told the exact contract up front — the correction loop is a safety net, not your first line of defense.