agent-workshop 0.1.1

Framework for building automation-focused AI agents with observability

agent-workshop

Cost-effective framework for building automation-focused AI agents with full observability.

📦 Install as a Package: Users should install agent-workshop via PyPI (uv add agent-workshop or pip install agent-workshop), not clone this repository. This repo is for framework development only. See Quick Start for the correct workflow.

Features

🚀 Dual-Provider Architecture

• Development: Claude Agent SDK ($20/month flat rate)
• Production: Anthropic API (pay-per-token)
• Automatic switching based on environment

📊 Full Observability

• Langfuse integration out of the box
• Automatic tracing of all LLM calls
• Cost tracking and token estimation
• Performance metrics

🕸️ LangGraph Support

• Multi-step agent workflows
• State management
• Conditional routing
• Iterative refinement

⚡ Fast Setup with UV

• Modern dependency management
• 10-100x faster than pip/poetry
• Reproducible environments

Quick Start

Important: Users should install agent-workshop as a package, not clone this repository. This repo is for framework development only.

Installation

# Create your project
mkdir my-research-agents
cd my-research-agents

# Initialize with UV
uv init

# Install agent-workshop from PyPI
uv add agent-workshop

# Or with pip
pip install agent-workshop

Simple Agent (80% use case)

from agent_workshop import Agent, Config

class DeliverableValidator(Agent):
    async def run(self, content: str) -> dict:
        messages = [{
            "role": "user",
            "content": f"Validate this deliverable:\n\n{content}"
        }]
        result = await self.complete(messages)
        return {"validation": result}

# Usage
config = Config()  # Auto-detects dev/prod environment
validator = DeliverableValidator(config)
result = await validator.run(report_content)

LangGraph Workflow (15% use case)

from agent_workshop.workflows import LangGraphAgent
from langgraph.graph import StateGraph, END

class ValidationPipeline(LangGraphAgent):
    def build_graph(self):
        workflow = StateGraph(dict)

        workflow.add_node("scan", self.quick_scan)
        workflow.add_node("verify", self.verify)

        workflow.add_edge("scan", "verify")
        workflow.add_edge("verify", END)
        workflow.set_entry_point("scan")

        return workflow.compile()

    async def quick_scan(self, state):
        result = await self.provider.complete([{
            "role": "user",
            "content": f"Quick scan: {state['content']}"
        }])
        return {"scan_result": result, **state}

    async def verify(self, state):
        result = await self.provider.complete([{
            "role": "user",
            "content": f"Verify: {state['scan_result']}"
        }])
        return {"final_result": result}

# Usage (still single invocation!)
pipeline = ValidationPipeline(Config())
result = await pipeline.run({"content": report})

Configuration

Environment Setup

In your project directory, create .env.development or .env.production:

# .env.development
AGENT_WORKSHOP_ENV=development

# Claude Agent SDK (development)
CLAUDE_SDK_ENABLED=true
CLAUDE_MODEL=sonnet  # opus, sonnet, haiku

# Anthropic API (production - optional in dev)
ANTHROPIC_API_KEY=your_api_key_here
ANTHROPIC_MODEL=claude-sonnet-4-20250514

# Langfuse Observability (optional but recommended)
LANGFUSE_ENABLED=true
LANGFUSE_PUBLIC_KEY=your_public_key
LANGFUSE_SECRET_KEY=your_secret_key
LANGFUSE_HOST=https://cloud.langfuse.com

For a complete example, see the .env.example in the repository.

Provider Switching

The framework automatically switches providers based on environment:

• Development (AGENT_WORKSHOP_ENV=development): Uses Claude Agent SDK
• Production (AGENT_WORKSHOP_ENV=production): Uses Anthropic API

Troubleshooting

Langfuse Authentication Warnings

Problem: You see warnings like "Langfuse client initialized without public_key"

Solution: This is usually caused by missing environment variables. The framework now automatically loads .env files before initializing Langfuse, but you need to ensure:

1. Create the correct .env file:

   # For development
   cp .env.example .env.development
   
   # Edit and add your Langfuse credentials
   LANGFUSE_PUBLIC_KEY=pk-lf-...
   LANGFUSE_SECRET_KEY=sk-lf-...
   

2. Set the environment:

   export AGENT_WORKSHOP_ENV=development
   

3. Test your Langfuse connection:

   from agent_workshop.utils import test_langfuse_connection
   
   if test_langfuse_connection():
       print("✓ Langfuse configured correctly")
   else:
       print("✗ Check your credentials")
   

If you don't want to use Langfuse:

# In your .env file
LANGFUSE_ENABLED=false

Environment Variables Not Loading

Problem: Environment variables from .env files aren't being picked up

Cause: The .env file needs to match your environment:

• AGENT_WORKSHOP_ENV=development → looks for .env.development
• AGENT_WORKSHOP_ENV=production → looks for .env.production
• Default → looks for .env

Solution:

# Option 1: Use environment-specific files (recommended)
export AGENT_WORKSHOP_ENV=development
# Then create .env.development

# Option 2: Use generic .env file
# Just create .env (no export needed)

Provider Configuration Errors

Problem: "No valid provider configuration found"

Solution: Ensure you have credentials for at least one provider:

