feat: design coded deepagents

Author: andreitava-uip

plan/review-coded-deepagents-plan.md

@@ -0,0 +1,177 @@
+# Review: Coded DeepAgents Contract And Sample
+
+## TODOs
+- [x] T01 Determine review scope and initialize the workfile
+- [x] T02 Capture conventions and reuse baseline
+- [x] T03 Select review dimensions and spawn agents
+- [x] T04 Wait for every required review agent to complete
+- [x] T05 Synthesize findings into the workfile
+- [x] T06 Finalize the findings-first review output
+
+## Scope
+
+### Target Area
+- Staged diff for the DeepAgents coded-agent contract and sample.
+- Exact command: `git diff --cached -- src/uipath_langchain/deepagents src/uipath_langchain/agent/advanced/agent.py src/uipath_langchain/runtime/factory.py src/uipath_langchain/runtime/runtime.py tests/deepagents tests/agent/advanced/test_create_advanced_agent_graph.py samples/coded-deepagent samples/README.md`
+
+### Entrypoints
+- `src/uipath_langchain/deepagents/agent.py`
+- `src/uipath_langchain/deepagents/backend.py`
+- `src/uipath_langchain/deepagents/metadata.py`
+- `src/uipath_langchain/runtime/factory.py`
+- `src/uipath_langchain/runtime/runtime.py`
+- `src/uipath_langchain/agent/advanced/agent.py`
+- `samples/coded-deepagent/graph.py`
+
+### Main Behaviors Or Deltas
+- Adds public `uipath_langchain.deepagents` helpers for task-mode coded DeepAgents.
+- Tags graph builders/compiled graphs with `UiPathDeepAgentRuntimeSpec`.
+- Runtime factory detects tagged graphs, creates a workspace, injects workspace path into LangGraph config, and wraps the resumable runtime in `HydrationRuntime`.
+- Advanced agent wrappers now forward `subagents`.
+- Adds a task-mode sample using typed input/output, a tool, a review subagent, and the runtime workspace contract.
+
+### Primary Risks To Examine
+- Public interface compatibility and whether the new helper exposes DeepAgents semantics accurately.
+- Runtime behavior around graph caching, workspace lifecycle, hydration scope, and config injection.
+- Whether sample dependencies and import-time behavior match existing sample conventions.
+- Test coverage for the public contract and runtime wrapping.
+- Abstraction cost from adding a new package and metadata side channel.
+
+## Conventions Baseline
+- Naming and file placement: runtime integrations live under `src/uipath_langchain/runtime`; author-facing agent helpers live under `src/uipath_langchain/agent/*`; sample folders are under `samples/<name>` with `graph.py`, `langgraph.json`, `uipath.json`, `pyproject.toml`, `README.md`, and optional `agent.mermaid`.
+- Validation and error handling: runtime factory maps load/compile errors into `LangGraphRuntimeError`; feature gaps in author helpers use explicit `NotImplementedError`.
+- Testing and verification: focused unit tests live under `tests/<area>` and often inspect runtime wrapper internals directly with mocks; async runtime tests use pytest asyncio.
+- Reuse seams to preserve: `create_advanced_agent` remains the local DeepAgents wrapper; runtime config is built centrally in `UiPathLangGraphRuntime._get_graph_config`; graph metadata helpers should avoid LangGraph internals where possible.
+- Abstraction and ownership style: small helper modules are acceptable when they isolate contracts (`metadata`) or runtime-specific adaptation (`backend`), but pass-through wrappers should earn their keep by clarifying UiPath semantics.
+
+## Selected Review Dimensions
+
+| Dimension | Status | Reason |
+| --------- | ------ | ------ |
+| Correctness | reviewed | Runtime hydration and backend factory behavior have execution-path gaps. |
+| Architecture | reviewed | New public package and runtime wrapper are reasonable, but workspace-capability signaling is incomplete. |
+| Data Contracts | reviewed | Runtime spec exposes persistence fields, but author helpers do not expose/choose the right success persistence policy. |
+| Testing | reviewed | Added unit coverage verifies tagging/config injection, but not success dehydration or runtime factory backend edge cases. |
+| Maintainability | reviewed | New modules are small and readable; unresolved behavior should be made explicit in the contract. |
+| Conventions & Reuse | reviewed | Reuses existing advanced-agent and runtime seams, but the backend factory conflicts with existing filesystem-only checks. |
+| Security | skipped | No new auth, command execution, user-controlled file path trust boundary beyond existing runtime workspace APIs. |
+| Performance | skipped | No hot path or large-data loop; runtime wrapping is per-runtime creation. |
+
+## Review Journal - By File
+
+### `src/uipath_langchain/deepagents/agent.py`
+- Adds author-facing helper functions, task-mode guardrails, default backend factory, response format defaulting, and metadata tagging.
+- Simplicity note: wraps `create_advanced_agent_graph` to give UiPath-specific runtime semantics and metadata.
+
+### `src/uipath_langchain/deepagents/backend.py`
+- Adds a DeepAgents backend factory that reads a runtime-injected configurable workspace path and returns a `FilesystemBackend`.
+- Simplicity note: small adapter around LangGraph tool runtime config.
+
+### `src/uipath_langchain/deepagents/metadata.py`
+- Adds `UiPathDeepAgentRuntimeSpec` and helpers for attaching/retrieving it on graph-like objects.
+- Simplicity note: uses object attributes as an out-of-band metadata channel.
+
+### `src/uipath_langchain/runtime/factory.py`
+- Preserves governance callback behavior while adding DeepAgents metadata propagation, workspace creation, config injection, and hydration wrapping.
+- Simplicity note: runtime creation now has an extra conditional wrapping path for tagged graphs.
+
+### `src/uipath_langchain/runtime/runtime.py`
+- Adds optional `configurable` values merged into LangGraph run config.
+- Simplicity note: direct extension point for runtime-injected config.
+
+### `src/uipath_langchain/agent/advanced/agent.py`
+- Adds `subagents` pass-through for task and conversational advanced wrappers.
+- Simplicity note: preserves existing wrapper responsibility while exposing an already supported DeepAgents parameter.
+
+### `samples/coded-deepagent/*`
+- Adds a task-mode sample using the new contract, `UiPathChat`, a tool, subagent, input JSON, configs, README, and Mermaid diagram.
+- Simplicity note: sample intentionally avoids custom bucket backend so runtime contract is the visible path.
+
+## Executive Summary
+
+**Analysis:** Independent reviewer completed. The design is close, but two contract gaps mean the sample is not ready as-is.
+
+| Dimension | Agent | Grade |
+|-----------|-------|-------|
+| Correctness | independent-reviewer | C |
+| Architecture | independent-reviewer | C |
+| Data Contracts | independent-reviewer | C |
+| Testing | independent-reviewer | C |
+| Maintainability | independent-reviewer | B |
+| Conventions & Reuse | independent-reviewer | B |
+| Security | skipped | N/A |
+| Performance | skipped | N/A |
+| **Overall** | — | **Needs Work** |
+
+**Top Risks:** Successful task-mode workspace files are not persisted with the default hydration policy; runtime-backed DeepAgents do not get the existing filesystem-only memory and input-attachment behavior.
+
+**Recommendations Priority:** Fix persistence policy first, then either make the runtime workspace backend participate in filesystem semantics or explicitly narrow the public contract.
+
+**Confidence:** Medium-high. Findings were confirmed against the staged diff and the installed `uipath.runtime.HydrationRuntime` source.
+
+**Verdict:** Needs Work.
+
+## Code Quality Rubric (0-3)
+
+| Criterion | Score | Evidence | Note |
+| --------- | ----- | -------- | ---- |
+| Single responsibility | 2 | `deepagents` modules isolate authoring, backend, and metadata helpers. | Good shape; runtime factory has the expected conditional wrapping branch. |
+| Boundaries & validation | 1 | Runtime spec allows hydration policy, but author helper does not expose it and defaults to non-success persistence. | Contract gap affects sample behavior. |
+| Typed contracts | 2 | Pydantic runtime spec and sample input/output schemas are clear. | More fields should be surfaced in helper API. |
+| Error taxonomy | 2 | Unsupported conversation modes are explicit `NotImplementedError`. | No issue found in new error handling. |
+| Determinism & state | 1 | `suspend_only` plus cleanup workspace loses successful task files. | High correctness risk. |
+| Algorithmic sanity | 2 | Config injection and metadata propagation are straightforward. | Needs backend factory path alignment. |
+| Naming & docs | 2 | Names are readable and sample explains the intended contract. | Docs currently overpromise success persistence. |
+| Minimal abstractions | 2 | New helpers are small. | Backend marker/capability abstraction may now be needed. |
+| Testability seams | 1 | Tests cover config/tagging, not success dehydration or factory-backed attachments/memory. | Add integration-style unit tests. |
+| Control flow clarity | 2 | Runtime wrapping path is understandable. | No major readability issue. |
+| Conventions & reuse | 2 | Reuses advanced agent wrapper and runtime config seams. | Filesystem-only conventions need updating for factories. |
+
+## Architecture & Behavior
+
+Retained for the final review because the change crosses authoring API, LangGraph runtime creation, and workspace hydration boundaries. A real diagram will be added only if it clarifies a finding or final risk.
+
+## Findings Catalog
+
+### High - Successful task-mode workspace files are not persisted
+
+- Evidence: `UiPathDeepAgentRuntimeSpec.hydration_policy` defaults to `suspend_only` in `src/uipath_langchain/deepagents/metadata.py:22-27`.
+- Evidence: `create_uipath_deep_agent_graph` constructs the runtime spec without exposing a `hydration_policy` override in `src/uipath_langchain/deepagents/agent.py:79-130`.
+- Evidence: runtime factory passes `HydrationPolicy(spec.hydration_policy)` into `HydrationRuntime` in `src/uipath_langchain/runtime/factory.py:347-362`.
+- Evidence: installed `HydrationRuntime._should_dehydrate` only persists successful results for `SUSPEND_OR_SUCCESS`; `SUSPEND_ONLY` persists suspended results only.
+- Impact: The sample asks the agent to write `/launch/brief.md` and `/launch/risks.md`, then return those paths. On a normal successful task run, those files are not uploaded/linked as job attachments before `Workspace.create(..., cleanup=True)` cleanup.
+- Recommendation: Make task-mode DeepAgent helpers default to `suspend_or_success`, or expose `hydration_policy` and set the sample to success persistence. Add a success-path dehydration test.
+
+### Medium - Runtime workspace backend factory bypasses existing FilesystemBackend behavior
+
+- Evidence: `create_uipath_deep_agent_graph` defaults `backend` to `create_workspace_backend_factory(...)` in `src/uipath_langchain/deepagents/agent.py:106-108`.
+- Evidence: `create_advanced_agent_graph` only enables memory when `isinstance(backend, FilesystemBackend)` in `src/uipath_langchain/agent/advanced/agent.py:75-77`.
+- Evidence: `resolve_input_attachments` rejects non-`FilesystemBackend` backends in `src/uipath_langchain/agent/advanced/utils.py:58-72`, while `transform_input_async` passes the backend value directly.
+- Impact: Default UiPath DeepAgents do not load `/memory/MEMORY.md` through `MemoryMiddleware`, and attachment-shaped inputs fail before the runtime-injected backend factory can resolve a concrete filesystem backend.
+- Recommendation: Add an explicit runtime-workspace backend capability/marker that the advanced wrapper can use for memory and attachment resolution, or document that runtime-backed helpers do not support workspace memory/input attachments yet.
+
+## Suggested Tests / Micro-Repros
+
+- Success-path hydration: run a tagged DeepAgent runtime that writes a file and returns `SUCCESSFUL`; assert `WorkspaceHydrator.dehydrate` uploads/links the file under `suspend_or_success`.
+- Backend factory memory: build a runtime-backed DeepAgent with `/memory/MEMORY.md`; assert `MemoryMiddleware` is configured for the runtime workspace backend.
+- Backend factory input attachment: use an input schema with job attachment fields and the runtime workspace backend; assert attachments are downloaded into the injected workspace path.
+
+## Fix Loop Result
+
+- Resolved the High persistence issue by defaulting UiPath DeepAgents task-mode hydration to `suspend_or_success` and exposing `hydration_policy` on the authoring helpers.
+- Resolved the prior Medium backend-factory behavior by marking the UiPath runtime workspace backend factory as filesystem-workspace capable, enabling memory for that factory, and resolving attachment downloads through runtime `RunnableConfig`.
+- Added tests for default success persistence metadata, explicit hydration-policy propagation, marked runtime workspace factory resolution, memory enablement, and attachment resolution through the marked factory.
+- Independent reviewer `019f46ec-1dfd-7210-b220-2d498891fc8a` reported: `No Major/High/Critical blockers found`.
+- Remaining lower-severity notes from that review: reject reserved `workspace_config_key` values such as `thread_id`; add an execution-path test that writes a workspace file and asserts default `suspend_or_success` dehydration/upload.
+- Verification run: `uv run pytest --no-cov tests/deepagents tests/agent/advanced/test_memory_injection.py tests/agent/advanced/test_utils.py tests/agent/advanced/test_create_advanced_agent_graph.py tests/agent/advanced/test_conversational_advanced_agent_graph.py` passed with 29 tests.
+- Verification run: `uv run pytest --no-cov tests/deepagents tests/agent/advanced/test_create_advanced_agent_graph.py tests/agent/advanced/test_memory_injection.py tests/agent/advanced/test_utils.py tests/runtime/test_factory_governance.py tests/runtime/test_runtime_unit.py tests/runtime/test_reference_context_wiring.py` passed with 82 tests.
+- Verification run: `uv run ruff check` on touched Python files and the sample graph passed.
+- Verification run: `uv run ruff format --check` on touched Python files passed.
+
+## Deferred Items
+- Full live execution of the sample requires UiPath credentials and model access.
+
+## Changelog
+- 2026-07-09 Initialized workfile with staged-diff scope, conventions baseline, selected dimensions, and pending review status.
+- 2026-07-09 Added independent reviewer findings, verified hydration behavior, and finalized review verdict.
+- 2026-07-09 Ran fix loop, patched the High issue and backend-factory behavior, verified locally, and recorded no remaining Major+ blockers from independent review.

