@uipath/skills 1.195.0

package/skills/uipath-agents/references/coded/capabilities/sdk-services.md

@@ -0,0 +1,244 @@
+# UiPath SDK Services Reference
+
+Complete reference for all platform services available through the UiPath Python SDK.
+
+## SDK Initialization
+
+```python
+from uipath.platform import UiPath
+
+sdk = UiPath()  # Reads credentials from environment variables
+
+# Or with explicit credentials
+sdk = UiPath(base_url="https://cloud.uipath.com/...", secret="your_token")
+sdk = UiPath(client_id="id", client_secret="secret", scope="scope", base_url="url")
+```
+
+> **CRITICAL: Never import or instantiate `UiPath()` at module level.** It requires auth credentials at construction time. Always create the instance inside a function or graph node — never at the top of the file. `uip codedagent init` imports your module to introspect it, and module-level `UiPath()` will fail.
+
+## Available Services
+
+| Service | Property | Purpose |
+|---------|----------|---------|
+| Processes | `sdk.processes` | Start process executions |
+| Jobs | `sdk.jobs` | Manage job lifecycle, attachments, output |
+| Assets | `sdk.assets` | Retrieve and update assets and credentials |
+| Attachments | `sdk.attachments` | Upload, download, delete attachments |
+| Buckets | `sdk.buckets` | Cloud storage file operations |
+| Queues | `sdk.queues` | Queue item and transaction management |
+| Context Grounding | `sdk.context_grounding` | RAG index management and search |
+| Documents | `sdk.documents` | Document extraction and validation |
+| Entities | `sdk.entities` | Data Service entity and record management |
+| Connections | `sdk.connections` | Integration Service connections |
+| LLM | `sdk.llm` | Chat completions via normalized LLM Gateway |
+| LLM OpenAI | `sdk.llm_openai` | OpenAI-compatible chat and embeddings |
+| Guardrails | `sdk.guardrails` | Evaluate guardrails on data |
+| Folders | `sdk.folders` | Folder key resolution |
+| Tasks | `sdk.tasks` | Action Center task management |
+| AgentHub | `sdk.agenthub` | LLM model discovery and system agent invocation |
+| MCP | `sdk.mcp` | List and retrieve MCP servers |
+| Resource Catalog | `sdk.resource_catalog` | Search and list tenant/folder resources |
+
+All services support **synchronous** and **asynchronous** methods (async methods have an `_async` suffix).
+
+---
+
+## Processes
+
+```python
+job = sdk.processes.invoke(name="MyProcess", input_arguments={"param1": "value1"}, folder_path="MyFolder")
+job = await sdk.processes.invoke_async(name="MyProcess", input_arguments={"param1": "value1"})
+```
+
+## Jobs
+
+```python
+job = sdk.jobs.retrieve(job_key="abc-123", folder_path="MyFolder")
+output = sdk.jobs.extract_output(job)
+sdk.jobs.resume(job_id="abc-123", payload={"approved": True})
+attachment_key = sdk.jobs.create_attachment(name="report.pdf", source_path="/path/to/report.pdf", job_key="abc-123")
+attachments = sdk.jobs.list_attachments(job_key=uuid.UUID("abc-123"))
+payload = sdk.jobs.retrieve_api_payload(inbox_id="inbox-123")
+```
+
+## Assets
+
+```python
+asset = sdk.assets.retrieve(name="MyAsset", folder_path="MyFolder")
+credential = sdk.assets.retrieve_credential(name="MyCredential")
+sdk.assets.update(robot_asset=asset, folder_path="MyFolder")
+```
+
+## Attachments
+
+```python
+key = sdk.attachments.upload(name="data.csv", source_path="/path/to/data.csv")
+key = sdk.attachments.upload(name="notes.txt", content="Hello, world!")
+path = sdk.attachments.download(key=uuid.UUID("abc-123"), destination_path="/path/to/download/")
+sdk.attachments.delete(key=uuid.UUID("abc-123"))
+```
+
+## Buckets
+
+```python
+bucket = sdk.buckets.retrieve(name="MyBucket")
+sdk.buckets.upload(name="MyBucket", blob_file_path="reports/output.csv", source_path="/local/path/output.csv")
+sdk.buckets.upload(name="MyBucket", blob_file_path="data/result.json", content='{"status": "done"}', content_type="application/json")
+sdk.buckets.download(name="MyBucket", blob_file_path="reports/output.csv", destination_path="/local/download/")
+```
+
+## Queues
+
+```python
+sdk.queues.create_item(item={"Name": "MyQueue", "SpecificContent": {"order_id": "12345"}})
+sdk.queues.create_items(queue_name="MyQueue", items=[{"SpecificContent": {"order_id": "001"}}], commit_type="AllOrNothing")
+sdk.queues.create_transaction_item(item={"Name": "MyQueue", "SpecificContent": {"task": "process_order"}})
+sdk.queues.complete_transaction_item(transaction_key="txn-123", result={"IsSuccessful": True, "Output": {"status": "done"}})
+sdk.queues.update_progress_of_transaction_item(transaction_key="txn-123", progress="Processing step 3 of 5")
+items = sdk.queues.list_items()
+```
+
+## Tasks
+
+```python
+task = sdk.tasks.create(title="Review Invoice", data={"invoice_id": "1234"}, app_name="InvoiceReview", assignee="user@example.com")
+task = sdk.tasks.retrieve(action_key="task-key-123")
+```
+
+## Context Grounding
+
+```python
+index = sdk.context_grounding.retrieve(name="KnowledgeBase")
+results = sdk.context_grounding.search(name="KnowledgeBase", query="How do I reset my password?", number_of_results=5)
+index = sdk.context_grounding.create_index(name="MyIndex", source={"type": "bucket", "bucketName": "docs-bucket"})
+sdk.context_grounding.add_to_index(name="MyIndex", blob_file_path="docs/guide.pdf", source_path="/local/guide.pdf")
+sdk.context_grounding.ingest_data(index=index)
+sdk.context_grounding.delete_index(index=index)
+```
+
+## Documents
+
+```python
+extraction = sdk.documents.extract(project_name="InvoiceExtraction", tag="invoice", file_path="/path/to/invoice.pdf")
+validation = sdk.documents.create_validation_action(
+    action_title="Validate Invoice", action_priority="Normal", action_catalog="InvoiceValidation",
+    action_folder="Invoices", storage_bucket_name="doc-storage",
+    storage_bucket_directory_path="validations/", extraction_response=extraction
+)
+result = sdk.documents.get_validation_result(validation_action=validation)
+```
+
+## Entities
+
+```python
+entities = sdk.entities.list_entities()
+entity = sdk.entities.retrieve(entity_key="Customers")
+records = sdk.entities.list_records(entity_key="Customers", start=0, limit=50)
+sdk.entities.insert_records(entity_key="Customers", records=[{"Name": "Acme", "Email": "info@acme.com"}])
+sdk.entities.update_records(entity_key="Customers", records=[{"Id": "rec-123", "Email": "new@acme.com"}])
+sdk.entities.delete_records(entity_key="Customers", record_ids=["rec-123"])
+```
+
+## Connections
+
+```python
+connections = sdk.connections.list(name="Salesforce")
+connection = sdk.connections.retrieve(key="conn-key-123")
+token = sdk.connections.retrieve_token(key="conn-key-123", token_type="direct")
+metadata = sdk.connections.metadata(element_instance_id=123, connector_key="uipath-salesforce", tool_path="/contacts")
+payload = sdk.connections.retrieve_event_payload(event_args=event_args)
+result = sdk.connections.invoke_activity(activity_metadata=meta, connection_id="conn-key-123", activity_input={"query": "site:uipath.com"})
+result = await sdk.connections.invoke_activity_async(activity_metadata=meta, connection_id="conn-key-123", activity_input={...})
+```
+
+See [integration-service.md](integration-service.md) for the full discover-and-invoke flow.
+
+## LLM
+
+```python
+response = sdk.llm.chat_completions(
+    messages=[{"role": "system", "content": "You are helpful."}, {"role": "user", "content": "Summarize this."}],
+    model="gpt-4o-mini-2024-07-18", max_tokens=4096, temperature=0
+)
+
+# Structured output with Pydantic
+response = sdk.llm.chat_completions(messages=[...], model="gpt-4o-mini-2024-07-18", response_format=MyPydanticModel)
+
+# With tools
+response = sdk.llm.chat_completions(messages=[...], model="gpt-4o-mini-2024-07-18", tools=[tool_def], tool_choice="auto")
+```
+
+## LLM OpenAI
+
+```python
+response = sdk.llm_openai.chat_completions(messages=[{"role": "user", "content": "Hello!"}], model="gpt-4o-mini-2024-07-18")
+embeddings = sdk.llm_openai.embeddings(input="The quick brown fox", embedding_model="text-embedding-ada-002")
+```
+
+## Guardrails
+
+```python
+result = sdk.guardrails.evaluate(guardrail_name="ContentSafety", data={"prompt": "User message"}, folder_path="MyFolder")
+```
+
+## Tasks
+
+```python
+task = sdk.tasks.create(title="Review document", data={"document_id": "doc-123"}, app_name="DocumentReview", assignee="reviewer@company.com")
+task = sdk.tasks.retrieve(action_key="task-key-123")
+```
+
+## AgentHub
+
+```python
+models = sdk.agenthub.get_available_llm_models()
+# Each item exposes `.model_name` and `.vendor`
+
+# Pick a model by vendor (example: first OpenAI model available in the tenant)
+openai_model = next(m.model_name for m in models if m.vendor == "OpenAI")
+
+job_key = sdk.agenthub.invoke_system_agent(
+    agent_name="system-agent",
+    entrypoint="main",
+    input_arguments={"query": "Help me"},
+)
+```
+
+## MCP
+
+```python
+servers = sdk.mcp.list()
+server = sdk.mcp.retrieve(slug="my-mcp-server", folder_path="MyFolder")
+```
+
+## Resource Catalog
+
+```python
+resources = sdk.resource_catalog.search(query="invoice processing")
+resources = sdk.resource_catalog.list(folder_path="Finance")
+```
+
+## Folders
+
+```python
+folder_key = sdk.folders.retrieve_key(folder_path="Finance/Invoices")
+```
+
+---
+
+## Common Patterns
+
+### Folder Targeting
+
+Most services accept `folder_key` or `folder_path`:
+```python
+asset = sdk.assets.retrieve(name="MyAsset", folder_path="Finance/Invoices")
+asset = sdk.assets.retrieve(name="MyAsset", folder_key="abc-123-def")
+```
+
+### Async Usage
+
+All services have async variants with `_async` suffix:
+```python
+asset = await sdk.assets.retrieve_async(name="MyAsset")
+```

