feat(core): updates to mailbox and agentverse registration process (#588

)

python/docs/api/uagents/agent.md

@@ -130,7 +130,7 @@ An agent that interacts within a communication environment.
 - `_logger` - The logger instance for logging agent activities.
 - `_endpoints` _List[AgentEndpoint]_ - List of endpoints at which the agent is reachable.
 - `_use_mailbox` _bool_ - Indicates if the agent uses a mailbox for communication.
-- `_agentverse` _dict_ - Agentverse configuration settings.
+- `_agentverse` _AgentverseConfig_ - Agentverse configuration settings.
 - `_mailbox_client` _MailboxClient_ - The client for interacting with the agentverse mailbox.
 - `_ledger` - The client for interacting with the blockchain ledger.
 - `_almanac_contract` - The almanac contract for registering agent addresses to endpoints.
@@ -168,8 +168,7 @@ An agent that interacts within a communication environment.
 - `identifier` _str_ - The Agent Identifier, including network prefix and address.
 - `wallet` _LocalWallet_ - The agent's wallet for transacting on the ledger.
 - `storage` _KeyValueStore_ - The key-value store for storage operations.
-- `mailbox` _Dict[str, str]_ - The mailbox configuration for the agent.
-- `agentverse` _Dict[str, str]_ - The agentverse configuration for the agent.
+- `agentverse` _AgentverseConfig_ - The agentverse configuration for the agent.
 - `mailbox_client` _MailboxClient_ - The client for interacting with the agentverse mailbox.
 - `protocols` _Dict[str, Protocol]_ - Dictionary mapping all supported protocol digests to their
   corresponding protocols.
