feat: add develop-agent-module skill (#743)

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: cotovanu-cristian

.claude/skills/develop-agent-module/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: develop-agent-module
+description: Use when modifying, extending, or debugging anything inside the agent/ module — the ReAct agent graph, tools, guardrails, exceptions, multimodal, or wrappers. Guides clean architecture, module boundaries, and correct integration patterns. Triggers on "add a node to the agent graph", "modify routing", "add a guardrail action", "change agent state", "fix agent exceptions", "add multimodal support", or any work touching files under src/uipath_langchain/agent/.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
+---
+
+# Develop the Agent Module
+
+Guidance for working inside `src/uipath_langchain/agent/` — the ReAct agent orchestration layer.
+
+**Read first, code second.** Before changing anything, read the existing code in the subsystem you're modifying. Follow established patterns unless you have a concrete reason to diverge — and if you do, discuss it first.
+
+## Architectural Constraints
+
+The agent module is designed so that subsystems can be composed into different loop patterns without coupling:
+
+- **`tools/` must not know about the loop.** Tools are standalone capabilities — they receive input, do work, return output. They must not import from `react/` (except shared types in `react/types.py` and helpers in `react/utils.py`). A tool should work regardless of whether it's orchestrated by a ReAct loop, a plan-and-execute loop, or something else entirely.
+- **`guardrails/` must not know about the loop.** Guardrail evaluation and actions are generic validation — they inspect data, return pass/fail, and execute actions. The *wiring* of guardrails into a specific loop happens in `react/guardrails/`, not in `guardrails/` itself.
+- **`react/` is one loop implementation, not the only possible one.** It owns graph construction, routing, and node lifecycle. It composes tools and guardrails but those subsystems don't depend back on it.
+- **`exceptions/`, `multimodal/`, `messages/` are fully standalone.** They have no knowledge of the loop or each other.
+- **`wrappers/` are loop-agnostic but impose state contracts.** They don't import the loop, but they do depend on specific state fields existing (e.g., `inner_state.job_attachments`). When adding a wrapper, ensure the state fields it expects are documented in `react/types.py`.
+
+This means: if you're adding a tool and find yourself importing from `react/agent.py` or `react/router.py`, you're coupling the tool to the loop. Stop and rethink.
+
+## Upstream Types (`uipath.agent` in uipath-python)
+
+Agent definition models, resource configs, guardrail models, flow control tools (`END_EXECUTION_TOOL`, `RAISE_ERROR_TOOL`), and prompt templates all live in `uipath.agent.models.agent` in uipath-python. This package consumes them — it doesn't define them.
+
+Key connection points:
+- `tools/tool_factory.py` dispatches on `isinstance(resource, AgentXResourceConfig)` — each resource config type maps to a tool factory
+- `guardrails/guardrails_factory.py` converts `AgentGuardrail` models into executable `(BaseGuardrail, GuardrailAction)` pairs
+
+**Adding a new tool type requires the `AgentXResourceConfig` to exist in uipath-python first.** If it doesn't, that's a cross-package change.
+
+## Where Does My Change Go?
+
+| Change | Owner | Read first |
+|--------|-------|------------|
+| New tool type | `tools/<name>_tool.py` | `tools/process_tool.py` (simple), `tools/context_tool.py` (complex) |
+| New guardrail action | `guardrails/actions/<name>_action.py` | `guardrails/actions/log_action.py` (simple), `guardrails/actions/escalate_action.py` (complex) |
+| New graph node | `react/<name>_node.py` | `react/llm_node.py`, `react/types.py` |
+| Routing changes | `react/router.py` or `react/router_conversational.py` | Both routers + `react/utils.py` |
+| State fields | `react/types.py` + `react/reducers.py` | Existing state classes and their reducers |
+| Error codes | `exceptions/exceptions.py` | Existing error code enums |
+| Tool wrapper | `wrappers/` | `wrappers/job_attachment_wrapper.py` |
+| Multimodal | `multimodal/` | `multimodal/invoke.py` |
+| Guardrail evaluation | `guardrails/guardrail_nodes.py` | Existing scope-specific node creators |
+| Guardrail subgraph wiring | `react/guardrails/guardrails_subgraph.py` | Existing subgraph creators |
+
+After adding a new tool: **also** register it in `tools/tool_factory.py` → `_build_tool_for_resource()` and export from `tools/__init__.py`.
+
+After adding a new guardrail action: **also** register it in `guardrails/guardrails_factory.py` → `build_guardrails_with_actions()` and export from `guardrails/actions/__init__.py`.
+
+---
+
+## Import Rules (Non-Obvious)
+
+These are the constraints you can't discover by reading any single file:
+
+**`react/agent.py` is the composition root.** It imports from everywhere in agent/. Nothing else may import from `react/agent.py` — only the runtime layer above does.
+
+```
+react/agent.py  ←  react/*, tools/, guardrails/, exceptions/
+tools/*         ←  tools/*, react/types, react/utils, exceptions/, chat.hitl
+guardrails/*    ←  guardrails/*, react/types, exceptions/, messages/
+wrappers/*      ←  react/*, tools/tool_node
+multimodal/*    ←  standalone (uipath._utils._ssl_context only)
+exceptions/*    ←  standalone (uipath.runtime.errors, uipath.platform.errors)
+messages/*      ←  standalone (langchain_core.messages)
+```
+
+**Hard rules:**
+- tools/ and guardrails/ must **never** import from `react/agent.py` — import from `react/types.py` or `react/utils.py` instead
+- agent/ must **never** import from downstream consumers — the dependency flows one way into this package, not out
+- No direct `os.environ` reads — dependencies come through constructor parameters or SDK instances
+
+---
+
+## State Management Rules
+
+The LangGraph state system has sharp edges. These rules prevent silent corruption:
+
+- **Always return state updates as dicts from nodes** — LangGraph passes copies, so mutations on the state object are silently lost. The only way to update state is by returning dicts that the reducers merge.
+- New fields on `InnerAgentGraphState` **must** have a reducer via `Annotated[T, reducer_func]` — use `merge_dicts` for dicts, `merge_objects` for nested BaseModel fields.
+- To append messages: return `{"messages": [new_msg]}` — the `add_messages` reducer handles it.
+- To **replace** messages (rare): use `Overwrite` from `langgraph.types`.
+- `tools_storage` (in inner_state) is the shared key-value store for inter-tool communication — use it instead of inventing new state fields.
+
+---
+
+## Anti-Patterns
+
+| Don't | Do Instead |
+|-------|------------|
+| Import from `react/agent.py` in tools/ or guardrails/ | Import from `react/types.py` or `react/utils.py` |
+| Put routing logic in tool nodes | Return results; let the router decide |
+| Mutate state object in a node (silently lost) | Return `{"messages": [...]}` dicts; let reducers merge |
+| Read env vars inside tool/node functions | Accept config through factory parameters |
+| Create tool classes | Use `create_<name>_tool()` factory functions |
+| Add `AgentGraphState` fields without reducers | Use `Annotated[T, reducer_func]` |
+| Catch and silently swallow exceptions | Re-raise or wrap with `AgentRuntimeError` |
+| Use `asyncio.run()` for sync→async bridging | Use `asyncio.run_coroutine_threadsafe()` |
+| Add guardrail eval logic outside `guardrail_nodes.py` | Create a scope-specific creator there |
+| Put HITL logic in tool functions | Set `REQUIRE_CONVERSATIONAL_CONFIRMATION` metadata on the tool |
+| Skip registering new tools in `tool_factory.py` | Always add dispatch entry in `_build_tool_for_resource()` |
+
+---
+
+## Exception Handling
+
+Use the structured error types in `exceptions/` — never raise raw `Exception`, `ValueError`, or `RuntimeError`:
+
+- **Runtime errors** (during execution): `AgentRuntimeError(code=AgentRuntimeErrorCode.X, title=..., detail=..., category=...)`
+- **Startup errors** (during init): `AgentStartupError(code=AgentStartupErrorCode.X, title=..., detail=..., category=...)`
+- **HTTP errors from platform calls**: catch `EnrichedException`, map via `raise_for_enriched()` in `exceptions/helpers.py`
+- **LLM provider errors**: handled by `raise_for_provider_http_error()` in `exceptions/licensing.py`
+- Always chain exceptions: `raise AgentRuntimeError(...) from e`
+
+## Testing
+
+Tests live in `tests/agent/` mirroring the source structure. Before writing new tests, read `tests/agent/tools/test_process_tool.py` for the standard fixture and mocking patterns.
+
+Key conventions:
+- Use `pytest-httpx` (`HTTPXMock`) for HTTP mocking — never make real network calls
+- Use `monkeypatch.setenv()` / `monkeypatch.delenv()` for environment isolation
+- Async tests need no decorator (`asyncio_mode = "auto"`)
+- All test functions require type annotations
+- Mock SDK dependencies via `AsyncMock` / `MagicMock` — tools and nodes receive them through constructor params
+
+---
+
+## Verification
+
+After making changes:
+
+- [ ] Code is in the correct subsystem (see table above)
+- [ ] No imports from `react/agent.py` in tools/, guardrails/, or other leaf modules
+- [ ] No imports from downstream consumers
+- [ ] New state fields have reducers
+- [ ] Node functions return dicts (not mutating state)
+- [ ] New tools/actions registered in their respective factories
+- [ ] New exports added to the subsystem's `__init__.py` and `__all__`
+- [ ] `uv run ruff check src/uipath_langchain/agent/` passes
+- [ ] `uv run mypy src/uipath_langchain/agent/` passes
+- [ ] `uv run pytest tests/agent/` passes