Welcome to AIPack: Your Agentic Runtime for AI

Building sophisticated AI agents that can tackle real-world problems isn’t just about crafting clever prompts. It’s about orchestrating complex workflows, managing context, integrating diverse tools, and ensuring your agents are reliable and shareable. Without a robust system, these challenges quickly lead to unmanageable, brittle AI applications. This is precisely where AIPack steps in.

This guide will take you on a journey from zero to mastery with AIPack, an open-source agentic runtime designed to simplify the entire lifecycle of AI agents. In this first chapter, you’ll learn how to install AIPack, understand its core architecture, and build your very first intelligent agent. By the end, you’ll have a foundational understanding of how to define, run, and interact with an AIPack agent, setting the stage for more advanced capabilities in your daily AI-assisted software engineering workflows.

AIPack: Your Agentic Runtime for AI

Imagine you want to create an AI assistant that can do more than just answer questions; you want it to perform multi-step tasks, like analyzing a codebase, generating documentation, or even managing cloud resources. This requires a robust framework that can handle the agent’s internal logic, its communication with large language models (LLMs), and its interaction with the outside world.

📌 Key Idea: AIPack is an open-source framework that provides the infrastructure (the “runtime”) for building, executing, and sharing complex AI agents. It acts as the operating system for your AI agents.

Without a dedicated runtime like AIPack, you’d manually handle every aspect: crafting prompts, calling LLM APIs, parsing responses, and orchestrating subsequent steps in your code. This quickly becomes a complex and error-prone process. AIPack streamlines this by providing a structured way to define these agents using a combination of markdown and Lua logic. This approach makes agents more modular, readable, and significantly easier to manage as they grow in complexity.

How the Agentic Runtime Orchestrates Tasks

Consider the journey of a simple command you give to an agent. AIPack streamlines this entire process, providing the execution environment, parsing your agent’s definition, managing the flow between different stages, and handling the interaction with your chosen AI models.

Here’s a simplified view of how AIPack orchestrates an agent’s interaction:

⚡ Real-world insight: In production environments, this orchestration is crucial for reliability. AIPack ensures consistent execution, proper context management, and predictable interactions with various AI models, preventing common issues like lost context or misinterpretation.

The Power of .aip Files: Packaging and Sharing Agents

At the heart of AIPack lies the .aip file. Think of it as a blueprint and a portable package for your AI agent. Just as a .zip file bundles software or a .tar.gz bundles source code, an .aip file bundles everything needed to define and run an AIPack agent.

What’s typically inside an .aip file?

• Agent Definition: Written in a specialized markdown format, this outlines the different stages or steps of your agent’s workflow.
• Lua Logic: For more advanced control flow, conditional execution, and complex operations, you can embed Lua scripts directly within your .aip file.
• Configuration: Metadata about the agent, its dependencies, and how it should interact with LLM providers.

This single-file packaging makes agents incredibly portable and shareable. You can easily distribute your .aip files, allowing others to run your agents consistently across different environments, assuming they have AIPack installed. This is vital for collaborative development and for building reusable AI components.

Multi-Stage Markdown Agents: Workflow in Plain Sight

One of AIPack’s most intuitive features is its use of multi-stage markdown agents. Instead of opaque code, your agent’s workflow is defined in clear, human-readable markdown. Each section of the markdown represents a distinct “stage” in your agent’s thought process or action sequence.

Why use markdown for agent definition? It enhances readability and makes the agent’s logic transparent. Anyone can quickly grasp the agent’s intended flow just by reading the .aip file.

For example, an agent might have stages like:

1. # Stage: analyze_request - Understand the user’s initial query.
2. # Stage: plan_action - Determine the necessary steps to fulfill the request.
3. # Stage: execute_tool - Call an external tool or API.
4. # Stage: summarize_result - Present the final outcome to the user.

AIPack executes these stages sequentially, passing the output of one stage as context to the next. This structured approach makes it easy to understand, debug, and extend complex agent behaviors. Later, we’ll see how Lua logic can introduce conditional branching and loops, turning simple sequences into powerful, dynamic agents.

Setting Up Your AIPack Environment

Before we can build our first agent, we need to set up our development environment. This involves installing AIPack itself and configuring a local AI model provider, Ollama, which is excellent for development due to its ease of use and privacy benefits.

Prerequisites

You’ll need a few essential tools ready on your system:

