Workflow code-execution Demo

This is a demonstration of using AIGNE Framework to build a code-execution workflow. The example now supports both one-shot and interactive chat modes, along with customizable model settings and pipeline input/output.

flowchart LR

in(In)
out(Out)
coder(Coder)
sandbox(Sandbox)

coder -.-> sandbox
sandbox -.-> coder
in ==> coder ==> 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 coder processing
class sandbox processing

Workflow of a code-execution between user and coder using a sandbox:

sequenceDiagram

participant User
participant Coder as Agent Coder
participant Sandbox as Agent Sandbox

User ->> Coder: 10! = ?
Coder ->> Sandbox: "function factorial(n) { return n <= 1 ? 1 : n * factorial(n - 1) } factorial(10)"
Sandbox ->> Coder: { result: 3628800 }
Coder ->> User: The value of \(10!\) (10 factorial) is 3,628,800.

Prerequisites

• Node.js (>=20.0) and npm installed on your machine
• An OpenAI API key for interacting with OpenAI's services
• Optional dependencies (if running the example from source code):
  • Bun for running unit tests & examples
  • Pnpm for package management

Quick Start (No Installation Required)

Run the Example

# Run in one-shot mode (default)
npx -y @aigne/example-workflow-code-execution

# Run in interactive chat mode
npx -y @aigne/example-workflow-code-execution --interactive

# Use pipeline input
echo 'Calculate 15!' | npx -y @aigne/example-workflow-code-execution

Connect to an AI Model

As an example, running npx -y @aigne/example-workflow-code-execution --interactive requires an AI model. If this is your first run, you need to connect one.

• Connect via the official AIGNE Hub

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 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.

• 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:

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.

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.

View a list of recent executions.

Installation

Clone the Repository

git clone https://github.com/AIGNE-io/aigne-framework

Install Dependencies

cd aigne-framework/examples/workflow-code-execution

pnpm install

Run the Example

pnpm start # Run in one-shot mode (default)

# Run in interactive chat mode
pnpm start -- --interactive

# Use pipeline input
echo "Calculate 15!" | pnpm start

Run Options

The example supports the following command-line parameters:

Parameter	Description	Default
--interactive	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

Examples

# Run in chat mode (interactive)
pnpm start -- --interactive

# Set logging level
pnpm start -- --log-level DEBUG

# Use pipeline input
echo "Calculate 15!" | pnpm start

Example

The following example demonstrates how to build a code-execution workflow:

import { AIAgent, AIGNE, FunctionAgent } from "@aigne/core";
import { OpenAIChatModel } from "@aigne/core/models/openai-chat-model.js";
import { z } from "zod";

const { OPENAI_API_KEY } = process.env;

const model = new OpenAIChatModel({
  apiKey: OPENAI_API_KEY,
});

const sandbox = FunctionAgent.from({
  name: "evaluateJs",
  description: "A js sandbox for running javascript code",
  inputSchema: z.object({
    code: z.string().describe("The code to run"),
  }),
  process: async (input: { code: string }) => {
    const { code } = input;
    // biome-ignore lint/security/noGlobalEval: <explanation>
    const result = eval(code);
    return { result };
  },
});

const coder = AIAgent.from({
  name: "coder",
  instructions: `\
You are a proficient coder. You write code to solve problems.
Work with the sandbox to execute your code.
`,
  skills: [sandbox],
});

const aigne = new AIGNE({ model });

const result = await aigne.invoke(coder, "10! = ?");
console.log(result);
// Output:
// {
//   $message: "The value of \\(10!\\) (10 factorial) is 3,628,800.",
// }

License

This project is licensed under the MIT License.