chore: add template agent

Author: radu-mocanu

template/.agent/CLI_REFERENCE.md

@@ -0,0 +1,92 @@
+## Required Agent Structure
+
+**IMPORTANT**: All UiPath coded agents MUST follow this standard structure unless explicitly specified otherwise by the user.
+
+### Required Components
+
+Every agent implementation MUST include these three Pydantic models:
+
+```python
+from pydantic import BaseModel
+
+class Input(BaseModel):
+    """Define input fields that the agent accepts"""
+    # Add your input fields here
+    pass
+
+class State(BaseModel):
+    """Define the agent's internal state that flows between nodes"""
+    # Add your state fields here
+    pass
+
+class Output(BaseModel):
+    """Define output fields that the agent returns"""
+    # Add your output fields here
+    pass
+```
+
+### Required LLM Initialization
+
+Unless the user explicitly requests a different LLM provider, always use `UiPathChat`:
+
+```python
+from uipath_langchain.chat import UiPathChat
+
+llm = UiPathChat(model="gpt-4.1-mini-2025-04-14", temperature=0.7)
+```
+
+**Alternative LLMs** (only use if explicitly requested):
+- `ChatOpenAI` from `langchain_openai`
+- `ChatAnthropic` from `langchain_anthropic`
+- Other LangChain-compatible LLMs
+
+### Standard Agent Template
+
+Every agent should follow this basic structure:
+
+```python
+from langchain_core.messages import SystemMessage, HumanMessage
+from langgraph.graph import START, StateGraph, END
+from uipath_langchain.chat import UiPathChat
+from pydantic import BaseModel
+
+# 1. Define Input, State, and Output models
+class Input(BaseModel):
+    field: str
+
+class State(BaseModel):
+    field: str
+    result: str = ""
+
+class Output(BaseModel):
+    result: str
+
+# 2. Initialize UiPathChat LLM
+llm = UiPathChat(model="gpt-4.1-mini-2025-04-14", temperature=0.7)
+
+# 3. Define agent nodes (async functions)
+async def process_node(state: State) -> State:
+    response = await llm.ainvoke([HumanMessage(state.field)])
+    return State(field=state.field, result=response.content)
+
+async def output_node(state: State) -> Output:
+    return Output(result=state.result)
+
+# 4. Build the graph
+builder = StateGraph(State, input=Input, output=Output)
+builder.add_node("process", process_node)
+builder.add_node("output", output_node)
+builder.add_edge(START, "process")
+builder.add_edge("process", "output")
+builder.add_edge("output", END)
+
+# 5. Compile the graph
+graph = builder.compile()
+```
+
+**Key Rules**:
+1. Always use async/await for all node functions
+2. All nodes (except output) must accept and return `State`
+3. The final output node must return `Output`
+4. Use `StateGraph(State, input=Input, output=Output)` for initialization
+5. Always compile with `graph = builder.compile()`

template/.agent/REQUIRED_STRUCTURE.md

@@ -0,0 +1,21 @@
+# Agent Code Patterns Reference
+
+This document provides practical code patterns for building UiPath coded agents using LangGraph and the UiPath Python SDK.
+
+---
+
+## Documentation Structure
+
+This documentation is split into multiple files for efficient context loading. Load only the files you need:
+
+1. **@.agent/REQUIRED_STRUCTURE.md** - Agent structure patterns and templates
+   - **When to load:** Creating a new agent or understanding required patterns
+   - **Contains:** Required Pydantic models (Input, State, Output), LLM initialization patterns, standard agent template
+
+2. **@.agent/SDK_REFERENCE.md** - Complete SDK API reference
+   - **When to load:** Calling UiPath SDK methods, working with services (actions, assets, jobs, etc.)
+   - **Contains:** All SDK services and methods with full signatures and type annotations
+
+3. **@.agent/CLI_REFERENCE.md** - CLI commands documentation
+   - **When to load:** Working with `uipath init`, `uipath run`, or `uipath eval` commands
+   - **Contains:** Command syntax, options, usage examples, and workflows

template/.agent/SDK_REFERENCE.md

@@ -0,0 +1 @@
+@AGENTS.md

template/AGENTS.md