• Python (3.9+): AIPack is a Python-based tool. Ensure you have a recent, stable version installed.
• Git: For cloning repositories, if you choose to explore examples, and for general version control.
• VS Code (Recommended): While not strictly required for running agents, VS Code offers powerful extensions and an integrated development experience that we’ll leverage in later chapters for a streamlined workflow.

Step 1: Install the AIPack CLI

AIPack provides a command-line interface (CLI) tool that allows you to initialize, run, and manage your agents. We’ll install it using pip, Python’s package installer.

1. Open your terminal or command prompt.

2. Install AIPack: As of 2026-05-17, the latest stable version of AIPack can be installed directly from PyPI.

   pip install aipack
   

   This command downloads and installs the AIPack CLI and its necessary dependencies.

3. Verify the installation: After installation, it’s good practice to check if AIPack is correctly installed and to confirm its version.

   aipack --version
   

   You should see output similar to aipack, version X.Y.Z (e.g., aipack, version 0.1.5). If you encounter a “command not found” error, ensure your Python Scripts directory (or equivalent on your OS) is correctly added to your system’s PATH environment variable.

Step 2: Install Ollama (Local AI Model Provider)

For local development, running AI models on your own machine is incredibly convenient. Ollama makes this easy by providing a simple way to download, run, and manage various open-source LLMs directly on your desktop.

1. Download Ollama: Visit the official Ollama website: https://ollama.com/download Download and install the appropriate version for your operating system (macOS, Linux, Windows). Follow the straightforward installation instructions provided on their site.

2. Run Ollama: Once installed, Ollama typically runs as a background service. You can verify it’s running by opening your terminal and attempting to pull a model.

3. Pull an AI Model: Let’s pull a small, efficient model like llama3 to get started. This model is excellent for local development and testing, offering a good balance of performance and resource usage.

   ollama pull llama3
   

   This command will download the llama3 model. Depending on your internet connection and the model size, this might take a few minutes. You’ll observe a progress bar during the download.

   ⚡ Quick Note: You can explore other models available on the Ollama library at https://ollama.com/library. Consider models like phi3 or mistral for different capabilities.

4. Verify Ollama is ready: To confirm that Ollama is properly installed and the model is ready to use, run a quick test prompt:

   ollama run llama3 "Hello, Ollama! How are you today?"
   

   Ollama should respond with a greeting from the llama3 model. Press Ctrl+D to exit the ollama run session.

Your First AIPack Agent: Hello World!

Now that AIPack and Ollama are successfully set up, let’s create our very first AI agent. This agent will be a simple “Hello, World!” example, designed to demonstrate the basic structure of an AIPack agent and how to run it.

Step 1: Create Your Project Directory

First, create a new directory for your agent project and navigate into it using your terminal.

mkdir my_first_aipack_agent
cd my_first_aipack_agent

Step 2: Initialize an AIPack

AIPack provides an init command to quickly set up a new agent project with a basic .aip file template.

aipack init

You’ll be prompted for a few details:

• Agent Name: (e.g., hello-agent)
• Agent Description: (e.g., A simple agent to greet the world.)

After providing these details, you’ll see a new file named hello-agent.aip (or whatever name you chose) created in your current directory.

Step 3: Explore the .aip File

Open the newly created hello-agent.aip file in your favorite text editor (like VS Code). It will look something like this:

---
name: hello-agent
description: A simple agent to greet the world.
model: ollama/llama3 # Default model, change if needed
---

# Stage: main
This is the main stage of your agent.

You can write your prompt here.

Let’s break down what you’re seeing:

• Front Matter (--- blocks): This section contains essential metadata about your agent, formatted in YAML.

  • name: The unique identifier for your agent.
  • description: A brief explanation of what your agent does.
  • model: Crucially, this specifies which AI model AIPack should use. ollama/llama3 instructs AIPack to use the llama3 model from your locally running Ollama instance. If you pulled a different model, remember to update this line accordingly (e.g., ollama/mistral).

• # Stage: main: This defines the first (and currently only) stage of your agent’s workflow. In AIPack, stages are where you define specific tasks or prompts that will be sent to the AI model. The content following this heading is the actual prompt.

Step 4: Define a Simple Agent Stage

Let’s modify the hello-agent.aip file to make our agent provide a specific greeting.

1. Open hello-agent.aip in your text editor.

