✨ feat: add strict agent base model for schemas

- introduce AgentBaseModel with strict validation defaults

- relocate and harden schema unit tests under tests/unit_tests/common

- document structured output guidance in AGENTS.md and README variants

Resolves #9

Author: webup

AGENTS.md

@@ -0,0 +1,33 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- Core agent logic lives in `src/react_agent/` (`graph.py` orchestrates the ReAct loop); shared utilities reside in `src/common/`.
+- Shared Pydantic schemas should inherit from `src/common/basemodel.AgentBaseModel`; keep the base class in that module so `src/common/models/` stays focused on provider integrations.
+- Packaging metadata and templates are exported via `langgraph/templates/react_agent`; add new modules under `src/` and expose them through `__init__.py` as needed.
+- Tests are split into `tests/unit_tests/`, `tests/integration_tests/`, and `tests/e2e_tests/`; evaluation harnesses live in `tests/evaluations/` with scenario scripts.
+- Static assets such as screenshots or fixtures belong in `static/` or the relevant `tests/cassettes/` folder.
+
+## Build, Test, and Development Commands
+- Install all deps with `uv sync --dev`; activate env through `uv run ...` or the generated `.venv`.
+- Launch the local graph runtime with `make dev` (headless) or `make dev_ui` (opens LangGraph Studio).
+- Run targeted suites via `make test_unit`, `make test_integration`, `make test_e2e`, or `make test_all`; watch mode is available through `make test_watch_*` targets.
+- Execute evaluation scenarios through `make eval_graph`, `make eval_multiturn`, or persona/model-specific targets like `make eval_graph_qwen`.
+
+## Coding Style & Naming Conventions
+- Python 3.11+ with 4-space indentation; favor type annotations and Google-style docstrings (enforced by Ruff + pydocstyle).
+- Run `make lint` before committing; it invokes Ruff formatting/isort checks and strict MyPy over `src/`.
+- Use snake_case for modules and functions, PascalCase for classes, and uppercase ENV names; keep public tool IDs descriptive (e.g., `search_tool`).
+
+## Testing Guidelines
+- Write tests with `pytest`; mirror implementation folders (e.g., `tests/unit_tests/common/` for `src/common/`).
+- Prefer deterministic fixtures and reuse cassette data in `tests/cassettes/` for external calls.
+- For new behaviors add unit coverage first, then integration/e2e if the agent flow changes; verify locally with the nearest `make test_*` target.
+
+## Commit & Pull Request Guidelines
+- Follow the existing conventional-emoji prefix style (`📚 docs:`, `♻️ refactor:`); keep the summary imperative and under 72 chars.
+- Reference issues in the body (`Fixes #123`) and note evaluation/test results.
+- PRs should explain the change, list verification commands, and attach screenshots or trace links when UI or agent output changes.
+
+## Security & Configuration Tips
+- Keep secrets in `.env` only; never commit API keys. Update `.env.example` when adding new configuration knobs.
+- Document any external service requirements (SiliconFlow, Tavily, OpenAI) and ensure fallback behaviors when keys are absent.

README.md

@@ -185,6 +185,26 @@ async def my_custom_tool(input: str) -> str:
 # Add to the tools list in get_tools()
 ```
 
+### Define Structured Outputs
+Use [`AgentBaseModel`](./src/common/basemodel.py) when you need structured responses (LLM tool outputs or graph state). It enforces strict typing, forbids unknown fields, and supports alias-driven serialization by default:
+
+```python
+from pydantic import Field
+
+from common import AgentBaseModel
+
+
+class Answer(AgentBaseModel):
+    display_name: str = Field(alias="displayName")
+    score: float
+
+
+result = Answer(display_name="Curie", score=0.98)
+assert result.model_dump(by_alias=True) == {"displayName": "Curie", "score": 0.98}
+```
+
+Keep shared schema primitives in `src/common/basemodel.py` so provider integrations in `src/common/models/` stay focused on model client wiring.
+
 ### Add New MCP Tools
 Integrate external MCP servers for additional capabilities:
 
@@ -330,6 +350,7 @@ The template uses a modular architecture:
 
 Key components:
 - **`src/common/mcp.py`**: MCP client management for external documentation sources
+- **`src/common/basemodel.py`**: Centralizes Pydantic configuration via `AgentBaseModel` for structured tool outputs
 - **Dynamic tool loading**: Runtime tool selection based on context configuration
 - **Context system**: Centralized configuration with environment variable support
 

README_CN.md

@@ -248,6 +248,26 @@ async def my_custom_tool(input: str) -> str:
     return "工具输出"
 ```
 
