@uipath/skills 1.195.0

package/skills/uipath-agents/references/lowcode/agent-definition.md

@@ -0,0 +1,388 @@
+# Agent Definition Reference
+
+Schemas for the core agent definition files: `agent.json`, `entry-points.json`, `project.uiproj`. Plus contentTokens construction, message templates, and Common Edits.
+
+## Project Directory Structure
+
+After `uip agent init <name>`:
+
+```
+<AgentName>/
+├── agent.json              # Main agent configuration (edit this)
+├── entry-points.json       # Entry point definition (must mirror agent.json schemas)
+├── project.uiproj          # Project metadata
+├── flow-layout.json        # UI layout — do not edit
+├── evals/                  # Evaluation sets and evaluators
+├── features/               # Agent features (memory spaces via uip agent memory)
+└── resources/              # Agent resources
+```
+
+## agent.json
+
+Primary configuration file. Edit directly.
+
+```json
+{
+  "version": "1.1.0",
+  "settings": {
+    "model": "<MODEL_IDENTIFIER>",
+    "maxTokens": 16384,
+    "temperature": 0,
+    "engine": "basic-v2",
+    "maxIterations": 25,
+    "mode": "standard"
+  },
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "<FIELD_NAME>": {
+        "type": "string",
+        "description": "<FIELD_DESCRIPTION>"
+      }
+    },
+    "required": ["<FIELD_NAME>"]
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "<FIELD_NAME>": {
+        "type": "string",
+        "description": "<FIELD_DESCRIPTION>"
+      }
+    }
+  },
+  "metadata": {
+    "storageVersion": "50.0.0",
+    "isConversational": false,
+    "showProjectCreationExperience": false,
+    "targetRuntime": "pythonAgent"
+  },
+  "type": "lowCode",
+  "messages": [
+    {
+      "role": "system",
+      "content": "<SYSTEM_PROMPT>",
+      "contentTokens": [
+        { "type": "simpleText", "rawString": "<SYSTEM_PROMPT>" }
+      ]
+    },
+    {
+      "role": "user",
+      "content": "{{input.fieldName}}",
+      "contentTokens": [
+        { "type": "variable", "rawString": "input.fieldName" }
+      ]
+    }
+  ],
+  "guardrails": [],
+  "projectId": "<AUTO_GENERATED_UUID>"
+}
+```
+
+> **`guardrails`** — array of guardrail objects that inspect agent inputs/outputs for policy violations. See [capabilities/guardrails/guardrails.md](capabilities/guardrails/guardrails.md) for the full schema, validator reference, and examples.
+
+### Settings
+
+| Field | Description |
+|-------|-------------|
+| `model` | LLM identifier. Discover valid values with `uip agent model list` and select per [model-selection-guide.md](model-selection-guide.md) — **override the scaffold default `gpt-4o-2024-11-20`** (illustrative GA: `"anthropic.claude-sonnet-4-6"`, `"gpt-5.4"` — verify against the tenant). |
+| `maxTokens` | Max output tokens. Must not exceed the chosen model's `MaxTokens` cap (from `uip agent model list`). |
+| `temperature` | 0 = deterministic, higher = creative |
+| `engine` | Use `"basic-v2"` |
+| `maxIterations` | Max agent loop iterations. Default 25. |
+| `mode` | Use `"standard"` |
+
+> Prompt **quality** (system/user prompt structure, tool-call criteria, output contract) lives in [agent-prompting-guide.md](agent-prompting-guide.md). This file owns the **mechanics** (schema, `contentTokens` sync).
+
+### Schema Types
+
+| Type | Use For |
+|------|---------|
+| `"string"` | Text, JSON strings, formatted data |
+| `"number"` | Numeric values with decimals |
+| `"integer"` | Whole numbers |
+| `"boolean"` | True/false flags |
+| `"object"` | Nested structures |
+| `"array"` | Lists |
+| `$ref: "#/definitions/job-attachment"` | File attachments (input or output). See § File Attachments. |
+
+### File Attachments (`job-attachment`)
+
+To accept or return a file, declare the field as `$ref: "#/definitions/job-attachment"` and add the canonical `job-attachment` block to `inputSchema.definitions` (or `outputSchema.definitions`). Schema is fixed — copy verbatim. `x-uipath-resource-kind: "JobAttachment"` is required.
+
+```jsonc
+{
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "fileIn": { "$ref": "#/definitions/job-attachment" }
+    },
+    "definitions": {
+      "job-attachment": {
+        "type": "object",
+        "properties": {
+          "ID":       { "type": "string", "description": "Orchestrator attachment key" },
+          "FullName": { "type": "string", "description": "File name" },
+          "MimeType": { "type": "string", "description": "MIME type, e.g. \"application/pdf\", \"image/png\"" },
+          "Metadata": {
+            "type": "object",
+            "description": "Dictionary<string, string> of metadata",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "required": ["ID"],
+        "x-uipath-resource-kind": "JobAttachment"
+      }
+    }
+  }
+}
+```
+
+| Field | Required | Notes |
+|---|---|---|
+| `ID` | Yes | Orchestrator attachment key. Runtime injects this. |
+| `FullName` | No | File name with extension. |
+| `MimeType` | No | Drives multimodal handling in built-in tools. |
+| `Metadata` | No | `Dictionary<string, string>`. |
+
+`{{input.<file-field>}}` in a message template renders **metadata only** (ID, FullName, MimeType, Metadata). The agent does not see file contents from this token. To read contents, configure a file-handling built-in tool (e.g. `analyze-attachments`) — see [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md).
+
+Output side: declare an output field the same way; the agent emits a `job-attachment` describing a file it produced.
+
+Runtime note: attachments cannot be supplied via `uip` CLI. Test from Studio Web or via Orchestrator job invocation.
+
+### Top-level fields (do not modify)
+
+| Field | Value |
+|-------|-------|
+| `version` | `"1.1.0"` — always scaffolded at this version |
+| `type` | `"lowCode"` |
+| `projectId` | Auto-generated UUID — do not edit |
+
+### Metadata (do not modify)
+
+| Field | Value |
+|-------|-------|
+| `storageVersion` | Managed by `uip agent migrate` — do not edit |
+| `isConversational` | `false` (autonomous agents) |
+| `showProjectCreationExperience` | `false` |
+| `targetRuntime` | `"pythonAgent"` |
+
+## Messages
+
+This section covers message **structure** and `contentTokens` mechanics. For prompt **quality** — system-prompt skeleton, tool-call criteria, output contract, worked examples — see [agent-prompting-guide.md](agent-prompting-guide.md).
+
+### System Message
+
+Sets the agent's role and behavior. Typically plain text with no variables:
+
+```json
+{
+  "role": "system",
+  "content": "You are a classifier. Categorize the input and explain your reasoning.",
+  "contentTokens": [
+    { "type": "simpleText", "rawString": "You are a classifier. Categorize the input and explain your reasoning." }
+  ]
+}
+```
+
+### User Message
+
+Templates input fields into the prompt using `{{input.fieldName}}`. For `job-attachment` fields the token renders metadata only (see § File Attachments).
+
+```json
+{
+  "role": "user",
+  "content": "Document: {{input.documentText}} Category options: {{input.categories}}",
+  "contentTokens": [
+    { "type": "simpleText", "rawString": "Document: " },
+    { "type": "variable", "rawString": "input.documentText" },
+    { "type": "simpleText", "rawString": " Category options: " },
+    { "type": "variable", "rawString": "input.categories" }
+  ]
+}
+```
+
+## contentTokens Construction
+
+Every message needs both `content` (string) and `contentTokens` (array). Keep them in sync.
+
+**Rules:**
+1. Text outside `{{ }}` → `{ "type": "simpleText", "rawString": "<text>" }`
+2. Text inside `{{ }}` → `{ "type": "variable", "rawString": "input.fieldName" }` (strip delimiters)
+3. Every segment including whitespace gets its own entry
+
+**Example — adjacent variables:**
+
+Content: `"{{input.field1}} {{input.field2}}"`
+
+```json
+"contentTokens": [
+  { "type": "variable", "rawString": "input.field1" },
+  { "type": "simpleText", "rawString": " " },
+  { "type": "variable", "rawString": "input.field2" }
+]
+```
+
+**Common mistakes:**
+- Forgetting to update contentTokens after editing content
+- Including `{{` or `}}` in the variable rawString
+- Missing whitespace tokens between adjacent variables
+
+## entry-points.json
+
+Defines how the agent is invoked. Schemas must exactly mirror agent.json.
+
+```json
+{
+  "$schema": "https://cloud.uipath.com/draft/2024-12/entry-point",
+  "$id": "entry-points.json",
+  "entryPoints": [
+    {
+      "filePath": "/content/agent.json",
+      "uniqueId": "<AUTO_GENERATED_UUID>",
+      "type": "agent",
+      "input": {
+        "type": "object",
+        "properties": { },
+        "required": []
+      },
+      "output": {
+        "type": "object",
+        "properties": { }
+      }
+    }
+  ]
+}
+```
+
+### Sync Rule
+
+| agent.json | entry-points.json |
+|-----------|-------------------|
+| `inputSchema.properties.<field>` | `entryPoints[0].input.properties.<field>` |
+| `inputSchema.required` | `entryPoints[0].input.required` |
+| `outputSchema.properties.<field>` | `entryPoints[0].output.properties.<field>` |
+
+Do not modify `filePath`, `uniqueId`, or `type`.
+
+## project.uiproj
+
+```json
+{
+  "ProjectType": "Agent",
+  "Name": "<AGENT_NAME>",
+  "Description": null,
+  "MainFile": null
+}
+```
+
+Only `Name` and `Description` are editable. `ProjectType` and `MainFile` are fixed.
+
+## Features Convention (v1.1.0)
+
+Features are defined as individual files in the agent project's `features/` directory. Today this is used for memory spaces. Do not hand-author memory feature files for routine changes; use `uip agent memory`.
+
+```
+Agent/
+├── agent.json                              # No manually-authored memory features here
+├── features/
+│   └── {FeatureName}/
+│       └── feature.json                    # Written by uip agent memory
+```
+
+The `memory` command updates `features/{FeatureName}/feature.json` and `.agent-builder/agent.json`. Run `uip agent validate --output json`, then `uip agent migrate --output json` after memory changes so generated bindings stay current.
+
+For the full memory workflow and generated shape, see [capabilities/memory/memory.md](capabilities/memory/memory.md).
+
+## Resources Convention (v1.1.0)
+
+Resources are defined as individual files in the agent project's `resources/` directory — **not** inline in the root `agent.json`. Each resource gets its own subdirectory:
+
+```
+Agent/
+├── agent.json                              # No resources field here
+├── resources/
+│   └── {ResourceName}/
+│       └── resource.json                   # One file per resource
+```
+
+The `validate` command reads these files, resolves `referenceKey` for solution tools, and generates `.agent-builder/agent.json` which inlines all resources. The root `agent.json` should not contain a `resources` field.
+
+### `folderPath` semantics
+
+`folderPath` (or `channel.properties.folderName` for escalations / `action.app.folderName` for guardrail escalations) carries the literal `Folder` field returned by `uip solution resource list` — the same rule for both local (`Source: "Local"`) and external (`Source: "Remote"`) resources:
+
+| `location` | `folderPath` value | Source |
+|---|---|---|
+| `"solution"` | Typically `"solution_folder"` (the in-solution declared folder) | `Folder` field from `uip solution resource list` |
+| `"external"` | Literal Orchestrator folder, slash-separated (e.g., `"Shared/Sales"`) | `Folder` field from `uip solution resource list` |
+
+The author writes the value verbatim into `resource.json` (or into the guardrail action under `agent.json`); `uip agent migrate` propagates it into `bindings_v2.json` as `folderPath` (App resources translate `folderName` → binding `folderPath`). Connection (Integration Service) resources are exempt — bound by `connection.id`, no `folderPath`. See [critical-rules.md](critical-rules.md) Rule 11 and [solution-resources.md](solution-resources.md) § Bindings.
+
+For each resource type's full schema, see the relevant capability file:
+
+- Tool resources (`$resourceType: "tool"`) — [capabilities/process/process.md](capabilities/process/process.md), [capabilities/integration-service/integration-service.md](capabilities/integration-service/integration-service.md)
+- Context resources (`$resourceType: "context"`) — [capabilities/context/context.md](capabilities/context/context.md)
+- Escalation resources (`$resourceType: "escalation"`) — [capabilities/escalation/escalation.md](capabilities/escalation/escalation.md)
+
+## Common Edits
+
+### Change System Prompt
+
+1. Edit `agent.json` → `messages[0].content`
+2. Rebuild `messages[0].contentTokens` — single `simpleText` entry for prompts with no variables
+3. Validate: `uip agent validate --output json`
+4. Migrate: `uip agent migrate --output json`
+
+### Change User Message Template
+
+1. Edit `agent.json` → `messages[1].content`
+2. Rebuild `messages[1].contentTokens` — tokenize `{{input.fieldName}}` as `variable`, surrounding text as `simpleText`
+3. Validate, then migrate
+
+### Add an Input Field
+
+1. Add to `agent.json` → `inputSchema.properties` (and `.required` if mandatory)
+2. Mirror in `entry-points.json` → `entryPoints[0].input.properties` (and `.required`)
+3. Update `messages[1].content` and `contentTokens` if the field should appear in the user message
+4. Validate, then migrate
+
+### Add a File Input Field (`job-attachment`)
+
+1. Add the field as `{ "$ref": "#/definitions/job-attachment" }` in `agent.json` → `inputSchema.properties`
+2. Add the canonical `job-attachment` block to `inputSchema.definitions` (copy from § File Attachments — do not edit)
+3. Mirror both in `entry-points.json` → `entryPoints[0].input.properties` and `.definitions`
+4. Reference in the user message with `{{input.<fieldName>}}` if the agent should see file metadata
+5. To let the agent **read contents**, add a file-handling built-in tool — see [capabilities/built-in-tools/built-in-tools.md](capabilities/built-in-tools/built-in-tools.md)
+6. Validate, then migrate
+
+### Add an Output Field
+
+1. Add to `agent.json` → `outputSchema.properties`
+2. Mirror in `entry-points.json` → `entryPoints[0].output.properties`
+3. Validate, then migrate
+
+### Add a File Output Field (`job-attachment`)
+
+1. Add the field as `{ "$ref": "#/definitions/job-attachment" }` in `agent.json` → `outputSchema.properties`
+2. Add the canonical `job-attachment` block to `outputSchema.definitions`
+3. Mirror both in `entry-points.json` → `entryPoints[0].output.properties` and `.definitions`
+4. Validate, then migrate
+
+### Change Model Settings
+
+1. Edit `agent.json` → `settings.model`, `.temperature`, `.maxTokens`, or `.maxIterations`
+2. Discover valid model identifiers with `uip agent model list` and select per [model-selection-guide.md](model-selection-guide.md) — the tenant is the source of truth (availability and GA/preview status vary per tenant). Keep `maxTokens` ≤ the model's `MaxTokens` cap.
+3. Validate, then migrate
+
+### Capability-Adding Edits
+
+For edits that add a new tool, context, or escalation, see the capability registry in [lowcode.md](lowcode.md).
+
+## Auto-Generated Files (do not edit)
+
+| File | Managed By |
+|------|------------|
+| `flow-layout.json` | Studio Web |
+| `.agent-builder/*` | Generated by `uip agent migrate` and Studio Web — do not edit by hand |

