feat(agents): enable middleware and state_schema compatibility (issue #33217)

[Rohanvasudev1]

PR Title:
feat(agents): enable middleware and
state_schema compatibility

PR Message:

Description

Remove the artificial constraint
preventing middleware and state_schema
from being used together in
create_agent(). This enables advanced use
cases like RAG applications that need
both conversation summarization
middleware and custom state schemas for
document storage and citations.

Changes Made

• Remove assert state_schema is None
  constraint in react_agent.py
• Add state_schema parameter to
  middleware_agent.create_agent()
• Implement schema validation and
  automatic merging logic
• Add comprehensive documentation with
  RAG usage examples
• Update type annotations for merged
  schema support
• Maintain full backwards compatibility

Example Usage (Previously Impossible)

class RAGState(AgentState):
retrieved_documents:
NotRequired[list[dict]]
citations: NotRequired[list[str]]

agent = create_agent(
model="openai:gpt-4",
tools=[retrieval_tool],
middleware=[SummarizationMiddleware(m
odel=llm)], # For conversation
management
state_schema=RAGState, # For
document storage - now works!
)

Issue: Closes feature request for
middleware + state_schema compatibility

Dependencies: None - uses existing
infrastructure

[eyurtsev]

Hi @Rohanvasudev1 thanks for the PR for now we recommend introducing state via Middleware. You can subclass middleware and introduce state. We might introduce a dedicated state schema parameter yet (or we may do it via middleware decorators) still TBD

[eyurtsev]

cc @sydney-runkle we need to document how to do this next week. But also see if there's a nice shorthand to simplify this. State creation is really common for langgraph agents

[Rohanvasudev1]

@eyurtsev oh so assume there's no point in adding this feature then? Should I just leave it for now?