@@ -0,0 +1,119 @@
+# UiPath LangGraph Template Agent
+
+A quickstart UiPath LangGraph agent. It answers user queries using live tools and optionally runs a second LLM pass to refine its own response.
+
+> **Docs:** [uipath-langchain quick start](https://uipath.github.io/uipath-python/langchain/quick_start/) — **Samples:** [uipath-langchain-python/samples](https://github.com/UiPath/uipath-langchain-python/tree/main/samples)
+
+## What it does
+
+1. **Prepares** the conversation — injects a system prompt and the user query into state
+2. **Runs a ReAct agent node** (OpenAI `gpt-4.1-mini`) that autonomously decides which tools to call and in what order
+3. **Refines the response** — if `refine=true`, a second LLM (Gemini `gemini-2.5-flash`) acts as a quality reviewer, suggests one concrete improvement, and routes back to the ReAct node for a final pass
+
+### Tools
+
+| Tool               | Description                                      |
+| ------------------ | ------------------------------------------------ |
+| `get_current_time` | Returns the current UTC date and time (ISO 8601) |
+| `web_search`       | Searches the web via DuckDuckGo                  |
+
+## Graph
+
+```mermaid
+flowchart TD
+    START --> prepare
+    prepare --> react_agent
+    react_agent --> refine
+    refine -->|"refine=true, first pass"| react_agent
+    refine -->|done| END
+```
+
+## Input / Output
+
+```json
+// Input
+{
+  "query": "What is the current UTC time and what are the latest news headlines about agentic AI today?",
+  "refine": true
+}
+
+// Output
+{
+  "result": "..."
+}
+```
+
+Set `refine: false` (default) to skip the refinement pass.
+
+## Running locally
+
+```bash
+# Run
+uv run uipath run agent --file input.json
+
+# Debug with dynamic node breakpoints
+uv run uipath debug agent --file input.json
+```
+
+## Evaluation
+
+The agent ships with a tool call order evaluator that verifies the ReAct node calls `get_current_time` **before** `web_search` when given a time-dependent query.
+
+```bash
+uv run uipath eval
+```
+
+## Actionable improvements
+
+### Add UiPath-native tools
+
+- **Read from an Orchestrator Asset** — use `sdk.assets.retrieve_async(name, folder_path="MyFolder")` to inject dynamic configuration (API keys, base URLs, feature flags) without redeploying
+- **Invoke a process** — use `sdk.processes.invoke_async(name, input_arguments, folder_path="MyFolder")` to trigger downstream RPA workflows from the agent's decision
+
+### Add Human-in-the-Loop
+
+Use the durable interrupt pattern with `CreateTask` to pause the graph mid-execution until a human completes the action in UiPath Action Center:
+
+```python
+from langgraph.types import interrupt
+from uipath.platform.common import CreateTask
+
+task_output = interrupt(CreateTask(
+    app_name="AppName",
+    app_folder_path="MyFolderPath",
+    title="Escalate Issue",
+    data={"key": "value"},
+    assignee="user@example.com",
+))
+```
+
+The graph suspends at the `interrupt` call and resumes automatically with `task_output` once the assignee completes the task.
+
+### Ground answers in your own documents
+
+Use Deep RAG to search a Context Grounding index with semantic + generative retrieval instead of the public web:
+
+```python
+from langgraph.types import interrupt
+from uipath.platform.common import CreateDeepRag
+
+result = interrupt(CreateDeepRag(
+    index_name="my-index",
+    prompt="What is the refund policy for enterprise customers?",
+    index_folder_path="MyFolderPath",
+))
+```
+
+The graph suspends, runs the Deep RAG task on UiPath, and resumes with the grounded answer.
+
+### Add guardrails
+
+Wrap the graph with input/output guardrails from `uipath_langchain.guardrails` to filter harmful prompts and validate responses before they reach the user.
+
+### Swap the web search tool
+
+Replace `DuckDuckGoSearchRun` with a UiPath Integration Service connection (e.g. Bing, Google Search API) via `sdk.connections.invoke_activity_async(...)` for more reliable, rate-limit-controlled search.
+
+### Add memory
+
+Persist conversation history across runs by storing messages in an Orchestrator bucket or Data Service entity, then loading them in the `prepare` node.

template/CLAUDE.md

@@ -0,0 +1,23 @@
+flowchart TB
+  __start__(__start__)
+  prepare(prepare)
+  refine(refine)
+  __end__(__end__)
+  __start__ --> prepare
+  prepare --> react_agent
+  react_agent --> refine
+  refine --> __end__
+  refine --> react_agent
+  subgraph react_agent [react_agent]
+    direction LR
+    __start__(__start__)
+    model(model)
+    tools(tools)
+    __end__(__end__)
+    __start__ --> model
+    model --> __end__
+    model --> model
+    model --> tools
+    tools --> __end__
+    tools --> model
+  end

template/README.md

@@ -0,0 +1,4 @@
+{
+    "version": "2.0",
+    "resources": []
+}