diff --git a/AGENTS.md b/AGENTS.md index 429486e..d2ab904 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -43,14 +43,15 @@ - **Composable**: Write small, modular agents and tools with clear interfaces and dependency injection (`RunContext`). - **Unix-like**: Each agent or tool has a single responsibility and does one thing well. -- **Predictable**: Use structured outputs (`result_type` with Pydantic models) to eliminate ambiguous text responses. +- **Predictable**: Require agents to submit final outputs via dedicated `reply` / `respond` tools accepting structured Pydantic models. Raise `ModelRetry` when inputs or tool usage fall short of the expected shape. - **Idiomatic**: Follow modern Python type hints (`list[str]`, `dict[str, Any]`), standard Pydantic v2 schemas, and Pydantic AI idioms. - **Domain-based**: Structure code and data around domain concepts (`NotificationDecision`, `CoordinatorDecision`, `ExecutionPlan`) rather than LLM framework mechanics. ## Pydantic AI Integration Guidelines - Use `pydantic_ai.Agent` as the primary execution engine for all AI agents. -- Define structured result schemas using Pydantic `BaseModel` for predictable output handling. +- Require agents to provide structured decisions by calling a dedicated `respond` tool that takes the response Pydantic model as an argument. +- Use `ModelRetry` (from `pydantic_ai`) inside tools or validators to force the LLM to retry when it returns raw strings or incorrect parameter shapes. - Pass runtime dependencies into tools using `pydantic_ai.RunContext` and typed dependency containers. - Register tools using `@agent.tool` or modular toolsets for clean separation of concerns.