samples/README.md

@@ -6,6 +6,9 @@ This sample demonstrates a simple LangGraph agent that performs basic arithmetic
 ## [Chat agent](chat-agent)
 This sample shows how to build an AI assistant using LangGraph and Tavily search for movie research and recommendations.
 
+## [Coded DeepAgent](coded-deepagent)
+This sample demonstrates a task-mode coded DeepAgent using the UiPath runtime workspace contract, typed input/output, a tool, and a review subagent.
+
 ## [Company research agent](company-research-agent)
 This sample demonstrates how to create an agent that researches companies and develops outreach strategies using web search capabilities.
 

samples/coded-deepagent/README.md

@@ -0,0 +1,42 @@
+# Coded DeepAgent
+
+This sample demonstrates a task-mode coded agent built with the UiPath
+DeepAgents contract.
+
+The graph uses `create_uipath_deep_agent_graph`, which tags the graph for the
+UiPath LangGraph runtime. At runtime, UiPath creates a workspace, injects its
+path into LangGraph config, and hydrates that workspace through job
+attachments. Task-mode DeepAgents persist workspace changes when the run
+successfully completes or suspends. The sample does not configure a custom
+bucket backend.
+
+## What It Shows
+
+- Typed coded-agent input and output with Pydantic models.
+- A standard LangChain tool used by the main DeepAgent.
+- A DeepAgents subagent used for risk review.
+- Runtime-provided workspace persistence through the UiPath contract.
+
+## Files
+
+- `graph.py`: task-mode coded DeepAgent graph.
+- `input.json`: sample input payload.
+- `langgraph.json`: LangGraph entrypoint.
+- `uipath.json`: UiPath task-mode runtime configuration.
+- `agent.mermaid`: high-level graph diagram.
+
+## Requirements
+
+- UiPath runtime credentials for `UiPathChat`.
+- Access to the configured model, `gpt-4o-2024-08-06`.
+
+## Run
+
+```bash
+cd samples/coded-deepagent
+uv sync
+uipath run agent "$(cat input.json)"
+```
+
+The agent writes `/launch/brief.md` and `/launch/risks.md` in the DeepAgents
+workspace and returns those paths in `workspace_files`.

