Aviary Agent Gym

Aviary — Language-Agent Gymnasium for Scientific Tasks

Aviary is a gym (in the OpenAI-Gym sense) for LLM agents. It defines five drop-in scientific environments and a clean Python API for adding your own. Pair it with the sister library LDP to actually run / train agents against the environments.

Reference: arXiv:2412.21154 ("Aviary: Training Language Agents on Challenging Scientific Tasks").

Built-in environments

Install

pip install fhaviary                                       # core only
pip install 'fhaviary[gsm8k,hotpotqa,labbench,lfrqa,notebook]'  # with envs
pip install 'fhaviary[dev]'                                # +tutorials

Python 3.11–3.13. License Apache-2.0.

Quickstart — define a custom environment

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

CounterState = namedtuple("CounterState", ["count"])

class CounterEnv(Environment[CounterState]):
    """Agent must increment a counter to 10."""
    async def reset(self):
        self.state = CounterState(count=0)
        self.target = 10
        self.tools = [Tool.from_function(self.incr), Tool.from_function(self.decr)]
        return [Message(content=f"Count to 10. counter={self.state.count}")], self.tools

    async def step(self, action: ToolRequestMessage):
        obs = await self.exec_tool_calls(action)
        reward = int(self.state.count == self.target)
        return obs, reward, reward == 1, False

    def incr(self): self.state = CounterState(self.state.count + 1); return f"counter={self.state.count}"
    def decr(self): self.state = CounterState(self.state.count - 1); return f"counter={self.state.count}"

Run a built-in env with a simple agent

import asyncio
from aviary.envs.gsm8k import GSM8KDatasetEnv
from ldp.agent import SimpleAgent
from ldp.alg import RolloutManager

async def main():
    env = GSM8KDatasetEnv()
    agent = SimpleAgent()                # uses default OpenAI model
    rollouts = RolloutManager(agent, env)
    trajectories = await rollouts.sample_trajectories(num=10)
    accuracy = sum(t.steps[-1].reward for t in trajectories) / len(trajectories)
    print(f"Accuracy: {accuracy:.1%}")

asyncio.run(main())

Common recipes

Evaluate a custom agent on LFRQA (scientific literature)

Useful for benchmarking your own retrieval-augmented agent against PaperQA-style baselines.

Build a Jupyter-notebook environment

The aviary/notebook env lets you wrap arbitrary Jupyter workflows as a gym task. This is the foundation under FutureHouse's finch agent.

Plug into RL training

Aviary environments expose reset / step / reward / done like Gym, so they drop into any RL framework. FutureHouse's ldp is the canonical companion; trl (Hugging Face) also works.

Demo-friendly first call

import asyncio
from aviary.envs.gsm8k import GSM8KDatasetEnv

async def demo():
    env = GSM8KDatasetEnv()
    obs, tools = await env.reset()
    print("Observation:", obs[0].content[:300])
    print("Tools available:", [t.info.name for t in tools])

asyncio.run(demo())

When to use Aviary

Caveats

• Aviary is a framework not a product — it expects you to bring an agent and an evaluation goal.
• Some envs (labbench, lfrqa) require dataset downloads on first use.
• For full reproduction of the paper's training results, you also need LDP and significant GPU compute.