From 4f7059788d81eba46ebea583ddbf72efc2822fac Mon Sep 17 00:00:00 2001 From: Michael Date: Sun, 2 Aug 2026 17:01:43 +0200 Subject: [PATCH] docs: update AGENTS.md with respond tool and ModelRetry patterns --- AGENTS.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) 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.