Agency
A fast and minimal framework for building agentic systems
Last verified:
What is Agency?
Agency is a fast and minimal Python framework for building agentic systems that unifies human, AI, and other computing systems. It provides an Actor model framework for creating agent-integrated systems with an easy-to-use API that enables developers to connect agents with traditional software systems in a flexible and scalable way. The framework allows you to develop any architecture you need by providing a minimal foundation to both experiment and build upon.
Key features include a straightforward class/method-based agent and action definition using the @action decorator, two Space types (LocalSpace for agents within the same application and AMQPSpace for networked agent communication via AMQP server like RabbitMQ), support for multiprocessing and multithreading for concurrency, action and lifecycle callbacks, access policies with ACCESS_PERMITTED/ACCESS_DENIED/ACCESS_REQUESTED for safety control, detailed logging, and built-in observability. The framework includes OpenAIFunctionAgent for OpenAI API integration, a HuggingFace transformers agent (ChattyAI), a Host agent for system access, and a Gradio-based UI for user interaction.
Agency is designed for Python developers building custom agent-based applications, including those creating multi-agent systems, customer service chatbots, smart home systems, research agents, DAOs with multiple decision-making agents, and multi-agent simulations. It's particularly suitable for developers who want flexibility without heavy abstractions, those needing agent integration with traditional systems, and teams requiring scalable distributed agent communication.
Agency pricing
Pricing model: Freemium
Agency is free and open-source under the MIT license. It can be installed via pip (pip install agency) or poetry (poetry add agency). There are no paid tiers or subscription plans. The framework itself is completely free, though using OpenAIFunctionAgent requires an OpenAI API key which incurs costs from OpenAI based on token usage. AMQPSpace requires setting up your own AMQP server like RabbitMQ, which may have associated hosting costs depending on your infrastructure.
Agency pros
- Fast and minimal framework with few abstractions
- Easy-to-use class/method-based API for agent definition
- Straightforward @action decorator for exposing agent actions
- LocalSpace connects agents within same Python application
- AMQPSpace enables networked agent communication across hosts
- Supports multiprocessing and multithreading for concurrency
- Access policies (ACCESS_PERMITTED/ACCESS_DENIED/ACCESS_REQUESTED) for safety
- Action and lifecycle callbacks for observability and control
- Built-in help action for agent and action discovery
- Broadcast messaging to all agents using special '*' id
- OpenAIFunctionAgent integrates with OpenAI function calling API
- Includes Gradio UI demo for user interaction
- Context manager syntax for Space cleanup
- Detailed documentation with example application walkthrough
- MIT open-source license
Agency cons
- Access control is experimental and needs feedback
- Requires OpenAI API key for OpenAIFunctionAgent (costs apply)
- AMQPSpace requires separate AMQP server setup (e.g., RabbitMQ)
- Message to non-existent agent silently fails (hard to debug)
- Limited to Python ecosystem
- No built-in state management
- Gradio UI is demo-only, not production-ready
- Requires implementing request_permission() callback for ACCESS_REQUESTED actions
Frequently asked questions about Agency
What is Agency?
Agency is a Python library that provides an Actor model framework for creating agent-integrated systems. It enables developers to connect AI agents with traditional software systems in a flexible and scalable way, allowing you to develop any architecture you need. The framework provides a minimal foundation for experimenting with and building custom agent-based applications.
How do I install Agency?
You can install Agency using pip with the command 'pip install agency' or using poetry with 'poetry add agency'. After installation, you can start creating agents by subclassing the Agent class and defining actions using the @action decorator.
What is a Space in Agency?
A Space is where agents communicate and interact with each other. Agents are instantiated within a space when added. Agency implements two Space types: LocalSpace connects agents within the same Python application using interprocess communication (IPC), while AMQPSpace connects agents across a network using an AMQP server like RabbitMQ, enabling scalable distributed agent systems.
How do agents communicate with each other?
Agents communicate by sending messages to invoke actions on other agents. Use self.send({'to': agent_id, 'action': {'name': action_name, 'args': arguments}}). The 'to' field should be the agent's id or '*' for broadcasting to all agents. Messages are validated against a schema, and the 'from' field is automatically populated.
What are access policies?
Access policies control when actions can be invoked by agents. There are three values: ACCESS_PERMITTED (default) allows any agent to use the action at any time, ACCESS_DENIED prevents access to the action, and ACCESS_REQUESTED prompts the receiving agent for permission via the request_permission() callback. This is useful for protecting dangerous actions like terminal commands.
How does agent discovery work?
All agents implement a 'help' action that returns a dictionary of their available actions. To discover agents, broadcast a message to '' with the help action. For example: self.send({'to': '', 'action': {'name': 'help'}}). Each agent responds with their available actions, allowing agents to discover all agents in the space and what they can do.
What is OpenAIFunctionAgent?
OpenAIFunctionAgent is an intelligent agent that uses the OpenAI API with function calling support. When added to a space, it automatically requests help information from other agents and provides that information to OpenAI as functions the LLM can invoke. This allows the LLM to discover and interact with other agents intelligently. It requires an OpenAI API key and model parameter.
How do I scale agents across multiple hosts?
Use AMQPSpace to connect agents across multiple hosts in a network. Separate your agents into multiple applications, each configured to use the same AMQP server via environment variables (AMQP_HOST, AMQP_PORT, AMQP_USERNAME, AMQP_PASSWORD, AMQP_VHOST) or AMQPOptions. Run all applications simultaneously, and agents will communicate over AMQP, enabling scaling beyond a single host.
Is Agency open source?
Yes, Agency is open-source under the MIT license. It is available on GitHub at operand/agency and can be freely installed via pip or poetry. The demo application in examples/demo includes multiple agent examples for experimentation, including OpenAI agents, HuggingFace agents, operating system access, and a Gradio UI.