Future House Aviary Aviary Agent Gym

---
name: aviary-agent-gym
description: Aviary is FutureHouse's open-source gymnasium for defining and benchmarking LLM agents on scientific tasks (math, multi-hop QA, biological sequences, scientific literature search, Jupyter notebooks). Use when the user wants to evaluate an LLM agent on standardized scientific environments, build custom RL-style environments for agent training, or reproduce results from the Aviary paper.
metadata:
  skill-author: Compiled from FutureHouse aviary (Apache-2.0)
  upstream: https://github.com/Future-House/aviary
---

# 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](https://github.com/Future-House/ldp) to actually run / train agents against the environments.

Reference: [arXiv:2412.21154](https://arxiv.org/abs/2412.21154) ("Aviary: Training Language Agents on Challenging Scientific Tasks").

## Built-in environments

| Env | Task |
|---|---|
| `gsm8k` | Grade-school math word problems |
| `hotpotqa` | Multi-hop general-knowledge QA |
| `labbench` | Biological sequence reasoning (LAB-Bench tasks) |
| `lfrqa` | Scientific literature search QA (LitQA-style) |
| `notebook` | Run / inspect a Jupyter notebook |

## Install

```bash
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

```python
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

```python
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](https://github.com/Future-House/ldp) is the canonical companion; `trl` (Hugging Face) also works.

## Demo-friendly first call

```python
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

| Use case | Pick |
|---|---|
| Benchmark a research agent on standard scientific tasks | **Aviary** (this skill) |
| Train an LLM agent with RL on custom science tasks | Aviary + LDP |
| Just want answers from an agent (not training) | Crow / Falcon / paper-qa |

## 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.