2. Replace the placeholder content under # Stage: main with a clear instruction for the AI:

   ---
   name: hello-agent
   description: A simple agent to greet the world.
   model: ollama/llama3 # Default model, change if needed
   ---
   
   # Stage: main
   Please say "Hello, AIPack user! Welcome to your first agent."
   

   Here, we’ve provided a direct instruction to the AI model. AIPack will take this markdown content and send it as a prompt to the llama3 model via Ollama. This demonstrates how easily you can instruct your agents.

Step 5: Run Your Agent!

Now for the exciting part: running your first AIPack agent!

1. Save the hello-agent.aip file.

2. Return to your terminal (ensuring you are still in the my_first_aipack_agent directory).

3. Execute the agent using the aipack run command, specifying your .aip file:

   aipack run hello-agent.aip
   

   AIPack will process your .aip file, connect to your local Ollama instance, send the prompt from the main stage, and then print the AI model’s response directly to your terminal.

   You should see output similar to this:

   [AIPack] Running agent 'hello-agent' from hello-agent.aip...
   
   Hello, AIPack user! Welcome to your first agent.
   

   (The exact phrasing from the LLM might vary slightly, but the core message will be present.)

   Congratulations! You’ve successfully built and run your first AI agent using AIPack. You’ve witnessed how AIPack acts as the bridge between your agent definition and the underlying AI model, making complex interactions straightforward.

Mini-Challenge: Personalize the Greeting

Let’s make our agent a little more interactive by allowing it to greet a specific name.

Challenge: Modify your hello-agent.aip file so that it greets a specific name provided by you when you run the agent.

Hint: AIPack agents can accept input parameters. You can access these parameters within your prompt using a special syntax. For example, if you pass --input name=Alice when running the agent, you can reference {{ .name }} in your prompt.

What to observe/learn: This challenge will teach you how to pass dynamic input to your AIPack agents, making them more versatile and responsive to user-provided data.

# Stage: main
Please say "Hello, {{ .name }}! Welcome to your first agent."

aipack run hello-agent.aip --input name=YourName

Common Pitfalls & Troubleshooting

Even with simple steps, you might encounter issues. Here are a few common problems and how to resolve them:

• aipack: command not found:
  • Problem: The AIPack CLI executable is not located in your system’s PATH.
  • Solution: Ensure pip’s installation directory for scripts is in your PATH. This is usually handled automatically by Python installers, but if you’re using a virtual environment, ensure it’s activated. Re-running pip install aipack might also help to reconfigure PATH entries.
• “Error connecting to Ollama…” or “Model ’llama3’ not found…”:
  • Problem: Ollama is either not running, or the specified AI model hasn’t been downloaded or is incorrectly referenced.
  • Solution:
    1. Verify Ollama is running: Make sure the Ollama application is active in the background (often a system tray icon or a running process).
    2. Download the model: Run ollama pull llama3 (or your chosen model, e.g., ollama pull mistral) in your terminal to download the model if you haven’t already.
    3. Check .aip file: Verify the model: line in your hello-agent.aip file exactly matches a model you’ve successfully pulled (e.g., ollama/llama3).
• Syntax Errors in .aip file:
  • Problem: Typos or incorrect markdown/YAML formatting within your .aip file. AIPack is particular about syntax.
  • Solution: Carefully review your hello-agent.aip file for any mistakes, especially in the front matter (the --- blocks) or stage headings. Ensure the model: line is correctly formatted and indented if necessary. Pay close attention to dashes, colons, and spacing in YAML.

Summary

In this introductory chapter, you’ve taken the crucial first steps into the world of AIPack, equipping yourself with foundational knowledge:

• Understood AIPack’s role as an open-source agentic runtime, providing the essential infrastructure for building, running, and sharing AI agents effectively.
• Learned about .aip files as the portable and self-contained package format for your AI agents, facilitating easy distribution and collaboration.
• Gained insight into multi-stage markdown agents, appreciating how they enable clear, human-readable definitions of structured agent workflows.
• Set up your complete development environment by installing the AIPack CLI and configuring Ollama as your local AI model provider.
• Built and successfully ran your first “Hello, World!” agent, demonstrating the basic agent definition and execution flow from concept to practical output.

You’re now equipped with the foundational knowledge to start experimenting with AIPack and building intelligent agents. In the next chapter, we’ll dive deeper into defining more complex multi-stage agents, exploring how they can perform sequential tasks and manage conversation flow, moving beyond single-shot interactions.

References

• AIPack GitHub Repository
• Ollama Official Website
• Ollama Model Library

This page is AI-assisted and reviewed. It references official documentation and recognized resources where relevant.