feat(agentenv-wrapper): Generic tool-based wrapper for AgentGym environments

[supmo668]

Summary

This PR introduces agentenv-wrapper, a generic package for adapting AgentGym environments into tool-based interfaces suitable for LLM agent frameworks like LangChain.

This addresses the feedback on PR WooooDyy#68 (WooooDyy/AgentGym) where @SixPlusSeven67 suggested creating a consistent mapping from existing AgentEnvironments to tools, rather than just demonstrating the MCP server pattern.

Architecture

flowchart TB
    subgraph Agent["Agent Framework"]
        LC[LangChain Agent]
        CA[Custom Agent]
    end

    subgraph Wrapper["AgentEnv Wrapper"]
        BTW[BaseToolWrapper]
        TEW[ToolEnvironmentWrapper]
        subgraph Adapters
            BAW[BabyAIToolWrapper]
            WSW[WebShopToolWrapper]
            CW["..."]
        end
        subgraph LCI["LangChain Integration"]
            CLT[create_langchain_tools]
            CAE[create_agent_for_env]
            AER[AgentEnvRunner]
        end
    end

    subgraph Servers["AgentGym Environment Servers"]
        BS[BabyAI Server]
        WS[WebShop Server]
        OS["..."]
    end

    LC --> CLT
    CA --> BTW
    CLT --> BAW
    CAE --> BAW
    BAW --> BS
    TEW --> WS
    TEW --> OS

Loading

Changes

Core Components

• models.py: Data models (ActionTool, ToolDefinition, ToolResult, EnvState)
• base.py: BaseToolWrapper abstract class and ToolEnvironmentWrapper
• adapters/babyai.py: BabyAI-specific adapter with action parsing

LangChain Integration

• langchain/tools.py: Convert wrapper tools to LangChain tools
• langchain/agent.py: create_agent_for_env() using v1 syntax (initialize_agent)
• AgentEnvRunner: Episode runner with batch support and metrics

Examples & Tests

• examples/babyai_langchain_example.py: Full usage examples
• tests/: Unit tests for models and wrappers

Key Design Decisions

1. v1 LangChain Syntax: Uses initialize_agent instead of create_react_agent for broader compatibility
2. Dynamic Action Space: Tools are regenerated after each action to reflect environment state
3. Framework Agnostic: Base wrapper can be used without LangChain
4. Specialized Adapters: Environment-specific adapters (BabyAI) with proper action parsing

Usage Example

from langchain_openai import ChatOpenAI
from agentenv_wrapper import BabyAIToolWrapper
from agentenv_wrapper.langchain import create_agent_for_env

# Create wrapper
wrapper = BabyAIToolWrapper("http://localhost:8080")
wrapper.reset(task_id=1)

# Create agent
llm = ChatOpenAI(model="gpt-4")
agent = create_agent_for_env(wrapper, llm)

# Run
result = agent.invoke({"input": wrapper.get_system_prompt()})

Type of Change

• New feature
• Bug fix
• Breaking change
• Documentation update

Testing

• Added unit tests for models
• Added unit tests for wrappers (mocked HTTP)
• Integration tests (requires running BabyAI server)

Checklist

• Code follows project style
• Self-reviewed
• Updated documentation (README.md)
• No debug code

Related

• Addresses feedback from feat(agentenv-mcp): Environment with MCP-configurable action space WooooDyy/AgentGym#68
• Provides foundation for adapting other environments (WebShop, TextCraft, etc.)