@@ -185,7 +184,8 @@ def __init__(name: Optional[str] = None,
              seed: Optional[str] = None,
              endpoint: Optional[Union[str, List[str], Dict[str, dict]]] = None,
              agentverse: Optional[Union[str, Dict[str, str]]] = None,
-             mailbox: Optional[Union[str, Dict[str, str]]] = None,
+             mailbox: bool = False,
+             proxy: bool = False,
              resolve: Optional[Resolver] = None,
              registration_policy: Optional[AgentRegistrationPolicy] = None,
              enable_wallet_messaging: Union[bool, Dict[str, str]] = False,
@@ -208,7 +208,8 @@ Initialize an Agent instance.
 - `seed` _Optional[str]_ - The seed for generating keys.
 - `endpoint` _Optional[Union[str, List[str], Dict[str, dict]]]_ - The endpoint configuration.
 - `agentverse` _Optional[Union[str, Dict[str, str]]]_ - The agentverse configuration.
-- `mailbox` _Optional[Union[str, Dict[str, str]]]_ - The mailbox configuration.
+- `mailbox` _bool_ - True if the agent will receive messages via an Agentverse mailbox.
+- `proxy` _bool_ - True if the agent will receive messages via an Agentverse proxy endpoint.
 - `resolve` _Optional[Resolver]_ - The resolver to use for agent communication.
 - `enable_wallet_messaging` _Optional[Union[bool, Dict[str, str]]]_ - Whether to enable
   wallet messaging. If '{"chain_id": CHAIN_ID}' is provided, this sets the chain ID for
@@ -328,29 +329,13 @@ Get the key-value store used by the agent for data storage.
 
 - `KeyValueStore` - The key-value store instance.
 
-<a id="src.uagents.agent.Agent.mailbox"></a>
-
-#### mailbox
-
-```python
-@property
-def mailbox() -> Dict[str, str]
-```
-
-Get the mailbox configuration of the agent.
-Agentverse overrides it but mailbox is kept for backwards compatibility.
-
-**Returns**:
-
-  Dict[str, str]: The mailbox configuration.
-
 <a id="src.uagents.agent.Agent.agentverse"></a>
 
 #### agentverse
 
 ```python
 @property
-def agentverse() -> Dict[str, str]
+def agentverse() -> AgentverseConfig
 ```
 
 Get the agentverse configuration of the agent.
@@ -419,22 +404,6 @@ Get the metadata associated with the agent.
 
   Dict[str, Any]: The metadata associated with the agent.
 
-<a id="src.uagents.agent.Agent.mailbox"></a>
-
-#### mailbox
-
-```python
-@mailbox.setter
-def mailbox(config: Union[str, Dict[str, str]])
-```
-
-Set the mailbox configuration for the agent.
-Agentverse overrides it but mailbox is kept for backwards compatibility.
-
-**Arguments**:
-
-- `config` _Union[str, Dict[str, str]]_ - The new mailbox configuration.
-
 <a id="src.uagents.agent.Agent.agentverse"></a>
 
 #### agentverse
@@ -863,7 +832,7 @@ This class manages a collection of agents and orchestrates their execution.
   response Futures.
 - `_logger` _Logger_ - The logger instance.
 - `_server` _ASGIServer_ - The ASGI server instance for handling requests.
-- `_agentverse` _Dict[str, str]_ - The agentverse configuration for the bureau.
+- `_agentverse` _AgentverseConfig_ - The agentverse configuration for the bureau.
 - `_use_mailbox` _bool_ - A flag indicating whether mailbox functionality is enabled for any
   of the agents.
 - `_registration_policy` _AgentRegistrationPolicy_ - The registration policy for the bureau.

python/docs/api/uagents/config.md

@@ -8,29 +8,41 @@
 
 ```python
 def parse_endpoint_config(
-    endpoint: Optional[Union[str, List[str], Dict[str, dict]]]
-) -> List[AgentEndpoint]
+        endpoint: Optional[Union[str, List[str], Dict[str, dict]]],
+        agentverse: AgentverseConfig,
+        mailbox: bool = False,
+        proxy: bool = False,
+        logger: Optional[logging.Logger] = None) -> List[AgentEndpoint]
 ```
 
 Parse the user-provided endpoint configuration.
 
+**Arguments**:
+
+- `endpoint` _Optional[Union[str, List[str], Dict[str, dict]]]_ - The endpoint configuration.
+- `agentverse` _AgentverseConfig_ - The agentverse configuration.
+- `mailbox` _bool_ - Whether to use the mailbox endpoint.
+- `proxy` _bool_ - Whether to use the proxy endpoint.
+- `logger` _Optional[logging.Logger]_ - The logger to use.
+
+
 **Returns**:
 
-  Optional[List[Dict[str, Any]]]: The parsed endpoint configuration.
+- `Optional[List[AgentEndpoint]` - The parsed endpoint configuration.
 
 <a id="src.uagents.config.parse_agentverse_config"></a>
 
 #### parse`_`agentverse`_`config
 
 ```python
 def parse_agentverse_config(
-    config: Optional[Union[str, Dict[str, str]]] = None
-) -> Dict[str, Union[str, bool, None]]
+        config: Optional[Union[str, Dict[str,
+                                         str]]] = None) -> AgentverseConfig
 ```
 
 Parse the user-provided agentverse configuration.
 
 **Returns**:
 
-  Dict[str, Union[str, bool, None]]: The parsed agentverse configuration.
+- `AgentverseConfig` - The parsed agentverse configuration.
 

python/docs/api/uagents/mailbox.md

@@ -2,67 +2,70 @@
 
 # src.uagents.mailbox
 
-<a id="src.uagents.mailbox.MailboxClient"></a>
+<a id="src.uagents.mailbox.is_mailbox_agent"></a>
 
-## MailboxClient Objects
+#### is`_`mailbox`_`agent
 
 ```python
-class MailboxClient()
+def is_mailbox_agent(endpoints: list[AgentEndpoint],
+                     agentverse: AgentverseConfig) -> bool
 ```
 
-Client for interacting with the Agentverse mailbox server.
+Check if the agent is a mailbox agent.
 
-<a id="src.uagents.mailbox.MailboxClient.base_url"></a>
+**Returns**:
 
-#### base`_`url
+- `bool` - True if the agent is a mailbox agent, False otherwise.
+
+<a id="src.uagents.mailbox.is_proxy_agent"></a>
+
+#### is`_`proxy`_`agent
 
 ```python
-@property
-def base_url()
+def is_proxy_agent(endpoints: list[AgentEndpoint],
+                   agentverse: AgentverseConfig) -> bool
 ```
 
-Property to access the base url of the mailbox server.
+Check if the agent is a proxy agent.
+
+**Returns**:
 
-Returns: The base url of the mailbox server.
+- `bool` - True if the agent is a proxy agent, False otherwise.
 
-<a id="src.uagents.mailbox.MailboxClient.agent_mailbox_key"></a>
+<a id="src.uagents.mailbox.register_in_agentverse"></a>
 
-#### agent`_`mailbox`_`key
+#### register`_`in`_`agentverse
 
 ```python
-@property
-def agent_mailbox_key()
+async def register_in_agentverse(
+        request: AgentverseConnectRequest, identity: Identity,
+        endpoints: list[AgentEndpoint],
+        agentverse: AgentverseConfig) -> RegistrationResponse
 ```
 
-Property to access the agent_mailbox_key of the mailbox server.
+Registers agent in Agentverse
 
-Returns: The agent_mailbox_key of the mailbox server.
+**Arguments**:
 
-<a id="src.uagents.mailbox.MailboxClient.protocol"></a>
+- `request` _AgentverseConnectRequest_ - Request object
+- `identity` _Identity_ - Agent identity object
+- `endpoints` _list[AgentEndpoint]_ - Endpoints of the agent
+- `agentverse` _AgentverseConfig_ - Agentverse configuration
+
 
-#### protocol
+**Returns**:
 
-```python
-@property
-def protocol()
-```
-
-Property to access the protocol of the mailbox server.
-
-Returns: The protocol of the mailbox server {ws, wss, http, https}.
+- `RegistrationResponse` - Registration
 
-<a id="src.uagents.mailbox.MailboxClient.http_prefix"></a>
+<a id="src.uagents.mailbox.MailboxClient"></a>
 
-#### http`_`prefix
+## MailboxClient Objects
 
 ```python
-@property
-def http_prefix()
+class MailboxClient()
 ```
 
-Property to access the http prefix of the mailbox server.
-
-Returns: The http prefix of the mailbox server {http, https}.
+Client for interacting with the Agentverse mailbox server.
 
 <a id="src.uagents.mailbox.MailboxClient.run"></a>
 
@@ -74,23 +77,3 @@ async def run()
 
 Runs the mailbox client.
 
-<a id="src.uagents.mailbox.MailboxClient.start_polling"></a>
-
-#### start`_`polling
-
-```python
-async def start_polling()
-```
-
-Runs the mailbox client. Acquires an access token if needed and then starts a polling loop.
-
-<a id="src.uagents.mailbox.MailboxClient.process_deletion_queue"></a>
-
-#### process`_`deletion`_`queue
-
-```python
-async def process_deletion_queue()
-```
-
-Processes the deletion queue. Deletes envelopes from the mailbox server.
-

python/examples/11-mailbox-agents/alice.py

@@ -5,25 +5,11 @@ class Message(Model):
     message: str
 
 
-# First generate a secure seed phrase (e.g. https://pypi.org/project/mnemonic/)
-SEED_PHRASE = "put_your_seed_phrase_here"
-
-# Copy the address shown below
-print(f"Your agent's address is: {Agent(seed=SEED_PHRASE).address}")
-
-# Then go to https://agentverse.ai, register your agent in the Mailroom
-# and copy the agent's mailbox key
-AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_here"
-
 # Now your agent is ready to join the agentverse!
-agent = Agent(
-    name="alice",
-    seed=SEED_PHRASE,
-    mailbox=f"{AGENT_MAILBOX_KEY}@https://agentverse.ai",
-)
+agent = Agent(name="alice", port=8008, mailbox=True)
 
 
-@agent.on_message(model=Message, replies={Message})
+@agent.on_message(model=Message, replies=Message)
 async def handle_message(ctx: Context, sender: str, msg: Message):
     ctx.logger.info(f"Received message from {sender}: {msg.message}")
 

python/examples/11-mailbox-agents/bob.py

@@ -8,22 +8,9 @@ class Message(Model):
 # Copy ALICE_ADDRESS generated in alice.py
 ALICE_ADDRESS = "paste_alice_address_here"
 
-# Generate a second seed phrase (e.g. https://pypi.org/project/mnemonic/)
-SEED_PHRASE = "put_your_seed_phrase_here"
-
-# Copy the address shown below
-print(f"Your agent's address is: {Agent(seed=SEED_PHRASE).address}")
-
-# Then go to https://agentverse.ai, register your agent in the Mailroom
-# and copy the agent's mailbox key
-AGENT_MAILBOX_KEY = "put_your_AGENT_MAILBOX_KEY_here"
 
 # Now your agent is ready to join the agentverse!
-agent = Agent(
-    name="bob",
-    seed=SEED_PHRASE,
-    mailbox=f"{AGENT_MAILBOX_KEY}@https://agentverse.ai",
-)
+agent = Agent(name="bob", port=8009, mailbox=True)
 
 
 @agent.on_interval(period=2.0)

python/examples/12-remote-agents/agent1.py

@@ -36,7 +36,6 @@ async def act_on_message(ctx: Context, sender: str, msg: Message):
     ctx.logger.info(f"Received message from {sender[-8:]}: {msg.message}")
 
 
-print(f"Agent address: {alice.address}")
 print(f"Agent public URL: {http_tunnel.public_url}/submit")
 
 if __name__ == "__main__":

python/examples/17-stateful-communication/agent1.py

@@ -121,5 +121,4 @@ async def conclude_chitchat(
 
 
 if __name__ == "__main__":
-    print(f"Agent address: {agent.address}")
     agent.run()

python/examples/17-stateful-communication/agent2.py

@@ -120,5 +120,4 @@ async def start_cycle(ctx: Context):
 
 
 if __name__ == "__main__":
-    print(f"Agent address: {agent.address}")
     agent.run()

python/examples/17-stateful-communication/agent3.py

@@ -54,5 +54,4 @@ async def continue_chitchat(
 
 
 if __name__ == "__main__":
-    print(f"Agent address: {agent.address}")
     agent.run()

python/examples/17-stateful-communication/agent4.py

@@ -49,5 +49,4 @@ async def start_cycle(ctx: Context):
 agent.include(chitchat_dialogue)
 
 if __name__ == "__main__":
-    print(f"Agent address: {agent.address}")
     agent.run()