v0.4.0: Hooks, Compaction, Context Tools, Benchmarks

What's New

Deterministic Loop Hooks

• BaseStartHook / BaseEndHook for injecting instructions before the first LLM call and resuming the loop when the agent would stop
• PlanningHook (forces task planning) and CompletionCheckHook (verifies todo completion before allowing stop)
• Composable TerminationCondition with | / & operators

Context Compaction Strategies

• CompactionStrategy protocol called before each LLM call
• HeadTailCompaction preserves system prompt + recent work while dropping middle messages, respecting atomic groups (tool calls + results stay together)
• SlidingWindowCompaction keeps system message + most recent messages
• NoCompaction baseline for benchmarking
• Token counting via tiktoken with character-estimation fallback

Context Engineering Tools

• TaskTool for spawning sub-agents in isolated contexts
• TodoWriteTool / TodoReadTool / TodoListSessionsTool for file-backed task tracking
• SkillsTool for progressive disclosure via SKILL.md files
• MultiEditTool for atomic multi-file edits
• Factory function create_context_engineering_tools()

Benchmark CLI

• picoagents benchmark list|run|results CLI commands
• Built-in datasets (coding_v1, repo_analysis_v1)
• AgentConfig for declarative agent configuration comparison
• BenchmarkRunner, BenchmarkMiddleware, and analysis formatters

Other

• Instruction presets: get_instructions() for loading reusable system prompt templates
• Built-in skills: Code-review skill with SKILL.md frontmatter format
• From-scratch examples: Four progressive files building a minimal agent from zero

Install

pip install picoagents==0.4.0

v0.3.2 - Fix AgentResponse print output

What's Changed

Fixed

• Fixed AgentResponse.__str__() to display full conversation content instead of only metadata. Previously, printing a response would only show usage statistics; now it shows all messages followed by usage stats.

Changed

• Improved user experience when printing agent responses - users can now simply print(response) to see the complete conversation history.

Installation

pip install -U picoagents

Full Changelog: v0.3.1...v0.3.2

v0.3.1

PicoAgents v0.3.1

Added

• Anthropic Claude model client with full API support
• GitHub Models integration example
• Agent-as-tool result strategies for flexible output handling
• Context engineering examples

Changed

• Updated model client tests for better coverage and reliability
• Improved workflow integration tests with proper Pydantic model handling
• Enhanced WebUI workflow view components

Fixed

• Fixed Anthropic model name in tests (claude-3-5-haiku-20241022)
• Fixed CancellationToken import path in workflow tests
• Fixed workflow step progress events test with correct function signatures
• Updated OpenAI test to use gpt-4.1-mini model

Installation

pip install picoagents==0.3.1

# With Anthropic support:
pip install picoagents[anthropic]==0.3.1

# With all features:
pip install picoagents[all]==0.3.1

Full Changelog: v0.3.0...v0.3.1

Release v0.2.3

Release v0.2.3 - Observability, Checkpointing, and Tool Approval

This release adds significant new capabilities for production-ready agent systems including observability, state persistence, and human-in-the-loop workflows.

✨ New Features

OpenTelemetry Integration

• Automatic instrumentation following OpenTelemetry Gen-AI semantic conventions
• Trace and metrics export for agent executions, tool calls, and LLM interactions
• Enable with PICOAGENTS_ENABLE_OTEL=true environment variable
• Includes docker-compose setup for Jaeger backend

Workflow Checkpointing

• Save and restore workflow execution state
• File-based and in-memory storage backends
• Automatic workflow structure validation for checkpoint compatibility
• Resume interrupted workflows from any checkpoint

Tool Approval System

• Human-in-the-loop workflows with @tool decorator
• ApprovalMode support: always_require or never_require
• Enhanced middleware with approval flow hooks
• Web UI integration with tool approval banners

Enhanced Features

• Context management improvements with agent-specific contexts
• Memory tools for persistent agent memory across sessions
• Poethepoet task automation (poe test, poe check, etc.)
• Improved Web UI with example tasks display and debug panel

📚 Examples

New example directories with complete working code:

• examples/memory/ - Memory management patterns
• examples/otel/ - OpenTelemetry instrumentation
• examples/tools/ - Tool approval workflows
• examples/workflows/ - Checkpoint and resume workflows

🔧 Changes

• Enhanced middleware system with better error handling and event emission
• Reorganized test structure (workflow tests moved to tests/workflow/)
• Updated Web UI with latest React components
• Improved debug panel with detailed execution traces

🗑️ Removals

• Deprecated planning tools module (functionality moved to core tools)
• Old workflow test files from src/picoagents/workflow/tests/

📦 Installation

pip install picoagents==0.2.3

# With all features
pip install "picoagents[all]==0.2.3"

# With specific features
pip install "picoagents[otel]==0.2.3"  # OpenTelemetry support

See CHANGELOG.md for complete details.