---
id: fhaviary
version: "0.35.0"
license: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record)
license_treatment: permissive
maintenance: active
---

# fhaviary — Gymnasium framework for training language model agents on constructive tasks

License: permissive · Maintenance: active · Downloads: 106.0K/mo

## What it is and what it does

This package provides a gymnasium-style framework for building custom reinforcement learning environments where language model agents solve tasks by making tool calls and exchanging messages. It defines core abstractions—Environment, Message, Tool, and ToolRequestMessage—that handle agent-environment communication following OpenAI's message standard. The library ships with pre-built environments for math, general knowledge, biological sequences, scientific literature, and protein stability tasks, plus a Jupyter notebook environment.

The core workflow involves subclassing Environment to define custom tasks, implementing reset() to initialize state and tools, and step() to execute agent actions and return observations and rewards. Communication flows through a message formalism where agents emit ToolRequestMessage objects containing tool calls, and the environment responds with ToolResponseMessage objects or general observations. The framework is designed to integrate with a sister library for defining agents as Language Decision Processes, though it remains task-agnostic and works with any agent implementation.

Use it for:

- Train language agents on math reasoning tasks by defining environments with calculator tools and evaluating agent trajectories
- Build custom multi-step reasoning environments where agents call domain-specific tools to solve problems
- Evaluate language model performance on knowledge retrieval by wrapping datasets as environments with tool-based interaction
- Research agent behavior on scientific tasks like protein stability prediction or sequence analysis
- Run Jupyter notebooks as interactive environments where agents execute code and observe outputs

## Worth the install?

AI-flagged interpretation of the facts above — verify before relying.

A gymnasium framework for defining custom reinforcement learning environments where language model agents interact via tool calls and messages to solve structured tasks.

Yes, if you are building or evaluating language agent systems on structured tasks. The framework is actively maintained, has no known vulnerabilities, uses permissive licensing, and provides a clean abstraction for agent-environment interaction. Best suited for researchers and developers working with language model agents; less relevant if you only need a standard RL gym or don't plan to define custom environments.

## Install

pip install fhaviary
uv add fhaviary
poetry add fhaviary

## Installing fhaviary

Before you install: Low install friction with a pure-Python wheel distribution. Actively maintained with recent commits. Supports Python 3.11 through 3.14 with 5 runtime dependencies including httpx and pydantic.

License in practice: Apache License 2.0 is permissive and allows commercial use, modification, and distribution with minimal restrictions. You must include a copy of the license and note any changes to the source.

Quickstart:

pip install fhaviary

from aviary.core import Environment, Message, ToolRequestMessage, Tool

class CounterEnv(Environment):
    async def reset(self):
        self.state = {"count": 0}
        self.tools = [Tool.from_function(self.increment)]
        return [Message(content="Start counting")], self.tools
    
    async def step(self, action: ToolRequestMessage):
        obs = await self.exec_tool_calls(action)
        return obs, 0, False, False
    
    def increment(self):
        self.state["count"] += 1
        return f"count={self.state['count']}"

Requires Python 3.11 or later. A custom agent implementation or integration with an external agent library is needed to run agents on the environment; this package defines the environment interface only.

Verify before relying:

- Whether pre-built environments (GSM8K, HotPotQA, LabBench, LFRQA, Notebook) are included in base install or require optional extras
- Whether the sister library LDP is required to use Aviary or optional for advanced workflows
- Performance characteristics and scalability limits for agent training at scale

## Package facts

- License: Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for… (full text in the JSON record) (permissive)
- Python support: supports_current
- Install friction: low
- Maintenance: active
- Downloads: 106.0K/month (top 15,000 on PyPI)
- Known vulnerabilities: none known

## Tags

language agent RL environments, gymnasium for LLM agents, agent training framework, language model task environments, tool-based agent evaluation, agent-training, rl-environments, llm-evaluation

[View on SkillFed](https://skillfed.io/packages/fhaviary) · [View on PyPI](https://pypi.org/project/fhaviary/)