package/skills/uipath-agents/references/coded/capabilities/tracing.md

@@ -0,0 +1,247 @@
+# UiPath Tracing Guide
+
+Understand and implement tracing in your agents for monitoring, debugging, and auditing.
+
+## What is Tracing?
+
+Tracing is a monitoring feature that automatically captures function execution details. With the `@traced()` decorator, you can:
+- 📊 Record function arguments and return values
+- 🔍 Track execution flow for debugging
+- 📋 Audit code behavior in Orchestrator
+- 🔒 Redact sensitive data before logging
+
+Trace data appears in:
+- **UiPath Orchestrator**: Jobs page → Trace tab
+- **UiPath Maestro**: For larger process orchestrations
+
+## How Tracing Works
+
+The `@traced()` decorator automatically monitors your functions. Apply it to any function:
+
+```python
+from uipath.tracing import traced
+
+@traced()
+def my_function(input_data):
+    """This function's execution will be traced."""
+    return process_data(input_data)
+```
+
+**Supported Function Types:**
+- Regular synchronous functions
+- Async functions (`async def`)
+- Generator functions (`yield`)
+- Async generators (`async yield`)
+
+## Basic Usage
+
+### Simple Tracing
+
+```python
+from pydantic import BaseModel
+from uipath.tracing import traced
+
+class Input(BaseModel):
+    user_id: int
+    action: str
+
+@traced()
+async def main(input: Input) -> dict:
+    """Main agent function with tracing enabled."""
+    result = process_user_action(input.user_id, input.action)
+    return {"status": "success", "result": result}
+```
+
+### Custom Span Names
+
+Organize traces by giving them meaningful names:
+
+```python
+@traced(name="validate_user_input")
+def validate_input(user_id: int, action: str) -> bool:
+    """Custom span name for better trace organization."""
+    return user_id > 0 and action in ["create", "update", "delete"]
+```
+
+### Custom Run Types
+
+Categorize traces by function purpose:
+
+```python
+@traced(run_type="data_processing")
+def process_csv_file(file_path: str) -> list:
+    """Mark this as a data processing operation."""
+    # Processing logic
+    return processed_data
+```
+
+### Span Type
+
+`span_type` is a free-form string; most callers leave it unset and let the decorator choose. The one value with special handling is `"tool"` — it marks the function as an OpenInference tool call (`openinference.span.kind = "TOOL"`, `tool.name = <function name>`). Use it on helper functions that act as tools the agent invokes.
+
+When `span_type` is not set, the decorator assigns one of `function_call_sync`, `function_call_async`, `function_call_generator_sync`, or `function_call_generator_async` based on the wrapped function's type.
+
+## Data Protection & Privacy
+
+### Redacting Sensitive Data
+
+Use input/output processors to mask sensitive information before logging:
+
+```python
+@traced(
+    input_processor=lambda x: {**x, "password": "***"},
+    output_processor=lambda x: {**x, "token": "***"}
+)
+def authenticate_user(username: str, password: str) -> dict:
+    """Password is redacted before tracing."""
+    token = generate_token(username, password)
+    return {"username": username, "token": token}
+```
+
+### Hide Input/Output
+
+Completely hide sensitive parameters from traces:
+
+```python
+@traced(hide_input=True, hide_output=True)
+def process_api_key(api_key: str) -> bool:
+    """API key is not recorded in traces at all."""
+    return validate_api_key(api_key)
+```
+
+## Advanced Configuration
+
+### Combining Parameters
+
+Create comprehensive tracing for complex operations:
+
+```python
+@traced(
+    name="payment_processing",
+    run_type="financial_transaction",
+    input_processor=lambda x: {
+        "amount": x["amount"],
+        "currency": x["currency"],
+        "customer_id": "***"
+    },
+    hide_output=False  # Show output but redact sensitive input
+)
+async def process_payment(customer_id: str, amount: float, currency: str) -> dict:
+    """Process payment with full tracing and privacy."""
+    result = call_payment_api(customer_id, amount, currency)
+    return result
+```
+
+## Integration Patterns
+
+### With LangChain Agents
+
+LangChain agents handle tracing automatically—no additional configuration needed.
+
+## Common Use Cases
+
+### 1. Production Monitoring
+
+Track function execution in production agents to monitor performance and catch errors.
+
+```python
+@traced(name="user_lookup")
+async def get_user_details(user_id: int) -> dict:
+    """Monitor user lookup operations."""
+    return await database.find_user(user_id)
+```
+
+### 2. Data Pipeline Auditing
+
+Record all transformations for compliance and debugging.
+
+```python
+@traced(
+    name="data_transformation",
+    input_processor=lambda x: {"record_count": len(x), "schema_version": "1.0"}
+)
+def transform_batch(records: list) -> list:
+    """Audit data transformation without logging raw data."""
+    return [transform_record(r) for r in records]
+```
+
+### 3. API Integration Debugging
+
+Track external API calls for troubleshooting.
+
+```python
+@traced(name="call_external_api", run_type="integration")
+async def fetch_from_third_party(endpoint: str, params: dict) -> dict:
+    """Monitor third-party API interactions."""
+    response = await call_api(endpoint, params)
+    return response
+```
+
+### 4. Security & Compliance
+
+Trace actions while protecting sensitive data for audit logs.
+
+```python
+@traced(
+    hide_input=True,
+    hide_output=True,
+    name="sensitive_operation"
+)
+def verify_credentials(username: str, password: str) -> bool:
+    """Audit sensitive operations without logging credentials."""
+    return authenticate(username, password)
+```
+
+## Viewing Traces
+
+### In Orchestrator
+
+1. Go to **Jobs** page
+2. Select a completed job
+3. Click **Trace** tab to view captured data
+4. Expand trace spans to see details
+
+### Trace Information Available
+
+- Function name and custom span name
+- Input arguments (or "hidden" if redacted)
+- Return value (or "hidden" if redacted)
+- Execution time
+- Exceptions and errors
+
+## Best Practices
+
+✅ **Do:**
+- Use meaningful `name` values for organization
+- Apply `@traced()` to all public functions
+- Use processors for sensitive data instead of `hide_*` flags (you get partial visibility)
+- Test tracing locally before deploying to production
+- Combine with logging for comprehensive observability
+
+❌ **Don't:**
+- Log raw passwords or API keys
+- Use `hide_*` for all sensitive data if you need partial visibility
+- Assume tracing adds no performance overhead (it's minimal but measurable)
+
+## Trace Flushing
+
+Traces are flushed automatically when the agent runs through `uip codedagent run` or `invoke`. No manual flush is required.
+
+## Troubleshooting
+
+### Traces Not Appearing
+
+1. Verify the agent ran to completion
+2. Check that `@traced()` is applied to the function you expect to see
+3. Confirm Orchestrator has the job data (check the Jobs page)
+
+### Performance Concerns
+
+Tracing has minimal overhead. If performance is critical:
+- Use `name` parameter for cleaner traces
+- Apply `@traced()` only to key functions (not every small helper)
+- Use `input_processor` to reduce data volume in traces
+
+## Documentation
+
+For more details, visit: https://uipath.github.io/uipath-python/core/traced/

package/skills/uipath-agents/references/coded/embedding-in-flows.md

@@ -0,0 +1,97 @@
+# Coded Agents in Flow Projects (Sibling Folder)
+
+A coded agent can live as a sibling folder to a flow project inside the same solution. The flow references it via `uipath.core.agent.<resourceKey>` with `section: "In this solution"`. The flow's `uip maestro flow registry list --local` discovers the agent by reading `resources/solution_folder/process/agent/<CodedAgentProject>.json`, written by `uip solution project add`.
+
+For the published-agent path (deployed standalone via `uip codedagent deploy`), see [coded/flow-integration.md § Pattern 2](flow-integration.md#pattern-2-published-coded-agent).
+
+## Sibling Folder Structure
+
+The `<resourceKey>` is the local UUID minted by `uip solution project add` — stable the moment the agent joins the solution.
+
+```
+<SolutionDir>/
+├── <SolutionName>.uipx
+├── resources/                      # created and maintained by `uip solution project add`
+│   └── solution_folder/
+│       ├── process/agent/<CodedAgentProject>.json   # holds the `resource.key` UUID
+│       └── package/<CodedAgentProject>.json
+├── <FlowProject>/
+│   ├── <FlowName>.flow
+│   └── project.uiproj
+└── <CodedAgentProject>/
+    ├── main.py                     # agent entrypoint
+    ├── pyproject.toml              # Python project config
+    ├── uipath.json                 # UiPath project config
+    ├── entry-points.json           # generated by `uip codedagent init`
+    ├── bindings.json               # runtime bindings
+    ├── main.mermaid                # generated graph diagram
+    ├── project.uiproj              # Studio Web project metadata
+    ├── .env                        # environment variables
+    ├── .uipath/
+    │   └── telemetry.json          # telemetry config
+    └── .venv/                      # local virtualenv (created by `uv sync`)
+```
+
+### Key differences from a published coded agent
+
+- **`resource.key`** is minted locally at `uip solution project add` time, not by Orchestrator at `uip codedagent deploy` time
+- **No `codedagent deploy`** — the agent ships inside the solution package
+- **Registry discovery is `--local`** (reads `resources/solution_folder/process/` files); no login or `registry pull` required
+- **`model.section`** is `"In this solution"`
+
+## Scaffolding the Sibling-Folder Coded Agent
+
+The full end-to-end workflow (solution init → flow scaffold → agent scaffold → register → wire → validate) is owned by [`quickstart.md` § Scenario 2](quickstart.md#quick-start-scenario-2--in-solution-coded-agent-in-a-flow). This file covers the agent-side detail of step 3 (scaffold) and step 5 (registration) in finer detail; the canonical sequence stays in the quickstart so it remains executable in one pass.
+
+If the solution and flow project don't yet exist, run `uip solution init "<SolutionName>"` and then `uip maestro flow init "<FlowName>"` from inside the solution **before** the steps below — those calls are the start of Scenario 2.
+
+1. From the solution directory, create the agent folder and scaffold inside it:
+
+   ```bash
+   mkdir <CodedAgentProject>
+   cd <CodedAgentProject>
+   uv venv --python 3.13
+   source .venv/bin/activate       # .venv/Scripts/activate on Windows
+   uv pip install <FRAMEWORK_PACKAGE>   # e.g. uipath for Coded Function
+   uip codedagent setup --force
+   uip codedagent new <agent-name>
+   uv sync
+   ```
+
+   For a simple stub with no LLM call, use the Coded Function framework
+   (`uipath` package). This avoids downloading the full LangGraph or
+   LlamaIndex stack and keeps the setup fast.
+
+2. Implement `main.py`. Use lazy LLM initialization (create clients inside functions, never at module level).
+
+3. Generate entry points:
+
+   ```bash
+   uip codedagent init
+   ```
+
+4. Register the agent in the solution — **this is the step that mints the `resource.key`** the flow will reference:
+
+   ```bash
+   cd <SolutionDir>
+   uip solution project add <CodedAgentProject> <SolutionName>.uipx --output json
+   ```
+
+   After this command, `resources/solution_folder/process/agent/<CodedAgentProject>.json` holds the `resource.key` UUID.
+
+
+### Flow Discovery
+
+From inside the flow project directory, the agent is discoverable via the in-solution registry. The `--local` flag tells the registry commands to walk up from CWD to find a `.uipx`, read the `resources/solution_folder/process/` files written by step 4, and surface every sibling project as a discoverable node type — all offline, without a tenant registry round-trip:
+
+```bash
+# list every in-solution node type (all sibling projects)
+uip maestro flow registry list --local --output json
+
+# fetch the full manifest for the coded agent
+uip maestro flow registry get "uipath.core.agent.<resourceKey>" --local --output json
+```
+
+The second command's `Data.Node` object is what the flow skill pastes into the flow's `definitions[]`. For the node instance shape and top-level `bindings[]` entries, see [agent/impl.md § In-solution variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--in-solution-variant).
+
+Without `--local`, `registry list`/`get` query the tenant registry (Orchestrator-published resources only) and will not surface the sibling project.

package/skills/uipath-agents/references/coded/flow-integration.md

@@ -0,0 +1,88 @@
+# Coded Agents — Flow Integration
+
+Coded agents in flows use the `uipath.core.agent.{key}` node with `Orchestrator.StartAgentJob`. Three patterns exist, distinguished by where the agent lives.
+
+---
+
+## Pattern 1: In-Solution Coded Agent
+
+The coded agent lives as a sibling folder inside the same solution as the flow. The flow references it with `section: "In this solution"`; the runtime resolves the node via the Studio Web projects API.
+
+- **Agent-side scaffolding:** [embedding-in-flows.md](embedding-in-flows.md)
+- **Flow node JSON shape + top-level `bindings[]` + `definitions[]` entry:** [agent/impl.md § In-solution variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--in-solution-variant)
+
+The node-type's `{key}` is the local `resource.key` minted by `uip solution project add` (written to `resources/solution_folder/process/agent/<name>.json`) and surfaced by `uip maestro flow registry list --local`.
+
+---
+
+## Pattern 2: Published Coded Agent
+
+The coded agent is deployed to Orchestrator as a standalone tenant resource. Any solution can reference it.
+
+**When to use:** reused across flows, independent versioning, already deployed.
+
+```bash
+uip codedagent deploy --my-workspace
+uip maestro flow registry pull --force
+```
+
+**Capture the package key from the deploy command's own output** — `uip codedagent deploy` prints JSON containing the package `Key` (an Orchestrator-assigned GUID). That GUID is the `resourceKey` used in the flow node's `type` (`uipath.core.agent.<resourceKey>`) and `model.bindings.resourceKey`. Always run `uip maestro flow registry pull --force` after deploy to refresh the local flow registry cache, but do NOT depend on `uip maestro flow registry search "uipath.core.agent"` to return the deployed agent — that search only enumerates built-in node types (`uipath.agent.autonomous`, etc.); user-deployed coded agents do not appear there, so an empty result is the *expected* state and is NOT a sign the deploy failed.
+
+Fallback discovery paths if the deploy output is unavailable or unparseable, **tried in order** — stop at the first one that returns the package:
+
+1. `uip or packages list --search "<agent-name>" --output json` (tenant feed listing). Returns 404 on tenants where the caller lacks `Orchestrator.Packages.View` scope — if so, move to (2).
+2. `uip or processes list --folder-path "<FolderName>" --output json` if the agent was deployed via `--folder` rather than `--my-workspace`.
+
+If all paths return empty / 404, the deploy command's stdout JSON is authoritative — re-run the deploy and capture its output rather than chasing post-hoc discovery endpoints.
+
+For the flow node JSON shape, see [agent/impl.md § Published variant](../../../uipath-maestro-flow/references/plugins/agent/impl.md#node-instance-inside-nodes--published-variant). `model.section` is `"Published"`.
+
+---
+
+## Pattern 3: Tool Resource for Another Agent
+
+The coded agent is a tool that another agent (inline or published) can call. Requires deploying the coded agent to Orchestrator first.
+
+**Resource file** at `<AgentProject>/resources/<ResourceName>/resource.json`:
+
+```json
+{
+  "$resourceType": "tool",
+  "type": "agent",
+  "name": "MyCodedAgent",
+  "description": "What this agent does (shown to the parent LLM for tool selection)",
+  "location": "external",
+  "properties": {
+    "processName": "<CODED_AGENT_PROCESS_NAME>",
+    "folderPath": "<FOLDER_PATH>"
+  },
+  "inputSchema":  { "type": "object", "properties": { "userInput": { "type": "string" } } },
+  "outputSchema": { "type": "object", "properties": { "content":   { "type": "string" } } },
+  "id": "<UUID>",
+  "referenceKey": ""
+}
+```
+
+Coded agents use `location: "external"`.
+
+---
+
+## Pattern Comparison
+
+| Aspect | In-Solution (1) | Published (2) | Tool (3) |
+|---|---|---|---|
+| Node type | `uipath.core.agent.<resourceKey>` (local, from `project add`) | `uipath.core.agent.<resourceKey>` (Orchestrator-assigned) | `uipath.agent.resource.tool.agent` |
+| Lifecycle | `uip solution upload` (single pass) | `uip codedagent deploy` | `uip codedagent deploy` |
+| Runtime lookup | Studio Web projects API | Orchestrator Releases API | Orchestrator (via parent agent) |
+| `model.section` | `"In this solution"` | `"Published"` or absent | n/a |
+| Cross-flow reuse | No | Yes | Yes |
+
+---
+
+## Debug
+
+| Error | Cause | Fix |
+| --- | --- | --- |
+| Node doesn't resolve in SW (Pattern 1) | `resourceKey` was hand-invented rather than read from the resource file | Run `uip maestro flow registry list --local` and use the returned `resourceKey` (it matches `resource.key` in `resources/solution_folder/process/agent/<name>.json`) |
+| Agent not found in registry (Pattern 2/3) | Not deployed or registry stale | `uip codedagent deploy`, then `uip maestro flow registry pull --force` |
+| Tool resource never called | Tool description too vague | Sharpen the `description` in `resource.json` |