package/skills/uipath-agents/references/lowcode/agent-prompting-guide.md

@@ -0,0 +1,149 @@
+# Agent Prompting Guide
+
+Robust prompts for low-code agents. This guide owns prompt **quality**; [agent-definition.md](agent-definition.md#contenttokens-construction) owns the `contentTokens` **mechanics** (keep `content` ↔ `contentTokens` in sync after every edit here).
+
+"Coding-agent-centric" = the prompt makes the embedded agent behave like a disciplined tool-using agent: explicit tool-call criteria, stop conditions, structured output. Maps to the agent's `tool` artifact ports and `outputSchema`.
+
+> Default scaffolds ship toy prompts ("You are an agentic assistant" / "What is the current date?"). Replace them. A placeholder system prompt is the single biggest quality gap in a scaffolded agent.
+
+## 1. System-prompt skeleton
+
+Copy this skeleton, fill every slot. Consistent structure → consistent runs. Put role/behavior here; data/task goes in the user message (§2).
+
+```text
+You are <ROLE> for <DOMAIN>. <ONE-LINE PURPOSE>.
+
+Scope:
+- In scope: <what the agent handles>
+- Out of scope: <what to refuse or escalate>
+
+Tools:
+- <toolName>: call when <explicit condition>. Do not call when <condition>.
+- <toolName>: ...
+Stop calling tools once <stop condition>; then produce the final answer.
+
+Output:
+- Return a result conforming to the output schema. <field>: <how to fill it>.
+- Never invent fields or values not grounded in the input or a tool result.
+
+Uncertainty:
+- If <required input> is missing or ambiguous, <ask | set field to null | escalate> — do not guess.
+- If you cannot complete the task, return <explicit failure shape>, not a fabricated answer.
+```
+
+Slot rules:
+
+- **Role + scope** — name the role, bound it. An unbounded agent answers off-task prompts.
+- **Tool-call criteria** — one trigger condition per tool, plus a stop condition. Without this the agent over-calls or loops to `maxIterations`.
+- **Output contract** — state that output MUST match `outputSchema`; map each field. Without it the agent free-forms prose.
+- **Grounding** — forbid values not traceable to input or tool output. Cuts hallucination.
+- **Iteration budget** — for multi-tool tasks, note the agent has limited iterations (`maxIterations`, default 25) and should act, not deliberate.
+
+## 2. User-prompt anatomy
+
+The user message carries the task and the data — not the role.
+
+```text
+<TASK INSTRUCTION>.
+
+<LABEL>: {{ $vars.<flowNodeId>.output.<field> }}
+<LABEL>: {{ $vars.<flowNodeId>.output.<field> }}
+
+<EXPLICIT OUTPUT INSTRUCTION — e.g. "Return the category and a one-sentence reason.">
+```
+
+Token form depends on context:
+
+- **Inline-in-flow agents** reference upstream flow nodes: `{{ $vars.<flowNodeId>.output[.<field>] }}`. See the [uipath-maestro-flow inline-agent prompt-wiring guide](../../../uipath-maestro-flow/references/author/references/plugins/inline-agent/impl.md#wiring-flow-variables-into-agent-prompts).
+- **Standalone agents** reference declared inputs: `{{input.<field>}}`.
+
+Mirror every `{{ ... }}` in `contentTokens[]` per [agent-definition.md § contentTokens Construction](agent-definition.md#contenttokens-construction).
+
+## 3. Grounding in wired data
+
+Reference inputs through tokens — never restate their literal contents in prose. The runtime injects the value; restating it duplicates tokens and risks drift if the upstream field changes. Tell the agent *what the field is*, not *what it contains*.
+
+## 4. Worked example — email triage
+
+Realistic inline-in-flow agent. Note the **structured `outputSchema`**, not a bare `content` blob.
+
+**Before (toy):**
+
+```json
+"settings": { "model": "gpt-4o-2024-11-20" },
+"outputSchema": { "type": "object", "properties": { "content": { "type": "string" } } },
+"messages": [
+  { "role": "system", "content": "You are an assistant." },
+  { "role": "user", "content": "Triage this email." }
+]
+```
+
+**After (robust):**
+
+```json
+"settings": { "model": "anthropic.claude-sonnet-4-6", "temperature": 0, "maxTokens": 4096, "maxIterations": 10 },
+"outputSchema": {
+  "type": "object",
+  "properties": {
+    "category": { "type": "string", "description": "One of: billing, technical, sales, other" },
+    "priority": { "type": "string", "description": "low | medium | high | urgent" },
+    "reason":   { "type": "string", "description": "One sentence justifying the category" },
+    "needsHuman": { "type": "boolean", "description": "true if the email requires human review" }
+  },
+  "required": ["category", "priority", "needsHuman"]
+}
+```
+
+System prompt (filled skeleton):
+
+```text
+You are a support-email triage classifier for a SaaS product. Classify each inbound email and flag those needing a human.
+
+Scope:
+- In scope: categorizing the email and assessing priority.
+- Out of scope: replying to the customer or taking any action — only classify.
+
+Output:
+- Return a result conforming to the output schema. category MUST be one of billing, technical, sales, other. priority MUST be low, medium, high, or urgent.
+- Set needsHuman=true for legal threats, churn risk, or anything outside the four categories.
+- Never invent customer details not present in the email.
+
+Uncertainty:
+- If the email is empty or unintelligible, set category="other", needsHuman=true, reason="unintelligible input".
+```
+
+User prompt:
+
+```text
+Classify the following email.
+
+From: {{ $vars.emailReceived1.output.from }}
+Subject: {{ $vars.emailReceived1.output.subject }}
+
+{{ $vars.emailReceived1.output.body }}
+
+Return category, priority, a one-sentence reason, and needsHuman.
+```
+
+## 5. Production checklist — adjacent `agent.json` quality fields
+
+A robust agent is more than its prompt. Each field: default, and when to change.
+
+| Field | Default | Change when |
+|-------|---------|-------------|
+| `outputSchema` | Scaffold gives a single `content` string | **Almost always** — define typed fields a downstream node can consume. Bare `content` forces brittle string-parsing. |
+| `settings.temperature` | `0` | Keep `0` for extraction/classification/judgment. Raise only when output *variation* is wanted (drafting, brainstorming). |
+| `settings.maxIterations` | `25` | Lower (≤5) for single-shot classification. Higher for multi-tool research loops. |
+| `settings.maxTokens` | Scaffold value | Set ≤ the model's `MaxTokens` cap — see [model-selection-guide.md](model-selection-guide.md#1-discover-primary-path). |
+| `settings.model` | `gpt-4o-2024-11-20` | **Always override** — discover + select per [model-selection-guide.md](model-selection-guide.md). |
+| `guardrails` | `[]` | Add input/output policy enforcement (PII, content, escalation). See [capabilities/guardrails/guardrails.md](capabilities/guardrails/guardrails.md). |
+
+## Anti-patterns
+
+- **Vague role** — "You are an assistant." Name the role and bound the scope.
+- **No output contract** — agent free-forms prose; downstream nodes can't parse it.
+- **Bare `content` output** — a single string where typed fields belong. Define `outputSchema`.
+- **No tool-call criteria** — agent over-calls tools or loops to `maxIterations`.
+- **Prompt-injection-prone passthrough** — pasting untrusted input into the system prompt. Keep untrusted data in the user message; keep instructions in the system message.
+- **Ignoring `outputSchema`** — prompt that doesn't tell the agent to conform to the declared schema.
+- **Cargo-culted `temperature`** — copying a nonzero temperature into a deterministic classification task.

package/skills/uipath-agents/references/lowcode/capabilities/built-in-tools/analyze-attachments.md

@@ -0,0 +1,115 @@
+# Analyze Files (`analyze-attachments`)
+
+Built-in tool that analyzes one or more `job-attachment` files with an LLM. Use it to extract, synthesize, or answer queries about file contents — the only way for a low-code agent to read attachment contents at runtime.
+
+For the built-in-tools capability overview, see [built-in-tools.md](built-in-tools.md).
+
+## When to Use
+
+- Agent has a `job-attachment` input field (or receives attachments inside a tool call) and must read contents
+- Agent must summarize, classify, or extract from PDFs, images, documents passed at runtime
+
+## Pairing Pattern
+
+Typical low-code shape: one `job-attachment` input field on the agent + one `analyze-attachments` tool resource. The user message references the attachment metadata with `{{input.<field>}}`; the agent calls `analyze-attachments`, passing the same attachment in `attachments[]` along with an `analysisTask`.
+
+## Resource Shape
+
+**Path:** `<AgentName>/resources/AnalyzeFiles/resource.json`
+
+```jsonc
+{
+  "$resourceType": "tool",
+  "id": "<FRESH_UUID>",
+  "referenceKey": null,
+  "name": "Analyze Files",
+  "type": "internal",
+  "description": "Analyze one or more files with an LLM to extract, synthesize, or answer queries about their content.",
+  "isEnabled": true,
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "attachments": {
+        "type": "array",
+        "items": { "$ref": "#/definitions/job-attachment" },
+        "description": "Array of files, documents, images, or other attachments to process"
+      },
+      "analysisTask": {
+        "type": "string",
+        "description": "The task, question, or instruction for processing the files (e.g., 'summarize this document', 'extract key points', 'what is in this image')"
+      }
+    },
+    "required": ["attachments", "analysisTask"],
+    "definitions": {
+      "job-attachment": {
+        "type": "object",
+        "properties": {
+          "ID":       { "type": "string", "description": "Orchestrator attachment key" },
+          "FullName": { "type": "string", "description": "File name" },
+          "MimeType": { "type": "string", "description": "MIME type, e.g. \"application/pdf\", \"image/png\"" },
+          "Metadata": {
+            "type": "object",
+            "description": "Dictionary<string, string> of metadata",
+            "additionalProperties": { "type": "string" }
+          }
+        },
+        "required": ["ID"],
+        "x-uipath-resource-kind": "JobAttachment"
+      }
+    }
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "analysis": {
+        "type": "string",
+        "description": "Analysis result of the attachments (analysis, summary, extracted information, etc.)"
+      }
+    },
+    "required": ["analysis"]
+  },
+  "settings": {},
+  "guardrail": { "policies": [] },
+  "argumentProperties": {},
+  "properties": {
+    "toolType": "analyze-attachments"
+  }
+}
+```
+
+Schema is canonical — copy verbatim. Only `id` (fresh UUID) and optionally `description` should differ.
+
+## Walkthrough
+
+1. **Add a file input field on the agent.** See [../../agent-definition.md](../../agent-definition.md) § Add a File Input Field. Mirror in `entry-points.json`.
+2. **Author the tool resource** at `resources/AnalyzeFiles/resource.json` using the shape above. Generate a fresh UUID for `id`.
+3. **Reference the attachment in the user message** so the agent sees its metadata:
+
+   ```jsonc
+   {
+     "role": "user",
+     "content": "Analyze the contents of the provided file and give a summary.\n\n{{input.fileIn}}",
+     "contentTokens": [
+       { "type": "simpleText", "rawString": "Analyze the contents of the provided file and give a summary.\n\n" },
+       { "type": "variable",   "rawString": "input.fileIn" }
+     ]
+   }
+   ```
+
+4. **Validate** with `uip agent validate "<AGENT_NAME>" --output json` (read-only). Confirm `MigrationPending`, `Validated`.
+5. **Migrate** with `uip agent migrate "<AGENT_NAME>" --output json`. Confirm `MigrationApplied`, `StorageVersion`.
+6. **Bundle and upload** with `uip solution bundle` then `uip solution upload --output json` (with user consent).
+7. **Test** from Studio Web or via Orchestrator job invocation — `uip` CLI cannot supply attachments at run time.
+
+## Gotchas
+
+- `properties.toolType` MUST be exactly `"analyze-attachments"` (kebab-lowercase). Anything else is silently ignored.
+- The `definitions.job-attachment` block belongs inside the tool's `inputSchema`, not at the agent root. Each schema (agent input, agent output, tool input) carries its own copy.
+- `{{input.<field>}}` only surfaces metadata; without this tool the agent has no way to read file contents. See [../../critical-rules.md](../../critical-rules.md) Critical Rule 18.
+- Agents can return a `job-attachment` from `outputSchema` (e.g. a generated file), but `analyze-attachments` itself only reads — it does not produce attachments.
+
+## References
+
+- [built-in-tools.md](built-in-tools.md) — capability overview
+- [../../agent-definition.md](../../agent-definition.md) § File Attachments — `job-attachment` schema
+- [../../critical-rules.md](../../critical-rules.md) Critical Rules 18–21