Skip to content

Commit 50713d0

Browse files
gheorghitahurmuzgheorghitahurmuz
committed
feat(cli): add quickstart and new command
1 parent 450f04f commit 50713d0

5 files changed

Lines changed: 456 additions & 0 deletions

File tree

‎docs/quick_start.md‎

Lines changed: 329 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,329 @@
1+
# Quickstart Guide: UiPath LLamaIndex Agents
2+
3+
## Introduction
4+
5+
This guide provides step-by-step instructions for setting up, creating, publishing, and running your first UiPath-LLamaIndex Agent.
6+
7+
## Prerequisites
8+
9+
Before proceeding, ensure you have the following installed:
10+
11+
- Python 3.10 or higher
12+
- `pip` or `uv` package manager
13+
- A UiPath Automation Cloud account with appropriate permissions
14+
- An OpenAI API key
15+
16+
/// info
17+
**OpenAI** - Generate an OpenAI API key [here](https://platform.openai.com).
18+
///
19+
20+
## Creating a New Project
21+
22+
We recommend using `uv` for package management. To create a new project:
23+
24+
//// tab | Linux, macOS, Windows Bash
25+
26+
<!-- termynal -->
27+
28+
```shell
29+
> mkdir example
30+
> cd example
31+
```
32+
33+
////
34+
35+
//// tab | Windows PowerShell
36+
37+
<!-- termynal -->
38+
39+
```powershell
40+
> New-Item -ItemType Directory -Path example
41+
> Set-Location example
42+
```
43+
44+
////
45+
46+
//// tab | uv
47+
new: true
48+
49+
<!-- termynal -->
50+
51+
```shell
52+
# Initialize a new uv project in the current directory
53+
> uv init . --python 3.10
54+
55+
# Create a new virtual environment
56+
# By default, uv creates a virtual environment in a directory called .venv
57+
> uv venv
58+
Using CPython 3.10.16 interpreter at: [PATH]
59+
Creating virtual environment at: .venv
60+
Activate with: source .venv/bin/activate
61+
62+
# Activate the virtual environment
63+
# For Windows PowerShell/ Windows CMD: .venv\Scripts\activate
64+
# For Windows Bash: source .venv/Scripts/activate
65+
> source .venv/bin/activate
66+
67+
# Install the uipath package
68+
> uv add uipath-llamaindex
69+
70+
# Verify the uipath installation
71+
> uipath -lv
72+
uipath-llamaindex version 0.0.100
73+
```
74+
75+
////
76+
77+
//// tab | pip
78+
79+
<!-- termynal -->
80+
81+
```shell
82+
# Create a new virtual environment
83+
> python -m venv .venv
84+
85+
# Activate the virtual environment
86+
# For Windows PowerShell: .venv\Scripts\Activate.ps1
87+
# For Windows Bash: source .venv/Scripts/activate
88+
> source .venv/bin/activate
89+
90+
# Upgrade pip to the latest version
91+
> python -m pip install --upgrade pip
92+
93+
# Install the uipath package
94+
> pip install uipath-uipath-llamaindex
95+
96+
# Verify the uipath installation
97+
> uipath -lv
98+
uipath-uipath-llamaindex version 0.0.100
99+
```
100+
101+
////
102+
103+
## Create Your First UiPath Agent
104+
105+
Generate your first UiPath LLamaIndex agent:
106+
107+
<!-- termynal -->
108+
109+
```shell
110+
> uipath new my-agent
111+
⠋ Creating new agent my-agent in current directory ...
112+
✓ Created 'main.py' file.
113+
✓ Created 'llama_index.json' file.
114+
✓ Created 'pyproject.toml' file.
115+
🔧 Please ensure to define OPENAI_API_KEY in your .env file.
116+
💡 Initialize project: uipath init
117+
💡 Run agent: uipath run agent '{"topic": "UiPath"}'
118+
```
119+
120+
This command creates the following files:
121+
122+
| File Name | Description |
123+
|------------------|----------------------------------------------------------------------------------------------------------------------------------|
124+
| `main.py` | LangGraph agent code. |
125+
| `langgraph.json` | [LangGraph](https://langchain-ai.github.io/langgraph/concepts/application_structure/#file-structure) specific configuration file. |
126+
| `pyproject.toml` | Project metadata and dependencies as per [PEP 518](https://peps.python.org/pep-0518/). |
127+
128+
129+
## Initialize Project
130+
131+
<!-- termynal -->
132+
133+
```shell
134+
> uipath init
135+
⠋ Initializing UiPath project ...
136+
✓ Created '.env' file.
137+
✓ Created 'agent.mermaid' file.
138+
✓ Created 'uipath.json' file.
139+
```
140+
141+
This command creates the following files:
142+
143+
| File Name | Description |
144+
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------- |
145+
| `.env` | Environment variables and secrets (this file will not be packed & published). |
146+
| `uipath.json` | Input/output JSON schemas and bindings. |
147+
| `agent.mermaid` | Graph visual representation. |
148+
149+
## Set Up Environment Variables
150+
151+
Before running the agent, configure `OPENAI_API_KEY` in the `.env` file:
152+
153+
//// tab | Open AI
154+
155+
```
156+
OPENAI_API_KEY=sk-proj-......
157+
```
158+
159+
////
160+
161+
## Authenticate With UiPath
162+
163+
<!-- termynal -->
164+
165+
```shell
166+
> uipath auth
167+
⠋ Authenticating with UiPath ...
168+
🔗 If a browser window did not open, please open the following URL in your browser: [LINK]
169+
👇 Select tenant:
170+
0: Tenant1
171+
1: Tenant2
172+
Select tenant number: 0
173+
Selected tenant: Tenant1
174+
✓ Authentication successful.
175+
```
176+
177+
## Run The Agent Locally
178+
179+
Execute the agent with a sample input:
180+
181+
<!-- termynal -->
182+
183+
```shell
184+
> uipath run agent '{"topic": "UiPath"}'
185+
[2025-04-29 12:31:57,756][INFO] ((), {'topic': 'UiPath'})
186+
[2025-04-29 12:32:07,689][INFO] ((), {'topic': 'UiPath', 'report': "..."})
187+
```
188+
189+
This command runs your agent locally and displays the report in the standard output.
190+
191+
/// warning
192+
Depending on the shell you are using, it may be necessary to escape the input json:
193+
194+
/// tab | Bash/ZSH/PowerShell
195+
```console
196+
uipath run agent '{"topic": "UiPath"}'
197+
```
198+
///
199+
200+
/// tab | Windows CMD
201+
```console
202+
uipath run agent "{""topic"": ""UiPath""}"
203+
```
204+
///
205+
206+
/// tab | Windows PowerShell
207+
```console
208+
uipath run agent '{\"topic\":\"uipath\"}'
209+
```
210+
///
211+
212+
///
213+
214+
/// attention
215+
216+
For a shell agnostic option, please refer to the next section.
217+
218+
///
219+
220+
### (Optional) Run The Agent with a json File as Input
221+
222+
The `run` command can also take a .json file as an input. You can create a file named `input.json` having the following content:
223+
224+
```json
225+
{
226+
"topic": "UiPath"
227+
}
228+
```
229+
230+
Use this file as agent input:
231+
232+
```shell
233+
> uipath run agent --file input.json
234+
```
235+
236+
## Deploy the Agent to UiPath Automation Cloud
237+
238+
Follow these steps to publish and run your agent to UiPath Automation Cloud:
239+
240+
### (Optional) Customize the Package
241+
242+
Update author details in `pyproject.toml`:
243+
244+
```toml
245+
authors = [{ name = "Your Name", email = "your.name@example.com" }]
246+
```
247+
248+
### Package Your Project
249+
250+
<!-- termynal -->
251+
252+
```shell
253+
> uipath pack
254+
⠋ Packaging project ...
255+
Name : test
256+
Version : 0.1.0
257+
Description: Add your description here
258+
Authors : Your Name
259+
✓ Project successfully packaged.
260+
```
261+
262+
### Publish To My Workspace
263+
264+
<!-- termynal -->
265+
266+
```shell
267+
> uipath publish --my-workspace
268+
⠙ Publishing most recent package: my-agent.0.0.1.nupkg ...
269+
✓ Package published successfully!
270+
⠦ Getting process information ...
271+
🔗 Process configuration link: [LINK]
272+
💡 Use the link above to configure any environment variables
273+
```
274+
275+
/// info
276+
Please note that a process will be auto-created only upon publishing to **my-workspace** package feed.
277+
///
278+
279+
Set the environment variables using the provided link:
280+
281+
<picture data-light="quick_start_images/cloud_env_var_light.png" data-dark="quick_start_images/cloud_env_var_dark.png">
282+
<source
283+
media="(prefers-color-scheme: dark)"
284+
srcset="quick_start_images/cloud_env_var_dark.png"
285+
/>
286+
<img
287+
src="quick_start_images/cloud_env_var_light.png"
288+
/>
289+
</picture>
290+
291+
## Invoke the Agent on UiPath Automation Cloud
292+
293+
<!-- termynal -->
294+
295+
```shell
296+
> uipath invoke agent '{"topic": "UiPath"}'
297+
⠴ Loading configuration ...
298+
⠴ Starting job ...
299+
✨ Job started successfully!
300+
🔗 Monitor your job here: [LINK]
301+
```
302+
303+
Use the provided link to monitor your job and view detailed traces.
304+
305+
<picture data-light="quick_start_images/invoke_output_light.png" data-dark="quick_start_images/invoke_output_dark.png">
306+
<source
307+
media="(prefers-color-scheme: dark)"
308+
srcset="quick_start_images/invoke_output_dark.png"
309+
/>
310+
<img
311+
src="quick_start_images/invoke_output_light.png"
312+
/>
313+
</picture>
314+
315+
### (Optional) Invoke The Agent with a json File as Input
316+
317+
The `invoke` command operates similarly to the `run` command, allowing you to use the same .json file defined
318+
in the [(Optional) Run the agent with a .json file as input](#optional-run-the-agent-with-a-json-file-as-input)
319+
section, as agent input:
320+
321+
```shell
322+
> uipath invoke agent --file input.json
323+
```
324+
325+
## Next Steps
326+
327+
Congratulations! You have successfully set up, created, published, and run a UiPath LangChain Agent. 🚀
328+
329+
For more advanced agents and agent samples, please refer to our [samples section](https://github.com/UiPath/uipath-langchain-python/tree/main/samples) in GitHub.

‎src/uipath_llamaindex/_cli/_templates/llama_index.json.template‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"dependencies": ["."],
3+
"workflows": {
4+
"agent": "main.py:workflow"
5+
},
6+
"env": ".env"
7+
}

‎src/uipath_llamaindex/_cli/_templates/main.py.template‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
from llama_index.core.workflow import (
2+
Event,
3+
StartEvent,
4+
StopEvent,
5+
Workflow,
6+
step,
7+
)
8+
from llama_index.llms.openai import OpenAI
9+
10+
11+
class TopicEvent(StartEvent):
12+
topic: str
13+
14+
15+
class JokeEvent(Event):
16+
joke: str
17+
18+
19+
class CritiqueEvent(StopEvent):
20+
joke: str
21+
critique: str
22+
23+
24+
class JokeFlow(Workflow):
25+
llm = OpenAI()
26+
27+
@step
28+
async def generate_joke(self, ev: TopicEvent) -> JokeEvent:
29+
topic = ev.topic
30+
31+
prompt = f"Write your best joke about {topic}."
32+
response = await self.llm.acomplete(prompt)
33+
return JokeEvent(joke=str(response))
34+
35+
@step
36+
async def critique_joke(self, ev: JokeEvent) -> CritiqueEvent:
37+
joke = ev.joke
38+
39+
prompt = f"Give a thorough analysis and critique of the following joke: {joke}"
40+
response = await self.llm.acomplete(prompt)
41+
return CritiqueEvent(joke=joke, critique=str(response))
42+
43+
44+
workflow = JokeFlow(timeout=60, verbose=False)

0 commit comments

Comments
 (0)