agent-workflow-builder

Files (1)

• SKILL.md

SKILL.md (first lines)

# Agent Workflow Builder

## When to Use

- Building a multi-agent workflow in the UI (`/app/localagent`)
- Understanding the Electron main process agent execution engine
- Configuring tool approval modes (auto-approve, ask every time, ask once)
- Debugging agent node execution failures

## Architecture

```
Layer 1: React UI (src/features/agent/)
  → Node graph with provider/model/tools per node
  → Sequential & simultaneous execution modes

Layer 2: IPC Bridge (electron/preload.ts → electron/Ipc/agentworkflowIpc.ts)
  → Sends workflow config to main process
  → Streams events back: node-start, node-stream, node-thinking, etc.

Layer 3: Agent Engine (electron/Agent/)
  → node-deepagent.ts — wraps deepagents package
  → provider.ts — LLM provider factory (10 providers)
  → workflow.ts — orchestrates multi-node execution
```

## Agent UI Structure

The agent feature lives in `src/features/agent/` and has its own store, components, and types:

```
features/agent/
├── api/api.ts              # Workflow execution via IPC
├── components/
│   ├── AgentBuilder.tsx     # Main workflow builder
│   ├── NodeEditor.tsx       # Configure individual nodes
│   └── WorkflowRunner.tsx   # Run & monitor execution
├── hooks/
├── store/store.ts          # Agent workflow state
├── types/type.ts           # Node, Edge, Workflow types
└── index.ts
```

## Node Configuration

Each agent node has:

```typescript
interface AgentNodeConfig {
  name: string;
  actor: string; // System prompt persona
  provider: string; // LLM provider (openai, anthropic, etc.)
  model: string; // Model name
  systemPrompt: string; // Custom system prompt override
  tools: string[]; // Tool group names to enable
  intent: string; // What the agent should accomplish
  autoApprove: "auto" | "ask_every_time" | "ask_once_per_session";
}
```

## Execution Modes

### 1. Specific Node (Single)

Execute one node in isolation. All other nodes are ignored.

### 2. Linear Sequence (Range)

Nodes execute in order from first to last. Each node's output feeds into the next.

```typescript
// workflow.ts handles this as sequential execution
for (const node of nodesInRange) {
  const agent = createDeepAgent({ ...node.config });
  const result = await agent.invoke({ messages });
  messages = result.messages; // Pass to next node
}
```

### 3. Simultaneous

Independent nodes execute in parallel. Results are merged.

```typescript
// workflow.ts handles this with Promise.all
const results = await Promise.all(
  independentNodes.map((node) => agent.invoke({ messages: node.input })),
);
```

## Tool Approval System

Defined in `electron/Ipc/agentworkflowIpc.ts`:

| Mode                   | Behavior                                                                      |
| ---------------------- | ----------------------------------------------------------------------------- |
| `auto`                 | Tool calls execute without user intervention                                  |
| `ask_every_time`       | Every tool call pauses and sends `tool-approval-response` request to renderer |
| `ask_once_per_session` | First tool call asks; subsequent calls auto-approved within same session      |

The approval flow:

1. Agent hits a write tool → workflow pauses via `interruptOn`
2. Renderer shows `ToolApprovalDialog`
3. User approves/rejects → `tool-approval-response` sent via IPC
4. Workflow resumes with `new Command({ resume: ... })`

## Provider Factory

Defined in `electron/Agent/provider.ts`. Supports 10 providers:

| Provider         | Package                   | Model Prefix                                   |
| ---------------- | ------------------------- | ---------------------------------------------- |
| OpenAI           | `@langchain/openai`       | `gpt-4o`, `gpt-4o-mini`, `o1`, `o3`, `o4-mini` |
| Anthropic        | `@langchain/anthropic`    | `claude-3.5-sonnet`, `claude-3-opus`           |
| Google Gemini    | `@langchain/google-genai` | `gemini-*`                                     |
| Groq             | `@langchain/groq`         | `llama-*`, `mixtral-*`                         |
| OpenRouter       | `@langchain/openrouter`   | Any                                            |
| Mistral          | `@langchain/mistralai`    | `mistral-*`, `codestral-*`                     |

From NarihitoM/MultimateAi, MIT.

More from NarihitoM/MultimateAi