@aigne/example-workflow-orchestrator 1.13.87 → 1.14.0-beta.1

package/README.md

@@ -8,43 +8,38 @@
   </picture>
 </p>
 
-This is a demonstration of using [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) to build an orchestrator workflow. The example now supports both one-shot and interactive chat modes, along with customizable model settings and pipeline input/output.
+This is a demonstration of using [AIGNE Framework](https://github.com/AIGNE-io/aigne-framework) to build an orchestrator workflow using YAML configuration. The orchestrator pattern enables autonomous task planning and execution through a planner-worker-completer architecture.
+
+## Architecture
+
+The orchestrator follows a three-phase workflow:
 
 ```mermaid
 flowchart LR
-
-in(In)
-out(Out)
-orchestrator(Orchestrator)
-synthesizer(Synthesizer)
-finder(Finder)
-writer(Writer)
-proofreader(Proofreader)
-fact_checker(Fact Checker)
-style_enforcer(Style Enforcer)
-
-in ==> orchestrator
-orchestrator -.-> finder -.-> synthesizer
-orchestrator -.-> writer -.-> synthesizer
-orchestrator -.-> proofreader -.-> synthesizer
-orchestrator -.-> fact_checker -.-> synthesizer
-orchestrator -.-> style_enforcer -.-> synthesizer
-synthesizer ==> out
-
-classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px,color:#b35b39,font-weight:bolder;
-classDef processing fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px,color:#6B8F3C,font-weight:bolder;
-
-class in inputOutput
-class out inputOutput
-class orchestrator processing
-class synthesizer processing
-class finder processing
-class writer processing
-class proofreader processing
-class fact_checker processing
-class style_enforcer processing
+    Input([User Objective]) --> Planner
+    Planner -->|Next Task| Worker
+    Worker -->|Task Result| State[Execution State]
+    State --> Planner
+    Planner -->|Finished| Completer
+    Completer --> Output([Final Response])
+
+    Skills[Skills/Tools] -.->|Available to| Worker
+
+    classDef inputOutput fill:#f9f0ed,stroke:#debbae,stroke-width:2px,color:#b35b39,font-weight:bolder
+    classDef agent fill:#F0F4EB,stroke:#C2D7A7,stroke-width:2px,color:#6B8F3C,font-weight:bolder
+    classDef resource fill:#E8F4F8,stroke:#4A9EBF,stroke-width:2px,color:#2B5F75,font-weight:bolder
+
+    class Input,Output inputOutput
+    class Planner,Worker,Completer agent
+    class State,Skills resource
 ```
 
+**Components:**
+- **Planner**: Analyzes the objective and execution state to determine the next task
+- **Worker**: Executes assigned tasks using available skills and tools
+- **Completer**: Synthesizes all results and provides the final response
+- **Execution State**: Tracks task history, results, and progress
+
 ## Prerequisites
 
 * [Node.js](https://nodejs.org) (>=20.0) and npm installed on your machine
@@ -53,20 +48,64 @@ class style_enforcer processing
   * [Bun](https://bun.sh) for running unit tests & examples
   * [Pnpm](https://pnpm.io) for package management
 
-## Quick Start (No Installation Required)
+## Quick Start
+
+The orchestrator is configured using YAML files. This example uses:
+- [aigne.yaml](./aigne.yaml) - Main configuration file
+- [agents/orchestrator.yaml](./agents/orchestrator.yaml) - Orchestrator agent definition
+- [agents/objective.md](./agents/objective.md) - Objective prompt template
+- [agents/planner.md](./agents/planner.md) - Custom planner instructions
+
+### Run with npx (No Installation Required)
 
 ```bash
-export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # Set your OpenAI API key
+export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # Set your API key
+export GEMINI_API_KEY=YOUR_GEMINI_API_KEY # Or use Gemini
 
-# Run in one-shot mode (default)
+# Run the orchestrator
 npx -y @aigne/example-workflow-orchestrator
+```
+
+### Connect to an AI Model
+
+As an example, running `npx -y @aigne/example-workflow-orchestrator --chat` requires an AI model. If this is your first run, you need to connect one.
+
+![run example](./run-example.png)
 
-# Run in interactive chat mode
-npx -y @aigne/example-workflow-orchestrator --chat
+- Connect via the official AIGNE Hub
 
-# Use pipeline input
-echo "Research ArcBlock and compile a report about their products and architecture" | npx -y @aigne/example-workflow-orchestrator
+Choose the first option and your browser will open the official AIGNE Hub page. Follow the prompts to complete the connection. If you're a new user, the system automatically grants 400,000 tokens for you to use.
+
+![connect to official aigne hub](../images/connect-to-aigne-hub.png)
+
+- Connect via a self-hosted AIGNE Hub
+
+Choose the second option, enter the URL of your self-hosted AIGNE Hub, and follow the prompts to complete the connection. If you need to set up a self-hosted AIGNE Hub, visit the Blocklet Store to install and deploy it: [Blocklet Store](https://store.blocklet.dev/blocklets/z8ia3xzq2tMq8CRHfaXj1BTYJyYnEcHbqP8cJ?utm_source=www.arcblock.io&utm_medium=blog_link&utm_campaign=default&utm_content=store.blocklet.dev#:~:text=%F0%9F%9A%80%20Get%20Started%20in%20Minutes).
+
+![connect to self hosted aigne hub](../images/connect-to-self-hosted-aigne-hub.png)
+
+- Connect via a third-party model provider
+
+Using OpenAI as an example, you can configure the provider's API key via environment variables. After configuration, run the example again:
+
+```bash
+export OPENAI_API_KEY="" # Set your OpenAI API key here
 ```
+For more details on third-party model configuration (e.g., OpenAI, DeepSeek, Google Gemini), see [.env.local.example](./.env.local.example).
+
+After configuration, run the example again.
+
+### Debugging
+
+The `aigne observe` command starts a local web server to monitor and analyze agent execution data. It provides a user-friendly interface to inspect traces, view detailed call information, and understand your agent’s behavior during runtime. This tool is essential for debugging, performance tuning, and gaining insight into how your agent processes information and interacts with tools and models.
+
+Start the observation server.
+
+![aigne-observe-execute](../images/aigne-observe-execute.png)
+
+View a list of recent executions.
+
+![aigne-observe-list](../images/aigne-observe-list.png)
 
 ## Installation
 
@@ -115,126 +154,112 @@ You can use different AI models by setting the `MODEL` environment variable alon
 
 For detailed configuration examples, please refer to the `.env.local.example` file in this directory.
 
-### Run the Example
+### Run from Source
 
 ```bash
-pnpm start # Run in one-shot mode (default)
+cd examples/workflow-orchestrator
+pnpm start
+```
 
-# Run in interactive chat mode
-pnpm start -- --chat
+You can pass custom messages to the orchestrator:
+
+```bash
+# Pass message via command line
+pnpm start -- -m "Analyze the project structure"
 
-# Use pipeline input
-echo "Research ArcBlock and compile a report about their products and architecture" | pnpm start
+# Or use YAML input
+pnpm start -- --input-yaml '{ message: "Generate a README for this project" }'
 ```
 
-### Run Options
+## Configuration
 
-The example supports the following command-line parameters:
+### Main Configuration (aigne.yaml)
 
-| Parameter | Description | Default |
-|-----------|-------------|---------|
-| `--chat` | Run in interactive chat mode | Disabled (one-shot mode) |
-| `--model <provider[:model]>` | AI model to use in format 'provider\[:model]' where model is optional. Examples: 'openai' or 'openai:gpt-4o-mini' | openai |
-| `--temperature <value>` | Temperature for model generation | Provider default |
-| `--top-p <value>` | Top-p sampling value | Provider default |
-| `--presence-penalty <value>` | Presence penalty value | Provider default |
-| `--frequency-penalty <value>` | Frequency penalty value | Provider default |
-| `--log-level <level>` | Set logging level (ERROR, WARN, INFO, DEBUG, TRACE) | INFO |
-| `--input`, `-i <input>` | Specify input directly | None |
+```yaml
+#!/usr/bin/env aigne
 
-#### Examples
+model: aignehub/google/gemini-2.5-pro
+agents:
+  - agents/orchestrator.yaml
+```
 
-```bash
-# Run in chat mode (interactive)
-pnpm start -- --chat
+### Orchestrator Configuration (agents/orchestrator.yaml)
+
+```yaml
+type: "@aigne/agent-library/orchestrator"
+name: orchestrator
+input_schema:
+  type: object
+  properties:
+    message:
+      type: string
+      description: (Optional) User's instruction
+  required: []
+
+# Specify the objective for the orchestrator agent
+objective:
+  url: objective.md
+
+# Custom planner agent can be defined here
+planner:
+  type: ai
+  instructions:
+    url: planner.md
+
+# Custom worker agent (optional)
+# worker:
+#   type: ai
+#   instructions:
+#     url: path/to/worker_instructions.md
+
+# Custom completer agent (optional)
+# completer:
+#   type: ai
+#   instructions:
+#     url: path/to/completer_instructions.md
+
+# State management configuration
+state_management:
+  max_iterations: 5              # Maximum planning-execution iterations
+  max_tokens: 100000            # Optional: limit total tokens for state management
+  keep_recent: 20               # Optional: keep only N most recent states in memory
+
+# Agent File System configuration
+afs:
+  modules:
+    - module: local-fs
+      options:
+        name: workspace
+        localPath: .
+        description: Workspace directory for the orchestrator agent.
+```
 
-# Set logging level
-pnpm start -- --log-level DEBUG
+### Objective Template (agents/objective.md)
 
-# Use pipeline input
-echo "Research ArcBlock and compile a report about their products and architecture" | pnpm start
-```
+```markdown
+Explore the project directory `/modules/workspace/` structure and generate a project summary report in Markdown format.
+
+- Ignore directories like node_modules, .git, dist, build, etc.
+- Provide accurate information based on actual file contents
 
-## Example
-
-The following example demonstrates how to build a orchestrator workflow:
-
-Here is the generated report for this example: [arcblock-deep-research.md](./generated-report-arcblock.md)
-
-```typescript
-import { OrchestratorAgent } from "@aigne/agent-library/orchestrator/index.js";
-import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
-import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";
-
-const { OPENAI_API_KEY } = process.env;
-
-const model = new OpenAIChatModel({
-  apiKey: OPENAI_API_KEY,
-  modelOptions: {
-    parallelToolCalls: false, // puppeteer can only run one task at a time
-  },
-});
-
-const puppeteer = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-puppeteer"],
-  env: process.env as Record<string, string>,
-});
-
-const filesystem = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-filesystem", import.meta.dir],
-});
-
-const finder = AIAgent.from({
-  name: "finder",
-  description: "Find the closest match to a user's request",
-  instructions: `You are an agent that can find information on the web.
-You are tasked with finding the closest match to the user's request.
-You can use puppeteer to scrape the web for information.
-You can also use the filesystem to save the information you find.
-
-Rules:
-- do not use screenshot of puppeteer
-- use document.body.innerText to get the text content of a page
-- if you want a url to some page, you should get all link and it's title of current(home) page,
-then you can use the title to search the url of the page you want to visit.
-  `,
-  skills: [puppeteer, filesystem],
-});
-
-const writer = AIAgent.from({
-  name: "writer",
-  description: "Write to the filesystem",
-  instructions: `You are an agent that can write to the filesystem.
-  You are tasked with taking the user's input, addressing it, and
-  writing the result to disk in the appropriate location.`,
-  skills: [filesystem],
-});
-
-const agent = OrchestratorAgent.from({
-  skills: [finder, writer],
-  maxIterations: 3,
-  tasksConcurrency: 1, // puppeteer can only run one task at a time
-});
-
-const aigne = new AIGNE({ model });
-
-const result = await aigne.invoke(
-  agent,
-  `\
-Conduct an in-depth research on ArcBlock using only the official website\
-(avoid search engines or third-party sources) and compile a detailed report saved as arcblock.md. \
-The report should include comprehensive insights into the company's products \
-(with detailed research findings and links), technical architecture, and future plans.`,
-);
-console.log(result);
-// Output:
-// {
-//   $message: "The objective of conducting in-depth research on ArcBlock using only the official website has been successfully completed...",
-// }
+{% if message %}
+## User Instructions
+{{ message }}
+{% endif %}
 ```
 
+### Custom Planner Instructions (agents/planner.md)
+
+The planner is responsible for iterative task planning. See [agents/planner.md](./agents/planner.md) for the full custom planner prompt that enables autonomous exploration and task decomposition.
+
+### Key Features
+
+1. **YAML-based Configuration**: Define your orchestrator workflow declaratively
+2. **Customizable Components**: Override planner, worker, or completer with custom instructions
+3. **State Management**: Control iteration limits and memory usage
+4. **Agent File System**: Shared storage accessible to all agent components
+5. **Template Support**: Use Jinja2-style templates in objective prompts
+
 ## License
 
 This project is licensed under the MIT License.

package/aigne.yaml

@@ -0,0 +1,5 @@
+#!/usr/bin/env aigne
+
+model: aignehub/google/gemini-2.5-pro
+agents:
+  - agents/orchestrator.yaml

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aigne/example-workflow-orchestrator",
-  "version": "1.13.87",
+  "version": "1.14.0-beta.1",
   "description": "A demonstration of using AIGNE Framework to build a orchestrator workflow",
   "author": "Arcblock <blocklet@arcblock.io> https://github.com/blocklet",
   "homepage": "https://github.com/AIGNE-io/aigne-framework/tree/main/examples/workflow-orchestrator",
@@ -9,24 +9,21 @@
     "type": "git",
     "url": "git+https://github.com/AIGNE-io/aigne-framework"
   },
-  "bin": "index.ts",
+  "bin": "aigne.yaml",
   "files": [
     ".env.local.example",
     "*.ts",
     "README.md"
   ],
   "dependencies": {
-    "@aigne/agent-library": "^1.22.4",
-    "@aigne/openai": "^0.16.14",
-    "@aigne/core": "^1.70.1",
-    "@aigne/cli": "^1.57.3"
+    "@aigne/agent-library": "^1.23.0-beta.1",
+    "@aigne/cli": "^1.58.0-beta.1"
   },
   "devDependencies": {
     "@types/bun": "^1.2.22",
-    "@aigne/test-utils": "^0.5.67"
+    "@aigne/test-utils": "^0.5.68-beta.1"
   },
   "scripts": {
-    "start": "bun run index.ts",
-    "lint": "tsc --noEmit"
+    "start": "aigne run ."
   }
 }

package/index.ts

@@ -1,64 +0,0 @@
-#!/usr/bin/env bunwrapper
-
-import { OrchestratorAgent } from "@aigne/agent-library/orchestrator/index.js";
-import { runWithAIGNE } from "@aigne/cli/utils/run-with-aigne.js";
-import { AIAgent, MCPAgent } from "@aigne/core";
-
-const puppeteer = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-puppeteer"],
-  env: process.env as Record<string, string>,
-});
-
-const filesystem = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-filesystem", import.meta.dir],
-});
-
-const finder = AIAgent.from({
-  name: "finder",
-  description: "Find the closest match to a user's request",
-  instructions: `You are an agent that can find information on the web.
-You are tasked with finding the closest match to the user's request.
-You can use puppeteer to scrape the web for information.
-You can also use the filesystem to save the information you find.
-
-Rules:
-- do not use screenshot of puppeteer
-- use document.body.innerText to get the text content of a page
-- if you want a url to some page, you should get all link and it's title of current(home) page,
-then you can use the title to search the url of the page you want to visit.
-  `,
-  skills: [puppeteer, filesystem],
-});
-
-const writer = AIAgent.from({
-  name: "writer",
-  description: "Write to the filesystem",
-  instructions: `You are an agent that can write to the filesystem.
-  You are tasked with taking the user's input, addressing it, and
-  writing the result to disk in the appropriate location.`,
-  skills: [filesystem],
-});
-
-const agent = OrchestratorAgent.from({
-  skills: [finder, writer],
-  maxIterations: 3,
-  tasksConcurrency: 1, // puppeteer can only run one task at a time
-  inputKey: "message",
-});
-
-await runWithAIGNE(agent, {
-  modelOptions: { parallelToolCalls: false },
-  chatLoopOptions: {
-    welcome: "Welcome to the Orchestrator Agent!",
-    inputKey: "message",
-    defaultQuestion: `\
-  Conduct an in-depth research on ArcBlock using only the official website\
-  (avoid search engines or third-party sources) and compile a detailed report saved as arcblock.md. \
-  The report should include comprehensive insights into the company's products \
-  (with detailed research findings and links), technical architecture, and future plans.`,
-  },
-});
-
-process.exit(0);

