Token Bowl Deep Agent

A command-line interface for running deep agents powered by OpenRouter and LangChain's deepagents library, featuring 6 specialized fantasy football subagents and MCP server integration.

Project URL: https://deepagent.tokenbowl.ai

Overview

Deep agents are built on LangGraph and designed to handle complex, multi-step tasks with:

• Planning capabilities for task decomposition
• File system tools for context management
• Subagent support for delegating specialized work
• Long-term memory persistence across conversations

Fantasy Football Edition

The fantasy football agent comes with 6 specialized subagents that work together to help you win your league:

1. Roster Analyst - Identifies bye weeks and optimizes lineups
2. Injury Analyst - Monitors health status and practice reports
3. Player Market Analyst - Finds waiver wire opportunities
4. Trade Analyst - Identifies and structures trade opportunities
5. Communications Spokesperson - Crafts persuasive trade messages
6. Assistant GM - Reviews all subagent work for quality control

Plus MCP server integration with the Token Bowl fantasy football data server at https://tokenbowl-mcp.haihai.ai/sse.

Installation

From source (recommended for development)

# Clone the repository
git clone https://github.com/tokenbowl/deepagent.git
cd token-bowl-deep-agent

# Install in editable mode
pip install -e .

# Or install with development dependencies
pip install -e ".[dev]"

Using pip (when published)

pip install tokenbowl-deepagent

Configuration

Set your OpenRouter API key:

export OPENROUTER_API_KEY="your-openrouter-api-key-here"

Get your API key from OpenRouter.

Usage

Fantasy Football Agent (Recommended)

Run the fantasy football agent with 6 specialized subagents:

# General chat and advice
deep-agent chat "Review my roster for Week 10"

# Interactive fantasy assistant
deep-agent chat --interactive

# Set weekly lineup with detailed report
deep-agent lineup my-roster.md -w 10

General Purpose Agent

Run the agent with a single message:

deep-agent run "Help me understand deep agents"

Interactive Mode

Start an interactive conversation:

deep-agent run --interactive

Type your messages and the agent will respond. Type exit or quit to end the session.

Use a Different Model

Specify a different OpenRouter model:

deep-agent run -m openai/gpt-4-turbo "What is AI?"

List Available Models

See popular OpenRouter models:

deep-agent models

Using Prompt Files

Load system and user prompts from markdown files:

# Use a built-in system prompt
deep-agent run -s research "Tell me about quantum computing"

# Load user prompt from file
deep-agent run -p prompts/user/example-research.md

# Use both custom system and user prompts
deep-agent run -s coding -p prompts/user/example-coding.md

# Interactive mode with custom system prompt
deep-agent run --interactive -s research

List Available Prompts

See built-in prompts:

# List system prompts
deep-agent prompts

# List user prompts
deep-agent prompts --type user

CLI Commands

Main Fantasy Football Commands

deep-agent chat - General interrogation and advice

deep-agent chat "What's the best waiver wire strategy?"
deep-agent chat --interactive
deep-agent chat -w 10 "Who should I target in trades?"

deep-agent lineup - Set weekly lineup with detailed reporting

deep-agent lineup my-roster.md -w 10
deep-agent lineup -w 10 -l ESPN_123 -t 5 -o week10-report.md

Outputs comprehensive markdown report with:

• Model info and token usage
• All system prompts
• Lineup recommendations
• Token breakdowns

deep-agent eval - Retrospective analysis of historical decisions

deep-agent eval -l ESPN_123 -t 5           # Full season
deep-agent eval -l ESPN_123 -t 5 -s 1 -e 10  # Specific weeks

Compares actual lineups vs optimal lineups, shows points left on bench.

Other Commands

deep-agent run - General purpose agent

deep-agent run -s research "Research topic"

deep-agent models - List available models deep-agent prompts - List prompt templates deep-agent agents - Display info about all 6 subagents

See docs/CLI_COMMANDS.md for complete reference.

Project Structure

token-bowl-deep-agent/
├── src/
│   └── deep_agent/
│       ├── __init__.py      # Package initialization
│       ├── agent.py         # Agent creation and configuration
│       ├── cli.py           # Command-line interface
│       ├── prompts.py       # Prompt loading utilities
│       └── tools.py         # Custom tools for the agent
├── prompts/
│   ├── system/              # System prompt templates
│   │   ├── default.md       # Default system prompt
│   │   ├── research.md      # Research specialist
│   │   └── coding.md        # Coding specialist
│   ├── user/                # User prompt examples
│   │   ├── example-research.md
│   │   └── example-coding.md
│   └── README.md            # Prompts documentation
├── pyproject.toml           # Modern Python packaging config
├── setup.py                 # Backward compatibility
├── requirements.txt         # Dependencies
└── README.md               # This file

