> ## Documentation Index
> Fetch the complete documentation index at: https://developer.watson-orchestrate.ibm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agentic Workflow Advisor skill

The Agentic Workflow Advisor is a skill that analyses IBM watsonx Orchestrate agentic workflow artefacts and returns prioritised architecture recommendations. Use it to catch design issues before they reach production, without needing engineering support.

The skill performs static analysis on your agentic workflow artefact and runs six detection checks across the patterns that most commonly cause performance problems, routing failures, or maintenance issues in production.

| Check | Pattern                                                                                    | Impact    |
| ----- | ------------------------------------------------------------------------------------------ | --------- |
| 1     | Sequential nodes with no data dependency between them                                      | 🔴 High   |
| 2     | Required input fields with no explicit mapping, or unmapped agentic workflow output fields | 🟡 Medium |
| 3     | LLM-based routing over a deterministic upstream result                                     | 🔴 High   |
| 4     | Input schema with more than 20 fields                                                      | 🟢 Low    |
| 5     | Toolkit tool node with no external HTTP calls                                              | 🟢 Low    |
| 6     | Agent node that a Generative Prompt node could replace                                     | 🟡 Medium |

Each finding includes what the skill observed, why it matters with measured latency figures, and a specific recommended action. Findings are grouped by impact level so you can address the most important issues first.

The skill works from the artefact you provide. It does not invoke, modify, or connect to any active agentic workflow or platform API.

Use the Agentic Workflow Advisor when you want to:

* Review an agentic workflow before deploying it to production
* Diagnose an agentic workflow with slow response times or unexpected routing failures
* Get an actionable design review without escalating to engineering

## Distribution

The skill is available through two channels:

| Channel | How to access                                                                                                                                                        |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bob** | Auto-activates in Bob chat when you use a trigger phrase. No setup required.                                                                                         |
| **ADK** | Available at `skills/agentic-workflow-advisor/` in the [ibm-watsonx-orchestrate-adk](https://github.com/IBM/ibm-watsonx-orchestrate-adk/tree/main/skills) repository |

## Activation

In Bob, the skill activates automatically when you include one of the following phrases in your message:

* `Review my agentic workflow`
* `Analyze my agentic workflow`
* `Audit this flow`
* `What architecture issues does my agentic workflow have?`
* `Run an agentic workflow advisor check on this`

No manual setup or configuration is required.

## Required artefacts

| Artefact              | Required | Notes                                                      |
| --------------------- | -------- | ---------------------------------------------------------- |
| Agentic workflow JSON | Yes      | Export from the Flow Builder UI or the ADK pro-code path   |
| Agent YAML            | No       | Provides additional context for LLM-based routing analysis |

Paste the artefact directly into the chat or attach the file.

## Scope and Limitations

* **All agentic workflows are in scope.** The skill evaluates any watsonx Orchestrate agentic workflow JSON. Checks that target a specific node kind produce no findings if that node kind is absent.
* **Static analysis only.** The skill does not invoke, modify, or connect to any active agentic workflow or platform API.
* **No automated remediation.** The skill identifies and explains issues. It does not rewrite the agentic workflow.
* **Agent YAML is optional.** All checks run from the agentic workflow JSON alone. The agent YAML adds depth to the LLM-based routing analysis.
* **Check 5 runs from description alone.** No toolkit Python source is needed. The skill infers the finding from the node's `description` and `display_name`.
* **Check 6 considers `thread_control_policy`.** When `REUSE_AND_CORRELATE` is set on the agent node, the recommendation notes that a Generative Prompt node cannot maintain conversation context continuity.

## Example

### Prompts

Paste an agentic workflow JSON inline:

```
Review my agentic workflow

<paste agentic workflow JSON here>
```

Attach an agentic workflow JSON and an optional agent YAML:

```
Run an agentic workflow advisor check on these files — I've attached the agentic workflow JSON and agent YAML.
```

### Output

The skill returns a structured report grouped by impact level. Each finding has three fields: what the skill observed, why it matters, and what to do about it.

```md [expandable] theme={null}
## Agentic Workflow Advisor — customer_support_flow

### 🔴 High Impact

**Sequential tool execution**
- Observed: Nodes `get_account_details`, `get_order_history`, and `get_open_tickets` are connected sequentially with no data dependencies between them
- Why it matters: Each tool averages ~1.5s. Running sequentially costs ~4.5s; running in parallel costs ~1.5s — a saving of ~3s per invocation
- Recommended action: Wrap all three nodes in a Parallel Node

**LLM-based routing over deterministic result**
- Observed: Agent node `intent_router` receives the output of `feature_match_tool` (a fixed category string) and routes to downstream flows based on it
- Why it matters: Passing a deterministic result through an agent ReACT loop adds 2–10s per turn and introduces routing failures due to LLM variability
- Recommended action: Replace `intent_router` with a Master Flow using Branch (Match) nodes that evaluate the feature match output directly

### 🟡 Medium Impact

**Unmapped required input field**
- Observed: Node `create_ticket` has required field `customer_id` with no explicit mapping in input_map
- Why it matters: The runtime will use an LLM to resolve this field at execution time — this always costs 500–3000ms per invocation. Explicit mapping costs <10ms.
- Recommended action: Add an explicit mapping for `customer_id`. If this latency is acceptable for the use case, no action is needed.

### 🟢 Low Impact / Housekeeping

**Oversized input schema**
- Observed: The top-level flow input schema defines 34 fields
- Why it matters: Large schemas increase token usage on every auto-mapping call and agent context retrieval
- Recommended action: Audit which fields are actually read inside the flow and remove unused ones

---
_Review scope: workflow JSON ✅ | agent YAML ❌ not provided_
```