samples/coded-deepagent/agent.mermaid

@@ -0,0 +1,15 @@
+flowchart TB
+  __start__(__start__)
+  transform_input(transform_input)
+  advanced_agent(advanced_agent)
+  risk_reviewer([risk_reviewer subagent])
+  workspace[(runtime workspace)]
+  transform_output(transform_output)
+  __end__(__end__)
+
+  __start__ --> transform_input
+  transform_input --> advanced_agent
+  advanced_agent -. delegates review .-> risk_reviewer
+  advanced_agent -. writes files .-> workspace
+  advanced_agent --> transform_output
+  transform_output --> __end__

samples/coded-deepagent/graph.py

@@ -0,0 +1,94 @@
+"""Task-mode coded DeepAgent using the UiPath DeepAgents contract."""
+
+from langchain_core.tools import tool
+from pydantic import BaseModel, Field
+
+from uipath_langchain.chat import UiPathChat
+from uipath_langchain.deepagents import create_uipath_deep_agent_graph
+
+
+class BriefInput(BaseModel):
+    """Input for the product launch brief."""
+
+    product_name: str = Field(description="Name of the product or feature.")
+    audience: str = Field(description="Primary customer or user audience.")
+    objective: str = Field(description="Main launch objective.")
+    constraints: list[str] = Field(
+        default_factory=list,
+        description="Important limits, requirements, or risks to account for.",
+    )
+
+
+class BriefOutput(BaseModel):
+    """Structured launch brief returned by the agent."""
+
+    executive_summary: str
+    launch_plan: list[str]
+    risk_review: list[str]
+    workspace_files: list[str]
+
+
+@tool
+def score_launch_readiness(audience: str, constraints: list[str]) -> str:
+    """Score launch readiness from simple deterministic planning signals."""
+    score = 80
+    if len(constraints) >= 3:
+        score -= 10
+    if any("compliance" in item.lower() for item in constraints):
+        score -= 10
+    if any("deadline" in item.lower() for item in constraints):
+        score -= 5
+    return f"Launch readiness for {audience}: {max(score, 35)}/100"
+
+
+MODEL = UiPathChat(model="gpt-4o-2024-08-06", temperature=0)
+
+RISK_REVIEWER_PROMPT = """You are a launch risk reviewer.
+Review the proposed launch plan for practical delivery risks, compliance gaps,
+unclear ownership, and missing follow-up work. Return concise findings that the
+main agent can incorporate into the final brief."""
+
+RISK_REVIEWER = {
+    "name": "risk_reviewer",
+    "description": "Reviews launch plans for execution risks and missing safeguards.",
+    "system_prompt": RISK_REVIEWER_PROMPT,
+    "model": MODEL,
+}
+
+SYSTEM_PROMPT = """You are a product launch planning agent.
+
+Use the planning tools provided by DeepAgents. Use score_launch_readiness to get
+a deterministic readiness signal. Delegate a plan review to risk_reviewer before
+finalizing the answer.
+
+The UiPath runtime provides your DeepAgents filesystem through the tagged graph
+contract. Write these workspace files before producing the final answer:
+- /launch/brief.md with the final launch brief
+- /launch/risks.md with the risk review
+
+Return structured output matching the schema. Include the workspace file paths
+you wrote in workspace_files."""
+
+
+def build_user_message(args: dict) -> str:
+    constraints = args.get("constraints") or []
+    constraint_lines = "\n".join(f"- {item}" for item in constraints) or "- None"
+    return f"""Create a launch brief.
+
+Product: {args["product_name"]}
+Audience: {args["audience"]}
+Objective: {args["objective"]}
+Constraints:
+{constraint_lines}
+"""
+
+
+graph = create_uipath_deep_agent_graph(
+    model=MODEL,
+    input_schema=BriefInput,
+    output_schema=BriefOutput,
+    system_prompt=SYSTEM_PROMPT,
+    tools=[score_launch_readiness],
+    subagents=[RISK_REVIEWER],
+    build_user_message=build_user_message,
+)