agency

Updates AMQPSpace to use a topic exchange for better observability. Thanks @wwj718! 🙏

I'm proud to announce Agency v1.6.0. Technically, it represents a big step forward and I believe is a milestone in terms of clarity for the project.

It took some iterating and lots of thoughtful feedback, but I think the learnings from the last few versions have come together to create a clearer picture for the API and architecture. I believe there is a good foundation now to focus on the next steps: js client, code execution, and multimodal support.

Special thanks to @wwj718 and @hidaris for their reviews and feedback that helped shape this release!

As with any major release, please do not hesitate to open issues or discussions if you have any questions or feedback. 🙇‍♂️

Summary of Changes

Space types now support mixed threading/multiprocessing for agents

Version 1.4 introduced multiprocessing but did not allow threading and multiprocessing based agents to be used together. Additionally the API prevented some use cases that were previously possible, due to not allowing direct access to agents from the main thread.

In 1.6.0, all agents are now add'ed using multiprocessing based subprocesses by default. Agents added this way may not be directly accessed, similar to 1.4.

With 1.6.0 you now have the option to run agents in the "foreground" using Space.add_foreground. When adding an agent this way, an instance of the agent is returned in the current thread. For example:

my_agent = my_space.add_foreground(MyAgent, "my_agent")

The tradeoff for adding an agent in the foreground is performance. Due to the python GIL, agents running in the foreground may not be fully parallel with other agents, and may block the main thread.

It's recommended to use Space.add_foreground only when needed.

MultiprocessSpace and ThreadSpace classes replaced with LocalSpace

Since all Space types now support mixed threading/multiprocessing, LocalSpace combines these older types into a single class for in-application communication.

Context manager support and Space.destroy method added

These two additions allow for improved resource management. Creating and cleaning up a Space can now be done using the context manager syntax:

with AMQPSpace() as space:
    space.add(Host, "Host")
    ...

This form will automatically clean up Space related resources upon exit of the with block.

Direct control of cleanup is also possible using the Space.destroy method.

space = AMQPSpace()
space.add(Host, "Host")
...
space.destroy()

Agent.respond_with and Agent.raise_with methods added

These methods are intended for use with Agent.request and the response callbacks: Agent.handle_action_value and Agent.handle_action_error.

Automatic response behavior has changed from v1.5. Actions will no longer automatically return their return value to the sender.

To explicitly return a value to the sender associated with the current message, use Agent.respond_with. For example:

@action
def ping(self):
    self.respond_with("pong")

The above will invoke the handle_action_value callback on the sender with the value "pong", or return the value "pong" directly when used with the request method.

Similarly you may return an error with:

@action
def ping(self):
    self.raise_with(Exception("oops"))

Actions that raise exceptions will automatically call the raise_with method.

Note that respond_with and raise_with may be called multiple times in a single action. Each call will invoke the appropriate callback on the sender.

When using request the first call to respond_with will return the value to the calling thread. Subsequent responses will invoke the handle_action_value callback.

Performance Improvements

All busy wai

This release addresses the request related issues brought up here regarding the use of multiple "meta" id's and the semantics of automatic responses to messages. Shoutout to @wwj718 for the great feedback for these updates!

Since this includes breaking changes, the version has been bumped to 1.5.0.

Summary:

• All messages now populate the meta.id field with a UUID by default. Agents may set their own custom meta.id upon sending to overwrite the generated ID.

  In addition, Agent.send() now returns the meta.id of the sent message. This way you may store the generated ID for your own purposes.

• Removed the use of meta.response_id and meta.request_id. These have been replaced by meta.parent_id. I think the term "parent" is clearer. This choice is inspired by the Jupyter messaging docs.

  To be clear, meta.parent_id if set, refers to the meta.id of the original message which the current message is responding to.

  To illustrate, the following would be typical meta fields in a send/response pair:

  # send
  {
    "meta": {
      "id": "123", # the message ID here
    },
    ...
  }
  # response
  {
    "meta": {
      "id": "456", # response has its own unique meta.id
      "parent_id": "123", # refers to the prior message
    },
    ...
  }
  

• All messages will now result in a [response] message like the above, returning the return value or error result from the message's action. These messages (unless using the request() method) will invoke the handle_action_value() and handle_action_error() methods appropriately.

  One might want to filter these messages from view in a user interface. The demo Gradio app has been updated to demonstrate this. See the _should_render() and get_chatbot_message() methods for an example.

• Agent.original_message() has been renamed to Agent.parent_message(). Additionally parent_message() takes a message as a parameter, allowing you to traverse a chain of messages in reverse.

• Internally renamed Agent._pending_responses to Agent._pending_requests which I think is clearer.

• The logger has been updated to provide colorization of output for easier reading. You may change the default "monokai" pygments style used for object output, by setting the LOG_PYGMENTS_STYLE environment variable.

• Log "warning" messages for unimplemented handle_action_value and handle_action_error methods have been updated to only print once per session, in order to reduce logging noise in the default setting.

• Tests and documentation updated.

Fixes a regression in the 1.4.0 release related to the AMQP exchange parameter