# Run Agents & Functions

Execute your UiPath agent or function with interactive, schema-driven input collection.

> **Note:** The `uv run uipath run` workflow is identical for both agents and functions. Everything below applies to both.

## Project Verification

Before running an agent, your project should have:
- `uipath.json` - Project configuration
- `entry-points.json` - Agent entry points with schemas

If missing, create an agent first. See the [Creating Agents](../creating-agents.md) guide for setup instructions.

## Agent Discovery

The tool reads `entry-points.json` to find all available agents and their schemas:
- **File path** and **entry point** (e.g., main.py:main)
- **Input schema** with field types and descriptions
- **Output schema** with expected return fields

If multiple agents exist, you'll be prompted to select one.

## Input Collection

The skill parses the agent's JSON schema and generates interactive prompts for each input field:

**For simple types:**
```
Enter field_name (number) - Description: 42
Enter description (string) - Agent input: hello
```

**For enums:**
```
Select action (string) - Choose an action:
  1. process
  2. analyze
  3. export
Choice: 1
```

**For optional fields:**
```
Enter description (string) - Optional agent description [press Enter to skip]:
```

## Execution

Your agent runs with:
```bash
uv run uipath run <name> '<json-input>'
```

Where `<name>` is the key from `uipath.json` (e.g., `"main"` from `"agents": {"main": "main.py:main"}`), or the equivalent key from framework config files like `langgraph.json` or `llama-index.json`. It is **not** the file path — use the short name, not `main.py`.

The agent runs with your provided inputs and returns structured output.

## Results Display

Results are shown in a formatted output panel:

```
EXECUTION RESULTS
═══════════════════════════════════════════════════════════

Status:           ✅ SUCCESS
Execution Time:   0.45 seconds
Agent:            my-agent (agent.py:run)
Input:            {"action": "process", "data": "sample"}

OUTPUT:
{
  "status": "completed",
  "result": "processed successfully"
}
```

## Supported Input Types

The skill supports all JSON schema types:
- **string** - Text input
- **number** - Decimal numbers
- **integer** - Whole numbers
- **boolean** - Yes/No toggle
- **array** - List of items
- **object** - Complex nested data
- **enum** - Choice from predefined options

## Error Handling

If execution fails, check the traceback for these common errors:

- **`ModuleNotFoundError`**: A dependency is missing. Add it to `pyproject.toml` under `[project.dependencies]` and run `uv sync`.
- **`entry point not found`**: `entry-points.json` is stale or missing. Run `uv run uipath init` to regenerate it.
- **`ValidationError` (Pydantic)**: The input doesn't match the expected schema. Check your Input model fields and types against the JSON you're passing.
- **Type errors with `from __future__ import annotations`**: This stringifies all annotations and breaks runtime type detection. Remove it if your Input/Output models aren't being recognized.
- **Missing environment variables**: Check that required variables (e.g., `OPENAI_API_KEY`) are set. The error will typically say `KeyError` or `EnvironmentError` with the variable name.

## Integration

Execution traces are automatically collected and can be:
- Viewed in UiPath Cloud
- Analyzed for performance
- Used for debugging and optimization
