Build production-ready AI agents with markdown-defined workflows
Quick Start • Documentation • Examples • Features • Contributing
PISA (Prismer Intelligence Server Agents) is a next-generation AI agent framework built on top of the OpenAI Agent SDK. It enables developers to create sophisticated, production-ready AI agents using markdown-based configuration and modular architecture.
- 🎯 Markdown-First: Define agents, tools, and workflows entirely in markdown files
- 🔧 Modular Design: Compose agents from reusable modules (Planning, Execution, Observation, Reflection)
- 🛠️ Rich Tooling: Built-in support for Functions, MCP Servers, and Subagents
- 📊 Observable: Real-time execution tracking with beautiful CLI output powered by Rich
- 🔄 Event-Driven: Production-ready deployment with Temporal integration
- 🎨 Developer-Friendly: Intuitive CLI, comprehensive logging, and extensive documentation
- Context Engineering: 1st version 'Pyramid Context Engineering' solution
From PyPI (Recommended):
pip install pisa-pythonFrom Source:
# Clone the repository
git clone https://github.com/Prismer-AI/pisa.git
cd pisa
# Install dependencies (using uv for faster installation)
uv pip install -e .
# Or using pip
pip install -e .Create a .env file in the project root:
# OpenAI Configuration
OPENAI_API_KEY=your_api_key_here
OPENAI_BASE_URL=https://api.openai.com/v1
# Default Model
AGENT_DEFAULT_MODEL=gpt-4o-mini
# Optional: Temporal Configuration
TEMPORAL_ADDRESS=localhost:7233- Initialize a new agent project:
pisa init my-agent
cd my-agent- Define your agent in
.prismer/agent.md:
---
name: my-first-agent
version: 1.0.0
description: A simple agent that performs calculations
loop_type: plan_execute
capabilities:
- calculator
- text_to_table
planning:
max_iterations: 10
# ... more configuration
---
## Planning Instructions
You are a helpful mathematical assistant. Break down complex calculations into steps.
## Reflection Guidelines
After each calculation, verify the result makes sense.- Define capabilities in
.prismer/capability/function/:
from pisa.capability import capability
from agents.extensions.function_tool import function_tool
@capability(
name="calculator",
description="Perform basic mathematical operations",
capability_type="function",
tags=["math", "calculation"]
)
def calculator(operation: str, a: float, b: float) -> float:
"""
Perform a mathematical operation.
Args:
operation: The operation (add, subtract, multiply, divide)
a: First number
b: Second number
"""
ops = {
"add": lambda x, y: x + y,
"subtract": lambda x, y: x - y,
"multiply": lambda x, y: x * y,
"divide": lambda x, y: x / y
}
return ops[operation](a, b)- Run your agent:
# Validate configuration
pisa validate .prismer/agent.md
# List available capabilities
pisa list-capabilities
# Run the agent
pisa run .prismer/agent.md -i "Calculate 123 * 456 and show the result"Define your entire agent in a single markdown file:
---
name: data-processor
loop_type: plan_execute
capabilities:
- data_loader
- data_cleaner
- data_analyzer
---
## Planning Instructions
Break down data processing tasks into logical steps...
## Execution Guidelines
Ensure data quality at each step...Choose from battle-tested agent loop patterns:
- Plan-Execute: Plan first, then execute tasks sequentially
- ReAct (coming soon): Reason and Act in interleaved fashion
- Custom: Define your own loop template
- Functions: Simple Python functions with
@function_tooldecorator - MCP Servers: Connect to Model Context Protocol servers
- Subagents: Delegate to specialized sub-agents via handoff
# Function Tool
@capability(capability_type="function")
@function_tool
def my_function(param: str) -> str:
return f"Processed: {param}"
# Subagent
@capability(capability_type="agent")
def my_subagent() -> Agent:
return Agent(
name="specialist",
instructions="You are a specialist in..."
)Real-time execution visualization powered by Rich:
╭─────────────────────────────── 👤 User Query ────────────────────────────────╮
│ Calculate the matrix multiplication of [[1,2],[3,4]] × [[5,6],[7,8]] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────── 📋 Planning (Iteration 0) ──────────────────────────╮
│ Goal: Matrix multiplication and analysis │
│ Total Tasks: 3 │
╰──────────────────────────────────────────────────────────────────────────────╯
╭───────────────────────── 🔧 Execution (Iteration 1) ─────────────────────────╮
│ Task: task_01 │
│ Capability: matrix_multiply │
│ Status: ✅ │
│ Result: [[19, 22], [43, 50]] │
╰──────────────────────────────────────────────────────────────────────────────╯
- Structured Logging: Context-aware logs with
structlog - Execution Tracking: Monitor planning, execution, observation, and reflection phases
- Debug Mode: Deep inspection of LLM interactions and tool calls
- Metrics Collection: Performance tracking for production deployments
| Document | Description |
|---|---|
| README | This file - Quick start and overview |
| Contributing Guide | How to contribute to PISA |
| CHANGELOG | Version history and release notes |
| Example Agent | Full example with math & data processing |
| Agent Template | Agent definition reference |
| Capability README | Capability system documentation |
📖 Full documentation coming soon! We're working on comprehensive guides for:
- Quick Start Tutorial
- Architecture Deep Dive
- Capability Development Guide
- Loop Template Creation
- API Reference
A sophisticated agent that performs matrix operations, calculates softmax, and generates structured tables.
Location: example/agent_example/
Run the example:
cd example/agent_example
pisa run .prismer/agent.md -i "Calculate [[1,2],[3,4]] × [[5,6],[7,8]], compute softmax, and show results as a table"Features demonstrated:
- ✅ Matrix operations (Function capability)
- ✅ Softmax calculations (MCP capability)
- ✅ Text-to-table conversion (Subagent capability)
- ✅ Plan-Execute loop
- ✅ Context management and persistence
- ✅ Rich CLI output
Example capabilities:
matrix_operations- Matrix math (add, multiply, transpose, etc.)compute_softmax- Temperature-scaled softmaxsoftmax_with_attention- Attention weights calculationtext_to_table- Convert text to structured tables
We're working on additional examples:
- 🔜 Research Assistant - Web search and paper summarization
- 🔜 Code Review Agent - Automated code analysis and suggestions
- 🔜 Data Analysis Agent - CSV/JSON processing and visualization
- 🔜 Customer Support Bot - Multi-turn conversation with knowledge base
PISA follows a clean, modular architecture designed for both development and production deployment:
┌─────────────────────────────────────────────────┐
│ Agent Definition Layer │
│ (agent.md - Markdown Config) │
└─────────────────┬───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ Agent Loop Engine (Core) │
│ │
│ ┌───────────────────┐ ┌──────────────────┐ │
│ │ Loop Templates │ │ Capability System│ │
│ │ - Plan-Execute │ │ - Functions │ │
│ │ - ReAct (soon) │ │ - MCP Servers │ │
│ │ - Custom │ │ - Subagents │ │
│ └─────────┬─────────┘ └────────┬─────────┘ │
│ │ │ │
│ ┌─────────▼──────────────────────▼─────────┐ │
│ │ Core Modules │ │
│ │ - Planning - Observation │ │
│ │ - Execution - Reflection │ │
│ │ - Validation - Context Management │ │
│ └──────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ OpenAI Agent SDK Runtime │
│ (Messages, Tools, Handoffs, Streaming) │
└────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────┐
│ Temporal Cluster │
│ (Orchestration & Durability) │
└─────────────────┬───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ PISA Temporal Workflow │
│ │
│ ┌──────────────────────────────────────────┐ │
│ │ Workflow Orchestration Layer │ │
│ │ - State Management & Persistence │ │
│ │ - Checkpointing & Recovery │ │
│ │ - Human-in-the-Loop Support │ │
│ │ - Long-running Task Execution │ │
│ └─────────────────┬────────────────────────┘ │
│ │ │
│ ┌─────────────────▼────────────────────────┐ │
│ │ Temporal Activities │ │
│ │ - Agent Loop Execution │ │
│ │ - State Checkpoint Storage │ │
│ │ - User Notification │ │
│ │ - External API Calls │ │
│ └──────────────────────────────────────────┘ │
└─────────────────┬───────────────────────────────┘
│
┌─────────────────▼───────────────────────────────┐
│ Agent Loop Engine (Same as Dev) │
│ (Referenced from Development Mode above) │
└─────────────────────────────────────────────────┘
Agent Definition Layer
- Markdown-based configuration (
agent.md) - Declarative instructions and settings
- Version-controlled agent specifications
Agent Loop Engine
- Loop Templates: Reusable behavior patterns (Plan-Execute, ReAct, etc.)
- Core Modules: Planning, Execution, Observation, Reflection, Validation
- Capability System: Unified interface for Functions, MCP Servers, and Subagents
- Context Management: Pyramid Context Engineering with compression
OpenAI Agent SDK
- LLM interaction primitives
- Tool/function calling
- Agent handoffs
- Message streaming
Temporal Workflow Layer (Production Only)
- Durable execution with automatic state persistence
- Failure recovery and retry mechanisms
- Long-running task support (hours/days)
- Human-in-the-loop workflows
- Built on Temporal's OpenAI Agents integration
| Feature | Development Mode | Production Mode (Temporal) |
|---|---|---|
| Use Case | Local testing & iteration | Production deployment |
| Execution | Direct Python process | Temporal Workflow |
| State | In-memory | Durable (persisted) |
| Recovery | Manual restart | Automatic retry & resume |
| Monitoring | CLI logs | Temporal UI + metrics |
| Scalability | Single instance | Distributed workers |
| Cost | Free (local) | Infrastructure cost |
PISA uses a sophisticated state management system:
- LoopState: Centralized state for agent execution
- Context Compression: Pyramid Context Engineering to manage token limits
- Checkpointing: Periodic state snapshots for recovery
- State Serialization: JSON-based state persistence
- ✅ Core framework with Plan-Execute loop
- ✅ Function, MCP, and Subagent capabilities
- ✅ CLI tools and rich observability
- ✅ Markdown-based agent definition
- ✅ Context management with Pyramid Context Engineering
- 🚧 Temporal workflow integration (experimental)
- 🔲 Complete Temporal production deployment guide
- 🔲 Additional loop templates (ReAct, ReWOO)
- 🔲 Enhanced context compression with LOD (Level of Detail)
- 🔲 Multi-agent collaboration patterns
- 🔲 Streaming response support
- 🔲 Comprehensive test coverage (target: 80%+)
- 🔲 Production-grade Temporal workflow orchestration
- 🔲 High-performance server mode for concurrent agents
- 🔲 Agent marketplace and community templates
- 🔲 Auto-optimization with feedback loops
- 🔲 Multi-modal support (images, audio, video)
- 🔲 Advanced monitoring and observability
- 🔲 Enterprise features (RBAC, audit logs, etc.)
We welcome contributions! Please see our Contributing Guide for details.
# Clone and install in development mode
git clone https://github.com/Prismer-AI/pisa.git
cd pisa
uv pip install -e ".[dev]"
# Run tests
uv run pytest tests/ -v
# Run linter
uv run ruff check src/
# Format code (using ruff format)
uv run ruff format src/- 📝 Documentation improvements
- 🐛 Bug reports and fixes
- ✨ New capability implementations
- 🎨 Loop template designs
- 🌍 Internationalization
PISA is released under the MIT License.
PISA is built on the shoulders of giants:
- OpenAI Agent SDK - Core agent primitives and LLM interactions
- Temporal - Durable workflow orchestration for production deployments
- Temporal OpenAI Agents Integration - Production-ready agent workflow patterns
- Rich - Beautiful terminal output and progress tracking
- Python Ecosystem - The amazing tools and libraries that make this possible
- Issues: GitHub Issues
- Discussions: GitHub Discussions
- Email: support@prismer.ai
- Twitter: @PrismerAI
⭐ Star us on GitHub — it motivates us a lot!
Made with ❤️ by Prismer AI Lab