+### 定义结构化输出
+当需要返回结构化响应（例如工具输出或图状态）时，请使用 [`AgentBaseModel`](./src/common/basemodel.py)。它默认启用严格类型检查、禁止未知字段，并支持字段别名序列化：
+
+```python
+from pydantic import Field
+
+from common import AgentBaseModel
+
+
+class Answer(AgentBaseModel):
+    display_name: str = Field(alias="displayName")
+    score: float
+
+
+result = Answer(display_name="居里", score=0.98)
+assert result.model_dump(by_alias=True) == {"displayName": "居里", "score": 0.98}
+```
+
+共享的 schema 基类请放在 `src/common/basemodel.py` 中，以保持 `src/common/models/` 目录专注于模型客户端集成。
+
 ### 添加新的 MCP 工具
 集成外部 MCP 服务器以获得更多功能：
 

src/common/__init__.py

@@ -1,13 +1,15 @@
 """Shared components for LangGraph agents."""
 
 from . import prompts
+from .basemodel import AgentBaseModel
 from .context import Context
 from .models import create_qwen_model, create_siliconflow_model
 from .tools import web_search
 from .utils import load_chat_model
 
 __all__ = [
     "Context",
+    "AgentBaseModel",
     "create_qwen_model",
     "create_siliconflow_model",
     "web_search",

src/common/basemodel.py

@@ -0,0 +1,20 @@
+"""Shared Pydantic base classes for structured agent outputs."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict
+
+
+class AgentBaseModel(BaseModel):
+    """Base model for structured outputs returned by LangGraph agents.
+
+    This class centralizes common configuration for schemas that are exposed to
+    LLM tool responses, ensuring consistent serialization and validation rules.
+    Downstream models should inherit from this base rather than directly from
+    ``pydantic.BaseModel``.
+    """
+
+    model_config = ConfigDict(populate_by_name=True, extra="forbid", strict=True)
+
+
+__all__ = ["AgentBaseModel"]

tests/unit_tests/common/test_basemodel.py

@@ -0,0 +1,42 @@
+"""Tests for the shared Pydantic base model used by the agent."""
+
+from __future__ import annotations
+
+import pytest
+from pydantic import Field, ValidationError
+
+from common import AgentBaseModel
+
+
+class Person(AgentBaseModel):
+    """Example structured response schema."""
+
+    name: str
+    age: int
+
+
+def test_agent_base_model_enforces_types() -> None:
+    result = Person(name="Ada", age=37)
+
+    assert result.name == "Ada"
+    assert result.age == 37
+
+    with pytest.raises(ValidationError):
+        Person(name="Ada", age="37")
+
+
+def test_agent_base_model_forbids_extra_fields() -> None:
+    with pytest.raises(ValidationError):
+        Person(name="Grace", age=35, nickname="hopper")
+
+
+def test_agent_base_model_populate_by_name() -> None:
+    class AliasExample(AgentBaseModel):
+        """Model using aliases but still accepting field names."""
+
+        display_name: str = Field(alias="displayName")
+
+    result = AliasExample(display_name="Curie")
+
+    assert result.display_name == "Curie"
+    assert result.model_dump(by_alias=True) == {"displayName": "Curie"}