|
| 1 | +# run_agent_with_ontology.py |
| 2 | + |
| 3 | +A standalone CLI helper that loads an OWL ontology, injects it into the Data |
| 4 | +Fabric **write** tool's fetch path, and runs a coded ReAct agent against a Data |
| 5 | +Fabric entity set. |
| 6 | + |
| 7 | +This is a developer helper, not part of the shipped package. No tests cover it. |
| 8 | + |
| 9 | +## What it does |
| 10 | + |
| 11 | +1. **Compiles + prints the ontology up front.** It runs |
| 12 | + `compile_ontology()` on your `.ttl` and prints the extracted facts — |
| 13 | + `entity_access`, `hitl_operations`, `state_fields`, `reference_fields`, |
| 14 | + `measure_fields`, `entity_relationships`. This validates the `.ttl` and |
| 15 | + shows exactly what the ontology contributes before any agent work. This step |
| 16 | + needs **no network**. |
| 17 | +2. **Bridges a not-yet-shipped platform method** (see below). |
| 18 | +3. Builds the Data Fabric read + write tools, force-initializes the write |
| 19 | + handler, prints the compiled ontology actually in use and the generated |
| 20 | + write tool description, then (unless `--dry-run`) runs the agent. |
| 21 | + |
| 22 | +## The monkeypatch bridge — and why it exists |
| 23 | + |
| 24 | +The runtime's `DataFabricWriteHandler._maybe_compile_ontology()` fetches the |
| 25 | +ontology by calling: |
| 26 | + |
| 27 | +```python |
| 28 | +entities_service.get_ontology_file_async("owl") |
| 29 | +``` |
| 30 | + |
| 31 | +**The platform does not yet expose that method.** Verified: the attribute is |
| 32 | +absent on |
| 33 | +`uipath.platform.entities._entities_service.EntitiesService`. When it is |
| 34 | +missing, the handler degrades to the metadata-only write path |
| 35 | +(`_compiled_ontology` stays `None`). |
| 36 | + |
| 37 | +This CLI closes that gap by monkeypatching the method onto the class **before** |
| 38 | +the handler runs: |
| 39 | + |
| 40 | +``` |
| 41 | +uipath.platform.entities._entities_service.EntitiesService.get_ontology_file_async |
| 42 | +``` |
| 43 | + |
| 44 | +The injected async method returns the text of your `--ontology` file for the |
| 45 | +`"owl"` file type. The handler's own `_maybe_compile_ontology` then discovers |
| 46 | +it via `getattr`, compiles it, and uses it in write validation and the write |
| 47 | +tool description — exactly as it will behave once the platform ships the real |
| 48 | +method. |
| 49 | + |
| 50 | +A class-level patch is used (not an instance patch) because the handler |
| 51 | +constructs `UiPath()` internally and resolves the `EntitiesService` lazily, so |
| 52 | +the instance is never reachable from the CLI. If the class patch ever fails, |
| 53 | +the script falls back to setting `handler._compiled_ontology` directly and |
| 54 | +rebuilding the description. |
| 55 | + |
| 56 | +After initialization the script prints either: |
| 57 | + |
| 58 | +- `ontology ACTIVE` — the handler compiled and is using the ontology, or |
| 59 | +- `ontology INACTIVE (fell back to metadata-only)` — it did not. |
| 60 | + |
| 61 | +## Run it offline (dry-run) |
| 62 | + |
| 63 | +The ontology compilation + fact printing needs no network. Building tools / |
| 64 | +resolving entities **does** need UiPath auth + network; in `--dry-run` that |
| 65 | +failure is caught and the script still prints the standalone ontology facts and |
| 66 | +exits `0`. |
| 67 | + |
| 68 | +```bash |
| 69 | +uv run python scripts/run_agent_with_ontology.py \ |
| 70 | + --ontology /Users/harshit/DF-Agents-2/df-agent-os/roadmap/p1-owl-write-extension.ttl \ |
| 71 | + --entity-set scripts/sample_refund_entity_set.json \ |
| 72 | + --prompt "test" --dry-run |
| 73 | +``` |
| 74 | + |
| 75 | +## Run it for real (against staging) |
| 76 | + |
| 77 | +1. `uip login` (sets `UIPATH_ACCESS_TOKEN`, `UIPATH_URL`, |
| 78 | + `UIPATH_TENANT_ID`, `UIPATH_ORGANIZATION_ID`). |
| 79 | +2. Edit `scripts/sample_refund_entity_set.json` and replace the **placeholder |
| 80 | + fake UUIDs** (`id`, `folderId`, `referenceKey`) with the real ids for your |
| 81 | + tenant's entities. The shipped values are clearly fake and will not resolve. |
| 82 | +3. Run without `--dry-run`: |
| 83 | + |
| 84 | +```bash |
| 85 | +uv run python scripts/run_agent_with_ontology.py \ |
| 86 | + --ontology /path/to/ontology.ttl \ |
| 87 | + --entity-set scripts/sample_refund_entity_set.json \ |
| 88 | + --prompt "Process the refund for contact Jane Doe on order PO-1042" \ |
| 89 | + --model anthropic.claude-sonnet-4-5-20250929-v1:0 \ |
| 90 | + --system-prompt scripts/sample_refund_sop.txt |
| 91 | +``` |
| 92 | + |
| 93 | +## Options |
| 94 | + |
| 95 | +| Flag | Required | Description | |
| 96 | +|------|----------|-------------| |
| 97 | +| `--ontology` | yes | Path to the OWL 2 QL Turtle `.ttl` file. | |
| 98 | +| `--entity-set` | yes | JSON list of `DataFabricEntityItem` dicts (`id`, `name`, `folderId`, `referenceKey`, `description`). | |
| 99 | +| `--prompt` | yes | The user prompt for the agent. | |
| 100 | +| `--model` | no | UiPath-gateway model name. Default: `anthropic.claude-sonnet-4-5-20250929-v1:0`. | |
| 101 | +| `--system-prompt` | no | Path to a system-prompt/SOP `.txt`. Generic default when omitted. | |
| 102 | +| `--resource-name` | no | Name for the Data Fabric context resource. Default: `datafabric`. | |
| 103 | +| `--dry-run` | no | Do not call the LLM; build tools, inject the ontology, print facts + write tool description, exit. Degrades gracefully offline. | |
| 104 | + |
| 105 | +## Sample files |
| 106 | + |
| 107 | +- `sample_refund_entity_set.json` — refund hero-case entities (Customer, |
| 108 | + Contact, Order/PurchaseOrder, CustomerRisk, RefundRequest) with **placeholder |
| 109 | + fake ids**. Fill in real tenant ids to run against staging. |
| 110 | +- `sample_refund_sop.txt` — the refund SOP (RFC §4.3) as a system prompt. |
0 commit comments