Troop

Build and manage AI agents from the CLI with PydanticAI and Model Context Protocol.

Introduction

Troop is a modern LLM agent framework built on top of PydanticAI and the Model Context Protocol (MCP). It enables users to easily create, customize, manage, and interact with AI agents through a simple yet powerful CLI.

troop researcher -p "Any music events in Paris tonight?"

Researcher: There are multiple music events in Pari...

Think of troop as a generalized version of Claude Code, that allows you to build and use all kinds of useful agents based on any LLM you like.

In troop, an AI agent consists of 3 parts:

1. Model: Choose any LLM from any supported provider as the backbone of your agent.
2. Tools: Every tool in troop is provided through an MCP server. Mix and match as many as you like, remote or locally.
3. Instructions: Tie everything together and let the agent know how to act and which tools to use in what situation.

Agent = Model + Tools + Instructions

Features

• Async-First Architecture: Built with asyncio for efficient concurrent operations
• PydanticAI: As the core engine to manage requests and responses with different providers
• MCP: As a single interface for tool usage
• Modern CLI Experience: Beautiful terminal interface using Typer and Rich
• REPL: Nicely formatted display of Human, Agent, and Tool messages
• Agent Registry: Add and manage agents to your needs

Installation

We recommend using uv to install troop:

uv tool install troop

Or with pip:

pip install troop

Quick Start

Let's build and run our first custom agent.

1. Add a Provider

troop provider add
# Enter provider name/ID: openai
# Enter API key: sk-abcd...

This adds OpenAI as a model provider making all their models available in troop. We support all PydanticAI providers.

2. Add an MCP Server

troop mcp add
# Enter name: web-tools
# Enter command: uvx mcp-web-tools
# Enter env var: BRAVE_SEARCH_API_KEY=abc...

This adds a predefined MCP server called mcp-web-tools with its search and fetch tools using uv, and accesses it directly from PyPI.

3. Create an Agent

troop agent add
# Enter name: researcher
# Enter model: openai:gpt-4o
# Enter MCP servers: web-tools
# Enter instructions: You're a helpful researcher agent with access to the web...

This defines the actual agent with the model, tools and instructions.

4. Use Your Agent

troop researcher

> What's the first headline on the Guardian?

> "Climate Summit Reaches Historic Agreement on Emissions"

This launches the interactive REPL for the researcher agent we just created.

Commands Overview

Agent Invocation

# Interactive chat mode (default)
troop researcher

# Single prompt mode
troop researcher -p "What's the weather in Paris?"

# Override model
troop researcher -m openai:gpt-4o-mini

Provider Management

# List providers
troop provider list

# Add provider
troop provider add openai --api-key sk-abc123...

# Remove provider
troop provider remove openai

MCP Server Management

# List servers
troop mcp list

# Add server
troop mcp add

# Remove server
troop mcp remove web-tools

Agent Management

# List agents
troop agent list

# Add agent
troop agent add

# Remove agent
troop agent remove researcher

# Set default agent
troop agent set researcher

Model Management

# Set default model
troop model set openai:gpt-4o

Configuration

Troop stores a global config YAML file in the user directory:

• macOS: ~/.troop/config.yaml
• Linux: ~/.config/troop/config.yaml
• Windows: %APPDATA%/troop/config.yaml

Example configuration:

providers:
  openai: sk-proj-vBAU...
  anthropic: sk-ant-api...
servers:
  web_tools:
    command:
    - uvx
    - mcp-web-tools
    env:
      BRAVE_SEARCH_API_KEY: BSA-abc123...
agents:
  researcher:
    model: openai:gpt-4o
    instructions: You're a helpful researcher with access to web tools...
    servers:
    - web_tools
defaults:
  model: openai:gpt-4o
  agent: researcher

REPL Experience

Troop provides a rich interactive experience in the terminal, with clear formatting for different message types:

┌─ User ────────────────────────────────────────────────────────────────┐
│ What is the Model Context Protocol?                                   │
└───────────────────────────────────────────────────────────────────────┘

┌─ Tool Call: web_tools-search_web ─────────────────────────────────────┐
│ {                                                                     │
│   "query": "Model Context Protocol",                                  │
│ }                                                                     │
└───────────────────────────────────────────────────────────────────────┘

┌─ Researcher ──────────────────────────────────────────────────────────┐
│ The Model Context Protocol (MCP) is an open standard created by       │
│ Anthropic that enables secure, two-way connections between AI systems │
│ and external data sources or tools.                                   │
└───────────────────────────────────────────────────────────────────────┘

Best Practices

System Instructions vs. Tool Descriptions

When defining agents and their tools, consider:

• Tool Description: Explain what the tool does, what it returns and HOW it needs to be used on a technical level. There shouldn't be any mentions of other tools or servers.
• System Instructions: Explain WHEN and in what situation a tool should be used or favored over another. Focus on the overall process the agent will go through.

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• GitHub Repository
• Issue Tracker
• PydanticAI Documentation
• Model Context Protocol