Pocket-Agent

A lightweight, extensible framework for building LLM agents with Model Context Protocol (MCP) support

Table of Contents

• Why Pocket Agent?
• Design Principles
• Cookbook
• Installation
• Quick Start
• Documentation

Why Pocket Agent?

Most agent frameworks are severely over-bloated. The reason for this is that they are trying to support too many things at once and make every possible agent implementation "simple". In the end, you might find yourself using 5-10% of the framework's code for your use case, meaning 90-95% is noise when you encounter a bug. This makes adding features and debugging unnecessarily complex.

Pocket Agent takes the opposite approach by implementing the basic functionalities of an Agent as an abstraction one layer above the MCP Client with useful features to provide first-class support for customization. This makes Pocket Agent extremely lightweight. In fact, so lightweight that the entire core framework and documentation can easily fit into most LLM context windows (see the built-in utility for this here). The minimal nature also means that you will use 90-95% of the framework's code for every agent you create.

Despite the minimal code, Pocket Agent is extremely powerful, even out-of-the-box with no custom extensions. By default, Pocket Agent enables users to:

• Use any remote or local MCP server(s) to integrate any amount of custom tools
• Run a typical agent loop (generate message, execute tool calls, handle tool results until the LLM does not call any tools)
• Allow tools to be run in parallel, minimizing execution bottlenecks
• Build multi-agent systems using built-in features to facilitate interaction
• View agents' behavior in a minimal built-in CLI frontend
• Use any local or remote LLM and enforce tpm/rpm limits for parallel LLM generations (Thanks to LiteLLM)

Design Principles

🚀 Lightweight & Simple

• Clean abstractions that separate agent logic from MCP client details
• Core functionality is only 2 files
• Only implements the core, non-case-specific features of an LLM agent

💡 Extensible

• Easily integrate a custom frontend using the built-in event system
• Easily implement fully custom agent behaviors
• Easily develop multi-agent systems

Installation

Install with uv (Recommended):

uv add pocket-agent

Install with pip:

pip install pocket-agent

Quick Start (For LLMs)

LLMs are excellent at building with Pocket Agent. Mostly, because the entirety of the core framework is minimal enough to easily fit into most LLM context windows.

Pocket Agent provides a simple command-line utility for this exact use case: pocket-dump

📄 Using pocket-dump

After installation, use pocket-dump to generate complete documentation with source code:

# Generate complete documentation + source code as pocket-agent-source.md
pocket-dump

# Custom filename
pocket-dump my-pocket-agent-reference.md

# Only include documentation
pocket-dump --docs-only

# Only include source code  
pocket-dump --source-only

The generated file contains everything an LLM needs to understand and build with Pocket Agent - no need to piece together multiple documentation sources or guess at implementation details.

Quick Start (For Humans)

You can use PocketAgent out of the box in 3 steps:

1. Configure the agent:

   from pocket_agent import AgentConfig
   
   # Configure and run
   config = AgentConfig(
       llm_model="gpt-4",
       system_prompt="You are a helpful assistant."
   )
   

2. Define the mcp servers the agent can access:

   servers = {
       "mcpServers": {
           "weather_tools": {
               "transport": "stdio",
               "command": "python",
               "args": ["server.py"],
               "cwd": "path/to/server.py"
           }
       }
   }
   

3. Initialize and run the agent:

   import asyncio
   from pocket_agent import PocketAgent
   
   agent = PocketAgent(agent_config=config, mcp_config=servers)
   
   agent_final_answer = await agent.run("What's the weather fo London?")
   

In the above example, the run method will add the input as a user message, and then run in a loop generating new messages and running any tools called by the configured LLM until the configured LLM generates a response which does not have any tool calls. All of the messages to and from the agent are neatly formatted in the console by default.

Pocket Agents are meant to be extended far beyond this behavior. Refer to the sections below for implementation examples and full documentation

🧑‍🍳 Cookbook

Find example implementations of Pocket Agents and their extensions in the Cookbook

📖 Documentation

For comprehensive documentation on all features and advanced usage, see the documentation folder:

• Getting Started - Detailed quick start guide and examples
• Core Concepts - PocketAgent base class, step method, message management
• Hooks and Events - Customizing agent behavior and frontend integration
• Multi-Model Support - Working with different LLM providers
• PocketAgentClient - MCP client wrapper and advanced features
• Multi-Agent Systems - Building complex agent architectures
• Agent-as-a-Server - Using agents as MCP servers
• Testing - Test suite and coverage

Feature Roadmap

Core Features

Modality support