agency

Creates Agent instances that implement the Actor model pattern, where each agent has a unique identifier (1-255 chars, non-reserved), processes messages asynchronously, and exposes lifecycle callback hooks (before_action, after_action, after_add, before_remove). Agents are initialized with identity validation and can be added to Spaces for communication without requiring pre-registration of message types or schemas.

Agents expose callable methods as discoverable 'actions' using the @action decorator, which adds metadata for runtime discovery and applies access control policies (ACCESS_PERMITTED or ACCESS_REQUESTED). Other agents can discover available actions at runtime and invoke them with automatic routing through the Space, with policies determining whether execution requires approval before proceeding.

Defines a structured message format where every message includes sender (originating agent), recipient (target agent), action (method to invoke), and payload (parameters). This structure enables type-safe routing, automatic action dispatch, and clear message semantics across both LocalSpace and AMQPSpace implementations, supporting both request-response and fire-and-forget patterns.

Routes messages between agents through a pluggable Space abstraction that supports both local (in-process) and distributed (AMQP-based) communication. Messages follow a structured format with sender, recipient, action, and payload fields; LocalSpace routes messages synchronously within a single process, while AMQPSpace routes messages asynchronously across network boundaries using an AMQP broker (e.g., RabbitMQ).

Enables agents to make synchronous requests to other agents and block until receiving a response, implementing a request-response pattern on top of the asynchronous message routing system. When an agent calls another agent's action synchronously, it blocks the calling thread until the recipient processes the action and returns a result, enabling sequential workflows and error propagation.

Allows agents to inherit shared behavior and methods through mixin classes, enabling code reuse across agent types without requiring deep inheritance hierarchies. Mixins can provide common actions (like help methods, response formatting) that are automatically discovered and exposed through the @action decorator, allowing agents to compose capabilities from multiple sources.

Integrates with OpenAI's function calling API by automatically converting agent actions into OpenAI function schemas and binding function call responses back to agent actions. When an OpenAI model requests a function call, the framework routes the call to the appropriate agent action, executes it, and returns the result to the model in the expected format, enabling LLM-driven agent orchestration.

Publishes agent state changes and events to MQTT topics, enabling external systems to subscribe to agent activity without direct coupling. When agents execute actions or change state, events are published to configurable MQTT topics (e.g., 'agency/agent/{agent_id}/action/{action_name}'), allowing monitoring systems, dashboards, or other agents to react to agent events in real-time.

Provides a Gradio-based web interface for interacting with agents, enabling non-technical users to invoke agent actions through a browser UI. The framework automatically generates Gradio components for each agent action based on parameter types, handles form submission, routes requests to agents through the Space, and displays results in the UI without requiring custom web development.

Enforces strict validation rules for agent identifiers to prevent naming conflicts and reserved name collisions. Agent IDs must be 1-255 characters, cannot start with 'amq.' (AMQP reserved prefix), and cannot be '*' (broadcast reserved). The framework validates IDs at agent creation time and maintains a namespace within each Space to ensure uniqueness and prevent routing ambiguities.

Enables runtime discovery of all agents in a Space and their available actions, including action metadata (name, help text, parameters). Agents can query a Space to list all connected agents, and for each agent, discover its available actions with full parameter information, enabling dynamic agent orchestration and UI generation without pre-shared schemas.