Development

Working with Prompts

Creating Custom System Prompts

Create a new markdown file in prompts/system/:

# My Custom Agent

You are a [description of role]...

## Your Capabilities
- List capabilities
- And responsibilities

## Guidelines
1. How to approach tasks
2. Communication style
3. Output format

Use it with:

deep-agent run -s prompts/system/my-custom.md "Your task"

Creating User Prompts

Create task-specific prompts in prompts/user/:

# Task Description

[Detailed description of what you want the agent to do]

## Requirements
- Requirement 1
- Requirement 2

## Expected Output
[What you expect as a result]

See prompts/README.md for detailed documentation on creating effective prompts.

Adding Custom Tools

Add new tools in src/deep_agent/tools.py:

from langchain_core.tools import tool

@tool
def my_custom_tool(input: str) -> str:
    """Tool description"""
    return "result"

Then import and add to the agent in src/deep_agent/agent.py:

from .tools import example_tool, my_custom_tool

tools = [example_tool, my_custom_tool]

Using Different Models

The agent supports any model available on OpenRouter. Popular models include:

• anthropic/claude-3.5-sonnet (default, recommended)
• anthropic/claude-3-opus
• openai/gpt-4-turbo
• openai/gpt-4o
• google/gemini-pro
• meta-llama/llama-3-70b-instruct
• mistralai/mixtral-8x7b-instruct

See all models at OpenRouter Models.

Programmatic Usage

You can also use the agent programmatically in your Python code:

from deep_agent import create_agent

# Create the agent
agent = create_agent(
    model_name="anthropic/claude-3.5-sonnet",
    api_key="your-api-key"
)

# Invoke the agent
result = agent.invoke({
    "messages": [{"role": "user", "content": "Your message here"}]
})

print(result)

Features

Core Features

• CLI Interface: Easy-to-use command-line tool
• Interactive Mode: Chat with the agent in real-time
• Model Selection: Choose from any OpenRouter model
• Prompt Templates: Load system and user prompts from markdown files
• Planning: Built-in task planning and decomposition
• File System: Read, write, and manage files for context
• Extensible: Add custom tools and prompts

Fantasy Football Features

• 6 Specialized Subagents: Roster, Injury, Market, Trade, Communications, Assistant GM
• MCP Integration: Token Bowl fantasy football data server
• Bye Week Management: Never start a player on bye
• Injury Monitoring: Track practice reports and health status
• Waiver Wire Analysis: Find valuable pickups before your league
• Trade Optimization: Identify and negotiate winning trades
• Quality Control: Assistant GM reviews all recommendations

Built-in Agent Personalities

• Default: General-purpose assistant
• Research: Expert researcher and report writer
• Coding: Software engineering specialist
• Fantasy Football GM: Complete fantasy team management

Requirements

• Python 3.9+
• OpenRouter API key

License

MIT

Documentation

• Fantasy Football Guide: docs/FANTASY_FOOTBALL.md
• MCP Integration: docs/MCP_INTEGRATION.md
• Project Summary: docs/PROJECT_SUMMARY.md
• Subagent Details: prompts/subagents/README.md
• Prompt System: prompts/README.md

Links

• Homepage: https://deepagent.tokenbowl.ai
• Repository: https://github.com/tokenbowl/deepagent
• Token Bowl MCP Server: https://tokenbowl-mcp.haihai.ai/sse
• OpenRouter: https://openrouter.ai
• DeepAgents Documentation: https://docs.langchain.com/oss/python/deepagents/overview

Support

For issues and questions, please open an issue on GitHub.

Quick Examples

Fantasy Football

# View available agents
deep-agent agents

# Weekly roster review
deep-agent chat "Check my lineup for bye weeks and injuries"

# Set lineup with detailed report
deep-agent lineup my-roster.md -w 10

# Waiver wire hunting
deep-agent chat "Find RB pickups for this week"

# Trade analysis
deep-agent chat "Find trades to upgrade my WR position"

# Evaluate historical decisions
deep-agent eval -l ESPN_123 -t 5

# Interactive assistant
deep-agent chat -i

General Purpose

# Research task
deep-agent run -s research "Research quantum computing applications"

# Coding task
deep-agent run -s coding -p my-coding-task.md

# Custom prompt
deep-agent run -s prompts/system/my-custom.md "Do something"

Contributing

We welcome contributions! Areas for improvement:

• Additional subagent specialists
• Fantasy platform API integrations
• Custom MCP servers
• Prompt template improvements
• Documentation enhancements

See docs/PROJECT_SUMMARY.md for development guide.