gentleman

Gentleman is a declarative multi-agent AI framework. Agents are declared in configuration files, not code. Put one directory per agent under agents/, and a single process serves them all over three protocols:

• AG-UI — for humans, from a chat UI.

• A2A — for other agents, local or remote.

• MCP — for MCP clients, as tools.

Using tools from MCP servers and delegating to other agents both take nothing but configuration. No glue code.

agents/
  concierge/
    agent.yaml
    mcp_config.json
  writer/
    agent.yaml

Requirements

• Python 3.14+

Related MCP server: Hive

Quick start

Scaffold a project with uv and run it:

uvx --from gentleman-agents gentleman init my-gentleman
cd my-gentleman
uv sync
# edit agents/example/agent.yaml
uv run gentleman dev

gentleman dev serves the agents at http://127.0.0.1:8000. The interfaces are available at:

AG-UI : http://localhost:8000/agui
A2A   : http://localhost:8000/a2a
MCP   : http://localhost:8000/mcp

The example agent uses the built-in gentleman:echo model, so it runs without any credentials. To use a model provider, copy .env.sample to .env, set its API key, and run uv run --env-file .env gentleman dev.

gentleman init scaffolds a project into the given directory, creating it if it does not exist. Without an argument, it scaffolds into the current directory.

The package is published as gentleman-agents, while the command is gentleman. The --from flag is therefore required with uvx.

Install

As a command-line tool:

uv tool install gentleman-agents
gentleman --help

As a project dependency:

uv add gentleman-agents

With pip:

pip install gentleman-agents

Model providers

Model providers are extras. Install the ones you use:

uv add "gentleman-agents[openai]"

providers installs all five. The built-in gentleman:echo model needs none. Projects from gentleman init start with openai.

Other providers supported by Pydantic AI can be added directly:

uv add "pydantic-ai-slim[groq]"

Interactive chat

gentleman chat is a small client for trying out your agents from a terminal. It is meant for development and testing, not as a chat interface for users.

The gentleman chat subcommand needs the chat extra:

uv tool install "gentleman-agents[chat]"
gentleman chat

Or run it directly:

uvx --from "gentleman-agents[chat]" gentleman chat

To add it to a project instead:

uv add "gentleman-agents[chat]"

Extras can be combined, e.g. gentleman-agents[chat,openai].

Docker

Images are published to the GitHub Container Registry for linux/amd64 and linux/arm64, with all five model providers:

docker pull ghcr.io/madebyman/gentleman:edge

edge tracks the latest build from main. See the packages page for available tags.

Helm

The Helm chart deploys gentleman on Kubernetes. Agents are declared as YAML in the chart values and mounted into the pod, one directory per agent.

helm install gentleman oci://ghcr.io/madebyman/charts/gentleman
kubectl port-forward svc/gentleman 8000:80

The interfaces are then available at the same URLs as in Quick start.

With no values, the chart ships an example agent using gentleman:echo, so it runs without any credentials. For agents, secrets and ingress, see the chart on Artifact Hub.

Status

Alpha. The API and the configuration format may change without notice.

License

MIT