180 lines
6.2 KiB
Markdown
180 lines
6.2 KiB
Markdown
# 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
|
|
|
|
```julia
|
|
using Pkg
|
|
Pkg.add("AgentCore")
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```julia
|
|
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.
|
|
|
|
```julia
|
|
bash_tool = createBashTool()
|
|
```
|
|
|
|
### Read Tool
|
|
|
|
Read files with support for text and images.
|
|
|
|
```julia
|
|
read_tool = createReadTool()
|
|
```
|
|
|
|
### Write Tool
|
|
|
|
Write content to files with automatic directory creation.
|
|
|
|
```julia
|
|
write_tool = createWriteTool()
|
|
```
|
|
|
|
### Edit Tool
|
|
|
|
Edit files using exact text replacement.
|
|
|
|
```julia
|
|
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](https://github.com/earendil-works/pi/packages/agent) package in Julia.
|