AgentCore.jl - Julia Implementation of Pi Agent Core

A Julia reimplementation of the @earendil-works/pi-agent-core package, providing a stateful agent framework for LLM interactions.

Overview

This package provides:

• Low-level agentLoop for stateful LLM interactions with tool execution
• High-level Agent struct with state management, event streaming, and queueing
• AgentHarness for session persistence, resource management, and extension hooks
• Built-in tools for file operations (read, write, edit) and bash execution
• Session management with JSONL-based storage, compaction, and branch navigation

Architecture

The Julia implementation follows the same layered architecture as the TypeScript version:

┌─────────────────────────────────────────────────────────────────────┐
│                            AgentHarness                              │
│              (Session persistence, resource management)              │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                              Agent                                 │
│              (State management, event streaming, queueing)           │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                          AgentLoop                                 │
│              (Low-level loop, tool execution)                        │
└─────────────────────────────────────────────────────────────────────┘
                              │
┌─────────────────────────────▼───────────────────────────────────────┐
│                            Session                                 │
│              (Conversation history, compaction, branching)           │
└─────────────────────────────────────────────────────────────────────┘

Installation

using Pkg
Pkg.add("AgentCore")

Quick Start

using AgentCore

# Create an agent with default configuration
agent = Agent()

# Subscribe to events
subscribe(agent) do event, signal
    if event isa MessageEndEvent
        println("Received message: $(event.message)")
    end
end

# Run a prompt
prompt(agent, "Hello, how are you?")

Core Concepts

Agent

The Agent struct provides a high-level interface for interacting with LLMs. It manages:

• Conversation state (messages, tools, system prompt)
• Event streaming and lifecycle management
• Steering and follow-up message queues
• Abort handling

AgentLoop

The agentLoop function implements the core agent loop that:

• Transforms AgentMessage[] to Message[] at the LLM call boundary
• Executes tool calls (parallel or sequential)
• Emits lifecycle events
• Handles steering and follow-up messages

AgentHarness

The AgentHarness provides:

• Session persistence with JSONL storage
• Resource management (skills, prompt templates)
• Extension hooks system
• Tool execution with context
• Branch navigation and compaction

Sessions

Sessions track conversation history using a tree-based structure:

• Branch-based history with compaction
• Tree navigation (moveTo, navigateTree)
• Message and metadata persistence

Built-in Tools

Bash Tool

Execute shell commands with output capture and truncation.

bash_tool = createBashTool()

Read Tool

Read files with support for text and images.

read_tool = createReadTool()

Write Tool

Write content to files with automatic directory creation.

write_tool = createWriteTool()

Edit Tool

Edit files using exact text replacement.

edit_tool = createEditTool()

Session Storage

AgentCore supports two session storage backends:

1. JsonlSessionStorage - File-based storage using JSONL format
2. InMemorySessionStorage - In-memory storage for testing

Compaction

The compaction system manages context window usage by:

• Summarizing old conversation history
• Retaining recent messages
• Supporting iterative updates to summaries

Event System

AgentCore uses a rich event system for monitoring and control:

• AgentStartEvent / AgentEndEvent - Agent lifecycle
• TurnStartEvent / TurnEndEvent - Conversation turns
• MessageStartEvent / MessageEndEvent - Message lifecycle
• ToolExecutionStartEvent / ToolExecutionEndEvent - Tool execution

Examples

See the examples/ directory for more detailed examples.

Differences from TypeScript

While maintaining API compatibility where possible, this Julia implementation:

• Uses Julia's type system for better compile-time guarantees
• Leverages Julia's multiple dispatch for extensibility
• Uses Julia's async primitives for concurrent operations
• Provides more idiomatic Julia error handling

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

License

MIT

Acknowledgments

This is a reimplementation of the Pi Agent Core package in Julia.