A fast and minimal actor model framework for building agent-integrated systems
Project description
Summary
agency
defines a common communication and action framework for creating AI
agent integrated applications.
The library provides a low-level means for connecting agents, systems, and human users by defining actions, callbacks, and access policies that you can use to monitor, control, and interact with your agents.
agency
handles the details of the common messaging system and allows
discovering and invoking actions across parties, automatically handling things
such as reporting exceptions, enforcing access restrictions, and more.
agency
's purpose is to support agent development and integration by allowing
you to create dynamic environments for your agents to freely work in a safe and
controllable way, and to leave all other details up to you.
Set your agents free (or just as much as you want) with agency
!
Features
Low-Level API Flexibility
- Straightforward class/method based agent and action definition
- Supports defining single process applications or networked agent systems using AMQP
Observability and Control
- Before/After action callbacks for observability or other needs
- Access policies and permission callbacks for access control
Performance
- Multithreaded (though python's GIL is a bottleneck for single process apps)
- AMQP support for multiprocess and networked systems (avoids GIL)
- Python multiprocess support is planned for better scalability on single-host systems
Multimodal (image/audio) support
Full demo available at examples/demo
- Two OpenAI agent examples
- HuggingFace transformers agent example
- Simple Flask/React web interface included
- Direct host access for agents
- Docker configuration for reference and development
API Overview
agency
is an implementation of the Actor
model for building AI agent
integrated systems.
In agency
, all entities are represented as instances of the Agent
class.
This includes all humans, software, and AI-driven agents that may communicate as
part of your application.
All agents may expose "actions" that other agents can discover and invoke at run time. An example of a simple agent implemention could be:
class CalculatorAgent(Agent):
def _action__add(a, b):
return a + b
This defines an agent with a single action: "add"
. Other agents will be able
to call this method by sending a message to an instance of CalculatorAgent
and
specifying the "add"
action.
other_agent._send({
'to': 'CalcAgent',
'thoughts': 'Optionally explain here',
'action': 'add',
'args': {
'a': 1,
'b': 2,
},
})
Actions must also specify an access policy, allowing you to control access for safety. For example:
@access_policy(ACCESS_PERMITTED) # This allows the action at any time
def _action__add(a, b):
...
You can also define before/after and permission callbacks for various purposes:
class CalculatorAgent(Agent):
...
def _before_action(self, original_message: dict):
# Called before any action is attempted
def _after_action(self, original_message: dict, return_value: str, error: str):
# Called after any action is attempted
def _request_permission(self, proposed_message: dict) -> bool:
# Called before an ACCESS_REQUESTED action is attempted for run-time review
A Space
is how you connect your agents together. An agent cannot communicate
with others until it is added to a common "space".
There are two included Space
implementations to choose from:
NativeSpace
- which connects agents within the same python processAMQPSpace
- which connects agents across processes and systems using an AMQP server like RabbitMQ.
Here is an example of creating a NativeSpace
and adding two agents to it.
space = NativeSpace()
space.add(CalculatorAgent("CalcAgent"))
space.add(AIAgent("AIAgent"))
# The agents above can now communicate
These are just some of the main agency
features. For more detailed information
please see the docs directory.
Install
pip install agency
or
poetry add agency
Running the Demo Application
To run the demo, please follow the directions at examples/demo.
After a short boot time you can visit the web app at http://localhost:8080
and
you should see a simple chat interface. The following is a screenshot of a
conversation that demonstrates multiple agents intelligently interacting and
following orders.
There are two OpenAI based agents: "FunctionAI"
and "CompletionAI"
, named
for the API's they use, and "Chatty"
a simple chat agent who uses a small
local transformers based model for demonstration.
The screenshot also demonstrates the results of rejecting an action and
directing an agent to use a different approach in real time. After I explained
my rejection of the read_file
action (which happened behind the scenes on the
terminal), "FunctionAI"
appropriately used the shell_command
action with wc -l Dockerfile
.
FAQ
How does agency
compare to agent libraries like LangChain?
Though you could entirely create a simple agent using only the primitives in
agency
(see examples/demo/agents/
), it is not
intended to be a full-fledged agent toolset.
Projects like LangChain and others are exploring how to create purpose-built
agents that solve diverse problems using tools. agency
is focused on the
problems surrounding agent/tool integration, such as observability and access
control.
More likely, you would use LangChain and other libraries for defining agent
behavior and rely on agency
to provide the connective layer for bringing
agents and other systems together.
So in comparison, agency
is a smaller but more general purpose application
framework compared to libraries like LangChain that focus on enabling individual
agent behavior.
What are some known limitations or issues?
-
It's a new project, so keep that in mind in terms of completeness, but see the issues page for what is currently planned, and the Roadmap below for the high level plan.
-
This library makes use of threads for each individual agent. Multithreading is limited by python's GIL, meaning that if you run a local model or other heavy computation in the same process as other agents, they may have to wait for their "turn". Note that I/O does not block, so networked backends or services will execute in parallel.
For blocking processes, it's recommended to use the
AMQPSpace
class and run heavy computations in isolation to avoid blocking other agents. -
This API does not assume or enforce predefined roles like "user", "system", "assistant", etc. This is an intentional decision and is not likely to change.
agency
is intended to allow potentially large numbers of agents, systems, and people to come together. A small predefined set of roles gets in the way of representing many things generally. This is a core feature ofagency
: that all entities are treated the same and may be interacted with through common means.The lack of roles may require extra translation code when integrating with role based APIs. See the implementation of
OpenAIFunctionAgent
for an example. -
There is currently not much by way of storage support. That is mostly left up to you and I'd suggest looking at the many technologies that focus on that. The
Agent
class implements a simple_message_log
array which you can make use of or overwrite to back it with longer term storage. More direct support for storage APIs will likely be considered in the future.
Contributing
Please do!
Development Installation
git clone git@github.com:operand/agency.git
cd agency
poetry install
Developing with the Demo Application
See the demo directory for instructions on how to run the demo.
The demo application is written to showcase both native and AMQP spaces and several agent examples. It can also be used for experimentation and development.
The application is configured to read the agency library source when running, allowing changes to be tested manually.
Test Suite
Ensure you have Docker installed. A small RabbitMQ container will be automatically created.
You can run the test suite with:
poetry run pytest
Roadmap
-
Multiprocess Support: An additional space type utilizing python multiprocessing, as another parallelism option for single-host systems.
-
Multimodal Support: Image/audio transfer for use with multimodal models or other multimedia services.
-
More Examples: More examples of integrations with popular AI libraries and tools such as Langchain and oobabooga.
Planned Work
If you have any suggestions or otherwise, feel free to add an issue!
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.