docs: add SETUP.MD

PRODEV-624

Author: giuliastf

SETUP.MD

@@ -0,0 +1,146 @@
+# SETUP.MD
+
+This file documents how to provision a clean development environment for the five packages in this repo (`uipath-agent-framework`, `uipath-google-adk`, `uipath-llamaindex`, `uipath-openai-agents`, `uipath-pydantic-ai`), run the build, execute the tests, and validate a sample code change end-to-end. It is intended both as a quick reference for human contributors and as a structured guide for automated environment-setup tooling.
+
+## Prerequisites
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/) 0.5+
+
+### Supported platforms
+
+`uv` is shell- and OS-agnostic, so the commands below run unchanged on every supported platform:
+
+- [x] Linux
+- [x] Windows
+- [x] macOS
+
+## Environment Variables
+
+### Standard
+
+None of the common shared environment variables (e.g. `AZURE_DEVOPS_PAT`, `GH_NPM_REGISTRY_TOKEN`) are required for environment setup, build, or unit tests.
+
+### Project-specific
+
+None. The unit-test suites under the `Test` section below run fully offline and require no external authentication.
+
+> **All commands below must be run from the repository root.** The `uv --directory packages/<name>` invocations resolve each subpackage relative to the current working directory. The first line of `## Setup` enforces this by `cd`-ing to the git root.
+
+## Setup
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+python3 -m pip install --upgrade uv
+
+# Sync all five packages (each is independent)
+uv --directory packages/uipath-agent-framework sync --all-extras
+uv --directory packages/uipath-google-adk sync --all-extras
+uv --directory packages/uipath-llamaindex sync --all-extras
+uv --directory packages/uipath-openai-agents sync --all-extras
+uv --directory packages/uipath-pydantic-ai sync --all-extras
+```
+
+## Verify Setup
+
+```bash
+uv --version
+uv --directory packages/uipath-pydantic-ai run python --version
+uv --directory packages/uipath-agent-framework run python -c "import uipath_agent_framework; print('uipath-agent-framework ok')"
+uv --directory packages/uipath-google-adk run python -c "import uipath_google_adk; print('uipath-google-adk ok')"
+uv --directory packages/uipath-llamaindex run python -c "import uipath_llamaindex; print('uipath-llamaindex ok')"
+uv --directory packages/uipath-openai-agents run python -c "import uipath_openai_agents; print('uipath-openai-agents ok')"
+uv --directory packages/uipath-pydantic-ai run python -c "import uipath_pydantic_ai; print('uipath-pydantic-ai ok')"
+```
+
+## Build
+
+N/A
+
+## Test
+
+```bash
+uv --directory packages/uipath-agent-framework run pytest
+uv --directory packages/uipath-google-adk run pytest
+uv --directory packages/uipath-llamaindex run pytest
+uv --directory packages/uipath-openai-agents run pytest
+uv --directory packages/uipath-pydantic-ai run pytest
+```
+
+## Sample Code Change
+
+### The change
+
+Add a new `agent_count` property to `PydanticAiConfig` in `packages/uipath-pydantic-ai/src/uipath_pydantic_ai/runtime/config.py`, immediately after the existing `entrypoint` property:
+
+```python
+@property
+def agent_count(self) -> int:
+    """Number of agents defined in the configuration."""
+    return len(self.agents)
+```
+
+Then create `packages/uipath-pydantic-ai/tests/test_config_agent_count.py` with two pytest tests:
+
+```python
+"""Tests for PydanticAiConfig.agent_count."""
+
+import json
+from pathlib import Path
+
+from uipath_pydantic_ai.runtime.config import PydanticAiConfig
+
+
+def test_agent_count_single(tmp_path: Path) -> None:
+    config_path = tmp_path / "pydantic_ai.json"
+    config_path.write_text(json.dumps({"agents": {"main": "main:agent"}}))
+    cfg = PydanticAiConfig(str(config_path))
+    assert cfg.agent_count == 1
+
+
+def test_agent_count_multiple(tmp_path: Path) -> None:
+    config_path = tmp_path / "pydantic_ai.json"
+    config_path.write_text(
+        json.dumps(
+            {
+                "agents": {
+                    "alpha": "alpha:agent",
+                    "beta": "beta:agent",
+                    "gamma": "gamma:agent",
+                }
+            }
+        )
+    )
+    cfg = PydanticAiConfig(str(config_path))
+    assert cfg.agent_count == 3
+```
+
+### Verification
+
+```bash
+uv --directory packages/uipath-pydantic-ai run pytest tests/test_config_agent_count.py -v
+```
+
+## Test with a real UiPath Coded Agent
+
+The unit tests above are necessary but not sufficient — they don't exercise the package end-to-end through a real agent. The flow below validates changes against a live runtime:
+
+1. Apply the code changes locally.
+2. Run the unit tests (see the `Sample Code Change` section above).
+3. Scaffold a coded UiPath agent (PydanticAI / OpenAI / Google ADK / LlamaIndex / Agent Framework, matching the package you changed) that exercises the changed code path.
+4. In the downstream project's `pyproject.toml`, add this local library as an editable dependency (substitute the package you changed):
+
+   ```toml
+   [tool.uv.sources]
+   uipath-pydantic-ai = { path = "../path/to/uipath-integrations-python/packages/uipath-pydantic-ai", editable = true }
+   ```
+
+5. Exercise the new behavior end-to-end:
+
+   ```bash
+   uv run uipath run <agent-name> --input '{...}'
+   ```
+
+6. (Optional) Open a PR and apply the `build:dev` label — this publishes the development version to Test PyPI.
+7. The PR description is updated automatically with instructions for pointing the downstream agent at the Test PyPI dev version.
+8. Push the dev version to UiPath with [`uipath push`](https://uipath.github.io/uipath-python/cli/#push), then deploy it to Orchestrator or Studio Web with [`uipath deploy`](https://uipath.github.io/uipath-python/cli/#deploy), and run it in cloud to confirm the changes behave correctly against the real platform.

packages/uipath-agent-framework/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-agent-framework"
-version = "0.0.13"
+version = "0.0.12"
 description = "Python SDK that enables developers to build and deploy Microsoft Agent Framework agents to the UiPath Cloud Platform"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -10,7 +10,7 @@ dependencies = [
     "aiosqlite>=0.20.0",
     "openinference-instrumentation-agent-framework>=0.1.0",
     "uipath>=2.10.0, <2.11.0",
-    "uipath-runtime>=0.11.0, <0.12.0",
+    "uipath-runtime>=0.10.0, <0.11.0",
 ]
 classifiers = [
     "Intended Audience :: Developers",

packages/uipath-agent-framework/tests/test_hitl_e2e.py

@@ -71,7 +71,6 @@ def __init__(self, auto_approve: bool = True):
         self.auto_approve = auto_approve
         self.interrupts: list[UiPathResumeTrigger] = []
         self.messages: list[Any] = []
-        self.executing_tool_calls: list[tuple[str, dict[str, Any] | None]] = []
 
     async def connect(self) -> None:
         pass
@@ -85,13 +84,6 @@ async def emit_message_event(self, message_event: Any) -> None:
     async def emit_interrupt_event(self, resume_trigger: UiPathResumeTrigger) -> None:
         self.interrupts.append(resume_trigger)
 
-    async def emit_executing_tool_call_event(
-        self,
-        tool_call_id: str,
-        tool_input: dict[str, Any] | None = None,
-    ) -> None:
-        self.executing_tool_calls.append((tool_call_id, tool_input))
-
     async def emit_exchange_end_event(self) -> None:
         pass
 

packages/uipath-agent-framework/uv.lock

@@ -1,14 +1,14 @@
 [project]
 name = "uipath-google-adk"
-version = "0.0.8"
+version = "0.0.7"
 description = "Python SDK that enables developers to build and deploy Google ADK agents to the UiPath Cloud Platform"
 readme = "README.md"
 requires-python = ">=3.11"
 dependencies = [
     "google-adk>=1.25.1",
     "openinference-instrumentation-google-adk>=0.1.9",
     "uipath>=2.10.0, <2.11.0",
-    "uipath-runtime>=0.11.0, <0.12.0",
+    "uipath-runtime>=0.10.0, <0.11.0",
 ]
 classifiers = [
     "Intended Audience :: Developers",