agent-contracts

agent-contracts is an advanced framework designed for creating scalable LangGraph agents through contract-driven architecture. This innovative approach separates node behavior from graph topology, allowing developers to define clear interfaces for complex multi-agent systems, enhancing maintainability and structure in agent development.

Understanding the Challenges

Building robust multi-agent systems can become complex as raw graphs grow. Adding nodes and ensuring seamless data flow often leads to unmanageable manual wiring and scattered routing logic. The agent-contracts framework addresses these challenges by automating graph construction and clarifying data flow.

Key Features of agent-contracts

• Contract-Driven Design: Define clear input and output contracts for each node, enabling automated interactions within the agent framework.
• Automatic Wiring: Automatically constructs the LangGraph based on defined NodeContracts, minimizing the manual labor previously required.
• Hybrid Routing: Combines rule-based and LLM-driven routing logic for nuanced decision-making.
• Type-safe State Management: Robust state management using type validation for safer and more predictable execution.

Target Audience

This library is particularly suited for:

• Developers creating complex multi-agent systems that require maintainability.
• Teams collaborating on distinct agent modules.
• Production environments where strict interface definitions are crucial.

Use Cases

• Complex Routing Logic: Facilitates managing numerous agents where decision-making is based on both fixed rules and LLM outputs.
• Modular Agent Development: Supports developers in building agent logic without needing awareness of the entire graph layout.
• Hybrid Supervisory Control: Implements a structured supervisor that adheres first to business rules, utilizing LLM only for ambiguous decisions.

Core Concepts

1. NodeContract: The foundation for each node, specifying the expected I/O and trigger conditions.

   NodeContract(
       name="my_node",
       description="Performs data processing tasks",
       reads=["input_data"],
       writes=["output_data"],
       requires_llm=False,
       supervisor="main",
       trigger_conditions=[
           TriggerCondition(llm_hint="User requests a process")
       ]
   )
   

2. AgentRuntime: The unified execution engine that handles the lifecycle of agent interactions, providing hooks for custom behavior and session management.
3. State Accessor: Implements a safe way to interact with node states, reducing errors and improving clarity in state handling.

   user_id = Internal.user_id.get(state)
   

Implementation Example

A simple implementation to return a greeting:

from agent_contracts import ModularNode, NodeContract, NodeInputs, NodeOutputs

class HelloNode(ModularNode):
    CONTRACT = NodeContract(
        name="hello",
        writes=["response"],
        trigger_conditions=[{"priority": 100}]
    )

    async def execute(self, inputs: NodeInputs, config=None) -> NodeOutputs:
        return NodeOutputs(response={"message": "Hello World!"})

Observability and Documentation

The framework integrates with LangSmith for deep observability, allowing developers to trace decisions made by the supervisory layer, thus enhancing debugging and system understanding. Additionally, documentation can be automatically generated to visualize the architecture and flow of agents.

Conclusion

agent-contracts provides a powerful, structured approach for developers looking to build and maintain complex agent systems. By decoupling behavior from graph topology and enabling contract-driven design, it paves the way for scalable, maintainable, and effective multi-agent applications.