Merge pull request #226 from UiPath/feat/generate_agents_md

feat(AGENTS.md): generate the AGENTS.md file

Author: radu-mocanu

pyproject.toml

@@ -1,11 +1,11 @@
 [project]
 name = "uipath-langchain"
-version = "0.0.141"
+version = "0.0.142"
 description = "UiPath Langchain"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
 dependencies = [
-    "uipath>=2.1.96, <2.2.0",
+    "uipath>=2.1.101, <2.2.0",
     "langgraph>=0.5.0, <0.7.0",
     "langchain-core>=0.3.34",
     "langgraph-checkpoint-sqlite>=2.0.3",

src/uipath_langchain/_cli/cli_init.py

@@ -1,9 +1,14 @@
 import asyncio
+import importlib.resources
 import json
 import os
+import shutil
 import uuid
+from collections.abc import Generator
+from enum import Enum
 from typing import Any, Callable, Dict, overload
 
+import click
 from langgraph.graph.state import CompiledStateGraph
 from uipath._cli._utils._console import ConsoleLogger
 from uipath._cli._utils._parse_ast import generate_bindings_json  # type: ignore
@@ -14,6 +19,14 @@
 console = ConsoleLogger()
 
 
+class FileOperationStatus(str, Enum):
+    """Status of a file operation."""
+
+    CREATED = "created"
+    UPDATED = "updated"
+    SKIPPED = "skipped"
+
+
 def resolve_refs(schema, root=None):
     """Recursively resolves $ref references in a JSON schema."""
     if root is None:
@@ -96,6 +109,120 @@ def generate_schema_from_graph(
     return schema
 
 
+def generate_agent_md_file(
+    target_directory: str,
+    file_name: str,
+    resource_name: str,
+    no_agents_md_override: bool,
+) -> tuple[str, FileOperationStatus] | None:
+    """Generate an agent-specific file from the packaged resource.
+
+    Args:
+        target_directory: The directory where the file should be created.
+        file_name: The name of the file should be created.
+        resource_name: The name of the resource folder where should be the file.
+        no_agents_md_override: Whether to override existing files.
+
+    Returns:
+        A tuple of (file_name, status) where status is a FileOperationStatus:
+        - CREATED: File was created
+        - UPDATED: File was overwritten
+        - SKIPPED: File exists and no_agents_md_override is True
+        Returns None if an error occurred.
+    """
+    target_path = os.path.join(target_directory, file_name)
+    will_override = os.path.exists(target_path)
+
+    if will_override and no_agents_md_override:
+        return file_name, FileOperationStatus.SKIPPED
+    try:
+        source_path = importlib.resources.files(resource_name).joinpath(file_name)
+
+        with importlib.resources.as_file(source_path) as s_path:
+            shutil.copy(s_path, target_path)
+
+        return (
+            file_name,
+            FileOperationStatus.UPDATED
+            if will_override
+            else FileOperationStatus.CREATED,
+        )
+
+    except Exception as e:
+        console.warning(f"Could not create {file_name}: {e}")
+        return None
+
+
+def generate_specific_agents_md_files(
+    target_directory: str, no_agents_md_override: bool
+) -> Generator[tuple[str, FileOperationStatus], None, None]:
+    """Generate agent-specific files from the packaged resource.
+
+    Args:
+        target_directory: The directory where the files should be created.
+        no_agents_md_override: Whether to override existing files.
+
+    Yields:
+        Tuple of (file_name, status) for each file operation, where status is a FileOperationStatus:
+        - CREATED: File was created
+        - UPDATED: File was overwritten
+        - SKIPPED: File exists and was not overwritten
+    """
+    agent_dir = os.path.join(target_directory, ".agent")
+    os.makedirs(agent_dir, exist_ok=True)
+
+    file_configs = [
+        (target_directory, "CLAUDE.md", "uipath._resources"),
+        (agent_dir, "CLI_REFERENCE.md", "uipath._resources"),
+        (agent_dir, "SDK_REFERENCE.md", "uipath._resources"),
+        (target_directory, "AGENTS.md", "uipath_langchain._resources"),
+        (agent_dir, "REQUIRED_STRUCTURE.md", "uipath_langchain._resources"),
+    ]
+
+    for directory, file_name, resource_name in file_configs:
+        result = generate_agent_md_file(
+            directory, file_name, resource_name, no_agents_md_override
+        )
+        if result:
+            yield result
+
+
+def generate_agents_md_files(options: dict[str, Any]) -> None:
+    """Generate agent MD files and log categorized summary.
+
+    Args:
+        options: Options dictionary
+    """
+    current_directory = os.getcwd()
+    no_agents_md_override = options.get("no_agents_md_override", False)
+
+    created_files = []
+    updated_files = []
+    skipped_files = []
+
+    for file_name, status in generate_specific_agents_md_files(
+        current_directory, no_agents_md_override
+    ):
+        if status == FileOperationStatus.CREATED:
+            created_files.append(file_name)
+        elif status == FileOperationStatus.UPDATED:
+            updated_files.append(file_name)
+        elif status == FileOperationStatus.SKIPPED:
+            skipped_files.append(file_name)
+
+    if created_files:
+        files_str = ", ".join(click.style(f, fg="cyan") for f in created_files)
+        console.success(f"Created: {files_str}")
+
+    if updated_files:
+        files_str = ", ".join(click.style(f, fg="cyan") for f in updated_files)
+        console.success(f"Updated: {files_str}")
+
+    if skipped_files:
+        files_str = ", ".join(click.style(f, fg="yellow") for f in skipped_files)
+        console.info(f"Skipped (already exist): {files_str}")
+
+
 async def langgraph_init_middleware_async(
     entrypoint: str,
     options: dict[str, Any] | None = None,
@@ -185,7 +312,9 @@ async def langgraph_init_middleware_async(
             try:
                 with open(mermaid_file_path, "w") as f:
                     f.write(mermaid_content)
-                console.success(f" Created '{mermaid_file_path}' file.")
+                console.success(
+                    f"Created {click.style(mermaid_file_path, fg='cyan')} file."
+                )
             except Exception as write_error:
                 console.error(
                     f"Error writing mermaid file for '{graph_name}': {str(write_error)}"
@@ -194,7 +323,10 @@ async def langgraph_init_middleware_async(
                     should_continue=False,
                     should_include_stacktrace=True,
                 )
-        console.success(f" Created '{config_path}' file.")
+        console.success(f"Created {click.style(config_path, fg='cyan')} file.")
+
+        generate_agents_md_files(options)
+
         return MiddlewareResult(should_continue=False)
 
     except Exception as e:

src/uipath_langchain/_resources/AGENTS.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

src/uipath_langchain/_resources/REQUIRED_STRUCTURE.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-4o-2024-08-06", 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-4o-2024-08-06", 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()`