For Development:

CLAUDE_SDK_ENABLED=true
CLAUDE_MODEL=sonnet

For Production:

ANTHROPIC_API_KEY=your_key_here
ANTHROPIC_MODEL=claude-sonnet-4-20250514

Import Errors

Problem: ModuleNotFoundError: No module named 'agent_workshop'

Solution: Install the package (not clone the repo):

# Correct way (users)
uv add agent-workshop

# Or with pip
pip install agent-workshop

# Incorrect way
git clone https://github.com/trentleslie/agent-workshop.git  # ❌ Only for contributors

Claude Agent SDK Issues

Problem: "claude-agent-sdk is not installed"

Solution: Install with the optional extra:

uv add 'agent-workshop[claude-agent]'

# Or with pip
pip install 'agent-workshop[claude-agent]'

Getting Help

If you encounter other issues:

1. Check the examples in the repository
2. Review the documentation
3. Open an issue with:
   • Your Python version (python --version)
   • Your environment configuration (.env file, with credentials redacted)
   • Full error message and traceback

Design Philosophy

Single-Message Pattern

agent-workshop focuses on single-message automation (input → output), NOT streaming conversations.

Perfect for:

• ✅ Automated validations
• ✅ Batch processing
• ✅ Scheduled jobs
• ✅ CI/CD pipelines

Not designed for:

• ❌ ChatGPT-like interfaces
• ❌ Streaming conversations
• ❌ Real-time chat

Simple Agent vs LangGraph

Use Case	Recommended Approach
Single validation check	Simple Agent
Multi-step validation pipeline	LangGraph
Batch processing	Simple Agent
Iterative refinement	LangGraph
One-shot classification	Simple Agent
Multi-agent collaboration	LangGraph

Example Usage

Complete User Workflow

# 1. Create your project
mkdir my-research-agents
cd my-research-agents

# 2. Initialize and install
uv init
uv add agent-workshop

# 3. Create .env.development file with your keys

# 4. Create your first agent
cat > agents/validator.py << 'EOF'
from agent_workshop import Agent, Config

class DeliverableValidator(Agent):
    async def run(self, content: str) -> dict:
        messages = [{
            "role": "user",
            "content": f"Validate this deliverable:\n\n{content}"
        }]
        result = await self.complete(messages)
        return {"validation": result}
EOF

# 5. Run your agent
python -c "
import asyncio
from agents.validator import DeliverableValidator
from agent_workshop import Config

async def main():
    validator = DeliverableValidator(Config())
    result = await validator.run('Sample deliverable content')
    print(result)

asyncio.run(main())
"

Reference Examples

For complete examples, see the repository:

• Simple Validator - Single-message pattern, batch processing, cost tracking
• LangGraph Pipeline - Multi-step workflow, state management, conditional routing

Note: These examples are for reference only. Build your agents in your own project, not by cloning the framework repository.

Building Your Own Agents

Users: You build agents in your own project by installing agent-workshop as a dependency. See the Complete User Workflow above.

Your project structure should look like:

my-research-agents/              # Your project
├── pyproject.toml               # dependencies = ["agent-workshop"]
├── .env.development
├── .env.production
├── agents/
│   ├── __init__.py
│   ├── deliverable_validator.py
│   └── analysis_checker.py
└── main.py

For detailed guidance, see the Building Agents Guide.

Contributing to the Framework

This section is for contributors who want to improve the agent-workshop framework itself.

Development Setup

# Clone the framework repository (contributors only)
git clone https://github.com/trentleslie/agent-workshop.git
cd agent-workshop

# Install with dev dependencies
uv sync --all-extras

# Run tests
uv run pytest

# Format code
uv run ruff format

# Type check
uv run mypy src/

Cost Comparison

Environment	Provider	Cost Model	Best For
Development	Claude Agent SDK	$20/month flat	Unlimited experimentation
Production	Anthropic API	$3/1M input tokens $15/1M output tokens	Production workloads

Example: 1,000 validations/day with ~500 tokens each

• Development: $20/month (unlimited)
• Production: ~$30-50/month (depending on response length)

Architecture

User's Project (your own repo)
├── pyproject.toml
│   └── dependencies: ["agent-workshop"]  ← Install as package
├── agents/
│   ├── deliverable_validator.py
│   └── analysis_checker.py
└── .env.development

        ↓ imports from

agent-workshop Package (from PyPI)
├── Agent (simple agents)
├── LangGraphAgent (workflows)
├── Providers (Claude SDK, Anthropic API)
└── Langfuse Integration

        ↓ traces to

Langfuse Dashboard
├── Traces
├── Metrics
├── Costs
└── Performance

Key Point: Users install agent-workshop via uv add agent-workshop or pip install agent-workshop, they do NOT clone the repository.

Documentation

Full documentation available in the repository:

• Quickstart Guide
• Building Agents
• LangGraph Workflows
• Langfuse Observability
• User Project Setup

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

To contribute to the framework itself, see the Contributing to the Framework section above.

License

MIT License - see LICENSE for details.

Acknowledgments

Built with:

• Claude - LLM provider
• Langfuse - Observability platform
• LangGraph - Agent workflows
• UV - Fast Python packaging