package/usage.ts

@@ -1,73 +0,0 @@
-import assert from "node:assert";
-import { OrchestratorAgent } from "@aigne/agent-library/orchestrator/index.js";
-import { AIAgent, AIGNE, MCPAgent } from "@aigne/core";
-import { OpenAIChatModel } from "@aigne/openai";
-
-const { OPENAI_API_KEY } = process.env;
-assert(OPENAI_API_KEY, "Please set the OPENAI_API_KEY environment variable");
-
-const model = new OpenAIChatModel({
-  apiKey: OPENAI_API_KEY,
-  modelOptions: {
-    parallelToolCalls: false, // puppeteer can only run one task at a time
-  },
-});
-
-const puppeteer = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-puppeteer"],
-  env: process.env as Record<string, string>,
-});
-
-const filesystem = await MCPAgent.from({
-  command: "npx",
-  args: ["-y", "@modelcontextprotocol/server-filesystem", import.meta.dir],
-});
-
-const finder = AIAgent.from({
-  name: "finder",
-  description: "Find the closest match to a user's request",
-  instructions: `You are an agent that can find information on the web.
-You are tasked with finding the closest match to the user's request.
-You can use puppeteer to scrape the web for information.
-You can also use the filesystem to save the information you find.
-
-Rules:
-- do not use screenshot of puppeteer
-- use document.body.innerText to get the text content of a page
-- if you want a url to some page, you should get all link and it's title of current(home) page,
-then you can use the title to search the url of the page you want to visit.
-  `,
-  skills: [puppeteer, filesystem],
-});
-
-const writer = AIAgent.from({
-  name: "writer",
-  description: "Write to the filesystem",
-  instructions: `You are an agent that can write to the filesystem.
-  You are tasked with taking the user's input, addressing it, and
-  writing the result to disk in the appropriate location.`,
-  skills: [filesystem],
-});
-
-const agent = OrchestratorAgent.from({
-  skills: [finder, writer],
-  maxIterations: 3,
-  tasksConcurrency: 1, // puppeteer can only run one task at a time
-  inputKey: "message",
-});
-
-const aigne = new AIGNE({ model });
-
-const result = await aigne.invoke(agent, {
-  message: `\
-Conduct an in-depth research on ArcBlock using only the official website\
-(avoid search engines or third-party sources) and compile a detailed report saved as arcblock.md. \
-The report should include comprehensive insights into the company's products \
-(with detailed research findings and links), technical architecture, and future plans.`,
-});
-console.log(result);
-// Output:
-// {
-//   message: "The objective of conducting in-depth research on ArcBlock using only the official website has been successfully completed...",
-// }