uagents-core 0.1.0__tar.gz

uagents_core-0.1.0/PKG-INFO

@@ -0,0 +1,27 @@
+Metadata-Version: 2.1
+Name: uagents-core
+Version: 0.1.0
+Summary: Core components for agent based systems
+License: Apache 2.0
+Author: Ed FitzGerald
+Author-email: edward.fitzgerald@fetch.ai
+Requires-Python: >=3.9,<3.13
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: aiohttp (>=3.8.3,<4.0.0)
+Requires-Dist: bech32 (>=1.2.0,<2.0.0)
+Requires-Dist: ecdsa (>=0.19.0,<0.20.0)
+Requires-Dist: msgpack (>=1.0.4,<2.0.0)
+Requires-Dist: pydantic (>=2.8,<2.9)
+Requires-Dist: requests (>=2.32.3,<3.0)
+Requires-Dist: rich (>=13.9.4,<14.0.0)
+Requires-Dist: structlog (>=24.4.0,<25.0.0)
+Description-Content-Type: text/markdown
+
+# UAgents-Core
+
+Core definitions and functionalities to build agent which can interact and integrate with Fetch.ai ecosystem and agent marketplace.

uagents_core-0.1.0/README.md

@@ -0,0 +1,3 @@
+# UAgents-Core
+
+Core definitions and functionalities to build agent which can interact and integrate with Fetch.ai ecosystem and agent marketplace.

uagents_core-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[tool.poetry]
+name = "uagents-core"
+version = "0.1.0"
+description = "Core components for agent based systems"
+authors = [
+    "Ed FitzGerald <edward.fitzgerald@fetch.ai>",
+    "James Riehl <james.riehl@fetch.ai>",
+    "Alejandro Morales <alejandro.madrigal@fetch.ai>",
+    "Florian Wilde <florian.wilde@fetch.ai>",
+    "Attila Bagoly <attila.bagoly@fetch.ai>",
+]
+packages = [{include = "uagents_core"}]
+license = "Apache 2.0"
+readme = "README.md"
+
+[tool.poetry.dependencies]
+python = ">=3.9,<3.13"
+pydantic = "~2.8"
+msgpack = "^1.0.4"
+bech32 = "^1.2.0"
+ecdsa = "^0.19.0"
+aiohttp = "^3.8.3"
+requests =">=2.32.3,<3.0"
+structlog = "^24.4.0"
+rich = "^13.9.4"
+
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+aioresponses = "^0.7.4"
+pytest = "^8.3.4"
+pytest-asyncio = "^0.25.0"
+pytest-order = "^1.3.0"
+ruff = "^0.8.4"
+pyright = "^1.1.391"
+pre-commit = "^4.0.1"
+
+
+[build-system]
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+target-version = "py310"
+
+[tool.ruff.lint]
+select = [
+    # pycodestyle (Errors, Warnings)
+    "E",
+    "W",
+    # Pyflakes
+    "F",
+    # flake8-bugbear
+    "B",
+    # flake8-simplify
+    "SIM",
+    # isort
+    "I",
+    # pep8-naming
+    "N",
+    # pylint
+    "PL",
+]
+ignore = ["PLR0913", "PLR0912", "PLR0911", "PLR2004", "PLR0915"]
+
+[tool.ruff.lint.pycodestyle]
+max-line-length = 100

uagents_core-0.1.0/uagents_core/communication.py

@@ -0,0 +1,76 @@
+import random
+from typing import Any, List, Optional, Tuple
+
+from uagents_core.config import (
+    AGENT_ADDRESS_LENGTH,
+    AGENT_PREFIX,
+)
+from uagents_core.crypto import is_user_address
+
+
+def weighted_random_sample(
+    items: List[Any], weights: Optional[List[float]] = None, k: int = 1, rng=random
+) -> List[Any]:
+    """
+    Weighted random sample from a list of items without replacement.
+
+    Ref: Efraimidis, Pavlos S. "Weighted random sampling over data streams."
+
+    Args:
+        items (List[Any]): The list of items to sample from.
+        weights (Optional[List[float]]): The optional list of weights for each item.
+        k (int): The number of items to sample.
+        rng (random): The random number generator.
+
+    Returns:
+        List[Any]: The sampled items.
+    """
+    if weights is None:
+        return rng.sample(items, k=k)
+    values = [rng.random() ** (1 / w) for w in weights]
+    order = sorted(range(len(items)), key=lambda i: values[i])
+    return [items[i] for i in order[-k:]]
+
+
+def is_valid_address(address: str) -> bool:
+    """
+    Check if the given string is a valid address.
+
+    Args:
+        address (str): The address to be checked.
+
+    Returns:
+        bool: True if the address is valid; False otherwise.
+    """
+    return is_user_address(address) or (
+        len(address) == AGENT_ADDRESS_LENGTH and address.startswith(AGENT_PREFIX)
+    )
+
+
+def parse_identifier(identifier: str) -> Tuple[str, str, str]:
+    """
+    Parse an agent identifier string into prefix, name, and address.
+
+    Args:
+        identifier (str): The identifier string to be parsed.
+
+    Returns:
+        Tuple[str, str, str]: A Tuple containing the prefix, name, and address as strings.
+    """
+
+    prefix = ""
+    name = ""
+    address = ""
+
+    if "://" in identifier:
+        prefix, identifier = identifier.split("://", 1)
+
+    if "/" in identifier:
+        name, identifier = identifier.split("/", 1)
+
+    if is_valid_address(identifier):
+        address = identifier
+    else:
+        name = identifier
+
+    return prefix, name, address

uagents_core-0.1.0/uagents_core/config.py

@@ -0,0 +1,21 @@
+from pydantic import BaseModel
+
+DEFAULT_AGENTVERSE_URL = "agentverse.ai"
+DEFAULT_ALMANAC_API_PATH = "/v1/almanac"
+DEFAULT_REGISTRATION_PATH = "/v1/agents"
+DEFAULT_CHALLENGE_PATH = "/v1/auth/challenge"
+
+DEFAULT_MAX_ENDPOINTS = 10
+
+AGENT_ADDRESS_LENGTH = 65
+AGENT_PREFIX = "agent"
+
+
+class AgentverseConfig(BaseModel):
+    base_url: str = DEFAULT_AGENTVERSE_URL
+    protocol: str = "https"
+    http_prefix: str = "https"
+
+    @property
+    def url(self) -> str:
+        return f"{self.http_prefix}://{self.base_url}"

uagents_core-0.1.0/uagents_core/crypto.py

@@ -0,0 +1,157 @@
+import base64
+import hashlib
+import struct
+from secrets import token_bytes
+from typing import Tuple, Union
+
+import bech32
+import ecdsa
+from ecdsa.util import sigencode_string_canonize
+
+USER_PREFIX = "user"
+SHA_LENGTH = 256
+
+
+def _decode_bech32(value: str) -> Tuple[str, bytes]:
+    prefix, data_base5 = bech32.bech32_decode(value)
+    data = bytes(bech32.convertbits(data_base5, 5, 8, False))
+    return prefix, data
+
+
+def _encode_bech32(prefix: str, value: bytes) -> str:
+    value_base5 = bech32.convertbits(value, 8, 5)
+    return bech32.bech32_encode(prefix, value_base5)
+
+
+def is_user_address(address: str) -> bool:
+    return address[0 : len(USER_PREFIX)] == USER_PREFIX
+
+
+def generate_user_address() -> str:
+    return _encode_bech32(USER_PREFIX, token_bytes(32))
+
+
+def _key_derivation_hash(prefix: str, index: int) -> bytes:
+    hasher = hashlib.sha256()
+    hasher.update(prefix.encode())
+    assert 0 <= index < SHA_LENGTH
+    hasher.update(bytes([index]))
+    return hasher.digest()
+
+
+def _seed_hash(seed: str) -> bytes:
+    hasher = hashlib.sha256()
+    hasher.update(seed.encode())
+    return hasher.digest()
+
+
+def derive_key_from_seed(seed, prefix, index) -> bytes:
+    hasher = hashlib.sha256()
+    hasher.update(_key_derivation_hash(prefix, index))
+    hasher.update(_seed_hash(seed))
+    return hasher.digest()
+
+
+def encode_length_prefixed(value: Union[str, int, bytes]) -> bytes:
+    if isinstance(value, str):
+        encoded = value.encode()
+    elif isinstance(value, int):
+        encoded = struct.pack(">Q", value)
+    elif isinstance(value, bytes):
+        encoded = value
+    else:
+        raise AssertionError()
+
+    length = len(encoded)
+    prefix = struct.pack(">Q", length)
+
+    return prefix + encoded
+
+
+class Identity:
+    """An identity is a cryptographic keypair that can be used to sign messages."""
+
+    def __init__(self, signing_key: ecdsa.SigningKey):
+        """Create a new identity from a signing key."""
+        self._sk = signing_key
+
+        # build the address
+        pub_key_bytes = self._sk.get_verifying_key().to_string(encoding="compressed")
+        self._address = _encode_bech32("agent", pub_key_bytes)
+        self._pub_key = pub_key_bytes.hex()
+
+    @staticmethod
+    def from_seed(seed: str, index: int) -> "Identity":
+        """Create a new identity from a seed and index."""
+        key = derive_key_from_seed(seed, "agent", index)
+        signing_key = ecdsa.SigningKey.from_string(
+            key,
+            curve=ecdsa.SECP256k1,
+            hashfunc=hashlib.sha256,
+        )
+        return Identity(signing_key)
+
+    @staticmethod
+    def generate() -> "Identity":
+        """Generate a random new identity."""
+        signing_key = ecdsa.SigningKey.generate(
+            curve=ecdsa.SECP256k1,
+            hashfunc=hashlib.sha256,
+        )
+        return Identity(signing_key)
+
+    @staticmethod
+    def from_string(private_key_hex: str) -> "Identity":
+        """Create a new identity from a private key."""
+        bytes_key = bytes.fromhex(private_key_hex)
+        signing_key = ecdsa.SigningKey.from_string(
+            bytes_key,
+            curve=ecdsa.SECP256k1,
+            hashfunc=hashlib.sha256,
+        )
+
+        return Identity(signing_key)
+
+    # this is not the real private key but a signing key derived from the private key
+    @property
+    def private_key(self) -> str:
+        """Property to access the private key of the identity."""
+        return self._sk.to_string().hex()
+
+    @property
+    def address(self) -> str:
+        """Property to access the address of the identity."""
+        return self._address
+
+    @property
+    def pub_key(self) -> str:
+        return self._pub_key
+
+    def sign(self, data: bytes) -> str:
+        """Sign the provided data."""
+        return _encode_bech32("sig", self._sk.sign(data))
+
+    def sign_b64(self, data: bytes) -> str:
+        raw_signature = bytes(self._sk.sign(data, sigencode=sigencode_string_canonize))
+        return base64.b64encode(raw_signature).decode()
+
+    def sign_digest(self, digest: bytes) -> str:
+        """Sign the provided digest."""
+        return _encode_bech32("sig", self._sk.sign_digest(digest))
+
+    @staticmethod
+    def verify_digest(address: str, digest: bytes, signature: str) -> bool:
+        """Verify that the signature is correct for the provided signer address and digest."""
+        pk_prefix, pk_data = _decode_bech32(address)
+        sig_prefix, sig_data = _decode_bech32(signature)
+
+        if pk_prefix != "agent":
+            raise ValueError("Unable to decode agent address")
+
+        if sig_prefix != "sig":
+            raise ValueError("Unable to decode signature")
+
+        # build the verifying key
+        verifying_key = ecdsa.VerifyingKey.from_string(pk_data, curve=ecdsa.SECP256k1)
+
+        return verifying_key.verify_digest(sig_data, digest)

uagents_core-0.1.0/uagents_core/envelope.py

@@ -0,0 +1,163 @@
+"""Agent Envelope."""
+
+import base64
+import hashlib
+import struct
+import time
+from typing import List, Optional
+
+from pydantic import (
+    UUID4,
+    BaseModel,
+    Field,
+    field_serializer,
+)
+
+from uagents_core.crypto import Identity
+from uagents_core.types import JsonStr
+
+
+class Envelope(BaseModel):
+    """
+    Represents an envelope for message communication between agents.
+
+    Attributes:
+        version (int): The envelope version.
+        sender (str): The sender's address.
+        target (str): The target's address.
+        session (UUID4): The session UUID that persists for back-and-forth
+        dialogues between agents.
+        schema_digest (str): The schema digest for the enclosed message.
+        protocol_digest (Optional[str]): The digest of the protocol associated with the message
+        (optional).
+        payload (Optional[str]): The encoded message payload of the envelope (optional).
+        expires (Optional[int]): The expiration timestamp (optional).
+        nonce (Optional[int]): The nonce value (optional).
+        signature (Optional[str]): The envelope signature (optional).
+    """
+
+    version: int
+    sender: str
+    target: str
+    session: UUID4
+    schema_digest: str
+    protocol_digest: Optional[str] = None
+    payload: Optional[str] = None
+    expires: Optional[int] = None
+    nonce: Optional[int] = None
+    signature: Optional[str] = None
+
+    def encode_payload(self, value: JsonStr):
+        """
+        Encode the payload value and store it in the envelope.
+
+        Args:
+            value (JsonStr): The payload value to be encoded.
+        """
+        self.payload = base64.b64encode(value.encode()).decode()
+
+    def decode_payload(self) -> str:
+        """
+        Decode and retrieve the payload value from the envelope.
+
+        Returns:
+            str: The decoded payload value, or '' if payload is not present.
+        """
+        if self.payload is None:
+            return ""
+
+        return base64.b64decode(self.payload).decode()
+
+    def sign(self, identity: Identity):
+        """
+        Sign the envelope with the provided identity.
+
+        Args:
+            identity (Identity): The identity to use for signing.
+
+        Raises:
+            ValueError: If the signature cannot be computed.
+        """
+        try:
+            self.signature = identity.sign_digest(self._digest())
+        except Exception as err:
+            raise ValueError(f"Failed to sign envelope: {err}") from err
+
+    def verify(self) -> bool:
+        """
+        Verify the envelope's signature.
+
+        Returns:
+            bool: True if the signature is valid.
+
+        Raises:
+            ValueError: If the signature is missing.
+            ecdsa.BadSignatureError: If the signature is invalid.
+        """
+        if self.signature is None:
+            raise ValueError("Envelope signature is missing")
+        return Identity.verify_digest(self.sender, self._digest(), self.signature)
+
+    def _digest(self) -> bytes:
+        """
+        Compute the digest of the envelope's content.
+
+        Returns:
+            bytes: The computed digest.
+        """
+        hasher = hashlib.sha256()
+        hasher.update(self.sender.encode())
+        hasher.update(self.target.encode())
+        hasher.update(str(self.session).encode())
+        hasher.update(self.schema_digest.encode())
+        if self.payload is not None:
+            hasher.update(self.payload.encode())
+        if self.expires is not None:
+            hasher.update(struct.pack(">Q", self.expires))
+        if self.nonce is not None:
+            hasher.update(struct.pack(">Q", self.nonce))
+        return hasher.digest()
+
+
+class EnvelopeHistoryEntry(BaseModel):
+    timestamp: int = Field(default_factory=lambda: int(time.time()))
+    version: int
+    sender: str
+    target: str
+    session: UUID4
+    schema_digest: str
+    protocol_digest: Optional[str] = None
+    payload: Optional[str] = None
+
+    @field_serializer("session")
+    def serialize_session(self, session: UUID4, _info):
+        return str(session)
+
+    @classmethod
+    def from_envelope(cls, envelope: Envelope):
+        return cls(
+            version=envelope.version,
+            sender=envelope.sender,
+            target=envelope.target,
+            session=envelope.session,
+            schema_digest=envelope.schema_digest,
+            protocol_digest=envelope.protocol_digest,
+            payload=envelope.decode_payload(),
+        )
+
+
+class EnvelopeHistory(BaseModel):
+    envelopes: List[EnvelopeHistoryEntry]
+
+    def add_entry(self, entry: EnvelopeHistoryEntry):
+        self.envelopes.append(entry)
+        self.apply_retention_policy()
+
+    def apply_retention_policy(self):
+        """Remove entries older than 24 hours"""
+        cutoff_time = time.time() - 86400
+        for e in self.envelopes:
+            if e.timestamp < cutoff_time:
+                self.envelopes.remove(e)
+            else:
+                break

uagents_core-0.1.0/uagents_core/logger.py

@@ -0,0 +1,37 @@
+import logging
+import os
+
+import structlog
+
+_log_level_map = {
+    "NOTSET": logging.NOTSET,
+    "DEBUG": logging.DEBUG,
+    "INFO": logging.INFO,
+    "WARNING": logging.WARNING,
+    "ERROR": logging.ERROR,
+    "CRITICAL": logging.CRITICAL,
+}
+
+_log_level = os.getenv("LOG_LEVEL", "INFO")
+
+
+structlog.configure(
+    processors=[
+        structlog.contextvars.merge_contextvars,
+        structlog.processors.add_log_level,
+        structlog.processors.StackInfoRenderer(),
+        structlog.dev.set_exc_info,
+        structlog.processors.TimeStamper(fmt="%Y-%m-%d %H:%M:%S", utc=False),
+        structlog.dev.ConsoleRenderer(),
+    ],
+    wrapper_class=structlog.make_filtering_bound_logger(
+        _log_level_map.get(_log_level, logging.INFO)
+    ),
+    context_class=dict,
+    logger_factory=structlog.PrintLoggerFactory(),
+    cache_logger_on_first_use=False,
+)
+
+
+def get_logger(logger_name: str):
+    return structlog.get_logger(logger_name)

uagents_core-0.1.0/uagents_core/models.py

@@ -0,0 +1,38 @@
+import hashlib
+from typing import Any, Dict, Type, Union
+
+from pydantic.v1 import BaseModel, Field  # noqa
+
+
+# reverting back to pydantic v1 BaseModel for backwards compatibility
+class Model(BaseModel):
+    @classmethod
+    def model_json_schema(cls) -> str:
+        return cls.schema_json()
+
+    def model_dump_json(self) -> str:
+        return self.json()
+
+    def model_dump(self) -> Dict[str, Any]:
+        return self.dict()
+
+    @classmethod
+    def model_validate_json(cls, obj: Any) -> "Model":
+        return cls.parse_raw(obj)
+
+    @classmethod
+    def model_validate(cls, obj: Union[Dict[str, Any], "Model"]) -> "Model":
+        return cls.parse_obj(obj)
+
+    @staticmethod
+    def build_schema_digest(model: Union["Model", Type["Model"]]) -> str:
+        schema = model.schema_json(indent=None, sort_keys=True)
+        digest = hashlib.sha256(schema.encode("utf8")).digest().hex()
+
+        return f"model:{digest}"
+
+
+class ErrorMessage(Model):
+    """Error message model"""
+
+    error: str

uagents_core-0.1.0/uagents_core/registration.py

@@ -0,0 +1,78 @@
+import hashlib
+import json
+import time
+from typing import Dict, List, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from uagents_core.crypto import Identity
+from uagents_core.types import AddressPrefix, AgentEndpoint, AgentType
+from uagents_core.utils.communication import parse_identifier
+
+
+class VerifiableModel(BaseModel):
+    agent_identifier: str
+    signature: Optional[str] = None
+    timestamp: Optional[int] = None
+
+    def sign(self, identity: Identity):
+        self.timestamp = int(time.time())
+        digest = self._build_digest()
+        self.signature = identity.sign_digest(digest)
+
+    def verify(self) -> bool:
+        _, _, agent_address = parse_identifier(self.agent_identifier)
+        return self.signature is not None and Identity.verify_digest(
+            agent_address, self._build_digest(), self.signature
+        )
+
+    def _build_digest(self) -> bytes:
+        sha256 = hashlib.sha256()
+        sha256.update(
+            json.dumps(
+                self.model_dump(exclude={"signature"}),
+                sort_keys=True,
+                separators=(",", ":"),
+            ).encode("utf-8")
+        )
+        return sha256.digest()
+
+
+class AgentRegistrationAttestation(VerifiableModel):
+    protocols: List[str]
+    endpoints: List[AgentEndpoint]
+    metadata: Optional[Dict[str, Union[str, Dict[str, str]]]] = None
+
+
+class RegistrationRequest(BaseModel):
+    address: str
+    prefix: Optional[AddressPrefix] = "test-agent"
+    challenge: str
+    challenge_response: str
+    agent_type: AgentType
+    endpoint: Optional[str] = None
+
+
+class AgentverseConnectRequest(BaseModel):
+    user_token: str
+    agent_type: AgentType
+    endpoint: Optional[str] = None
+
+
+class RegistrationResponse(BaseModel):
+    success: bool
+
+
+class ChallengeRequest(BaseModel):
+    address: str
+
+
+class ChallengeResponse(BaseModel):
+    challenge: str
+
+
+class AgentUpdates(BaseModel):
+    name: str = Field(min_length=1, max_length=80)
+    readme: Optional[str] = Field(default=None, max_length=80000)
+    avatar_url: Optional[str] = Field(default=None, max_length=4000)
+    agent_type: Optional[AgentType] = "custom"

uagents_core-0.1.0/uagents_core/types.py

@@ -0,0 +1,14 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+JsonStr = str
+
+AgentType = Literal["mailbox", "proxy", "custom"]
+
+AddressPrefix = Literal["agent", "test-agent"]
+
+
+class AgentEndpoint(BaseModel):
+    url: str
+    weight: int

uagents_core-0.1.0/uagents_core/utils/communication.py

@@ -0,0 +1,130 @@
+import json
+import urllib.parse
+from typing import Any, List, Optional
+from uuid import UUID, uuid4
+
+import requests
+
+from uagents_core.communication import parse_identifier, weighted_random_sample
+from uagents_core.config import (
+    DEFAULT_ALMANAC_API_PATH,
+    DEFAULT_MAX_ENDPOINTS,
+    AgentverseConfig,
+)
+from uagents_core.crypto import Identity
+from uagents_core.envelope import Envelope
+from uagents_core.logger import get_logger
+
+logger = get_logger("uagents_core.utils.communication")
+
+
+def lookup_endpoint_for_agent(
+    agent_identifier: str,
+    *,
+    max_endpoints: int = DEFAULT_MAX_ENDPOINTS,
+    agentverse_config: Optional[AgentverseConfig] = None,
+) -> List[str]:
+    """
+    Look up the endpoints for an agent using the Almanac API.
+
+    Args:
+        destination (str): The destination address to look up.
+
+    Returns:
+        List[str]: The endpoint(s) for the agent.
+    """
+    _, _, agent_address = parse_identifier(agent_identifier)
+
+    agentverse_config = agentverse_config or AgentverseConfig()
+    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
+
+    request_meta: dict[str, Any] = {
+        "agent_address": agent_address,
+        "lookup_url": almanac_api,
+    }
+    logger.debug("looking up endpoint for agent", extra=request_meta)
+    r = requests.get(f"{almanac_api}/agents/{agent_address}")
+    r.raise_for_status()
+
+    request_meta["response_status"] = r.status_code
+    logger.info(
+        "Got response looking up agent endpoint",
+        extra=request_meta,
+    )
+
+    endpoints = r.json().get("endpoints", [])
+
+    if len(endpoints) > 0:
+        endpoints = [val.get("url") for val in endpoints]
+        weights = [val.get("weight") for val in endpoints]
+        return weighted_random_sample(
+            endpoints,
+            weights=weights,
+            k=min(max_endpoints, len(endpoints)),
+        )
+
+    return []
+
+
+def send_message(
+    destination: str,
+    message_schema_digest: str,
+    message_body: Any,
+    sender: Identity,
+    *,
+    session_id: Optional[UUID] = None,
+    protocol_digest: Optional[str] = None,
+    agentverse_config: Optional[AgentverseConfig] = None,
+):
+    """
+    Send a message (dict) to an agent.
+
+    Args:
+        destination (str): The address of the target agent.
+        message_schema_digest (str): The digest of the model that is being used
+        message_body (Any): The payload of the message.
+        sender (Identity): The identity of the sender.
+        session (UUID): The unique identifier for the dialogue between two agents
+        protocol_digest (str): The digest of the protocol that is being used
+        agentverse_config (AgentverseConfig): The configuration for the agentverse API
+    Returns:
+        None
+    """
+    json_payload = json.dumps(message_body, separators=(",", ":"))
+
+    env = Envelope(
+        version=1,
+        sender=sender.address,
+        target=destination,
+        session=session_id or uuid4(),
+        schema_digest=message_schema_digest,
+        protocol_digest=protocol_digest,
+    )
+
+    env.encode_payload(json_payload)
+    env.sign(sender)
+
+    logger.debug("Sending message to agent", extra={"envelope": env.model_dump()})
+
+    # query the almanac to lookup the destination agent
+    agentverse_config = agentverse_config or AgentverseConfig()
+    endpoints = lookup_endpoint_for_agent(
+        destination, agentverse_config=agentverse_config
+    )
+
+    if len(endpoints) == 0:
+        logger.error(
+            "No endpoints found for agent", extra={"agent_address": destination}
+        )
+        return
+
+    # send the envelope to the destination agent
+    request_meta = {"agent_address": destination, "agent_endpoint": endpoints[0]}
+    logger.debug("Sending message to agent", extra=request_meta)
+    r = requests.post(
+        endpoints[0],
+        headers={"content-type": "application/json"},
+        data=env.model_dump_json(),
+    )
+    r.raise_for_status()
+    logger.info("Sent message to agent", extra=request_meta)

uagents_core-0.1.0/uagents_core/utils/registration.py

@@ -0,0 +1,224 @@
+import urllib.parse
+from typing import List, Optional
+
+import requests
+
+from uagents_core.config import (
+    DEFAULT_ALMANAC_API_PATH,
+    DEFAULT_CHALLENGE_PATH,
+    DEFAULT_REGISTRATION_PATH,
+    AgentverseConfig,
+)
+from uagents_core.crypto import Identity
+from uagents_core.logger import get_logger
+from uagents_core.registration import (
+    AgentRegistrationAttestation,
+    AgentUpdates,
+    AgentverseConnectRequest,
+    ChallengeRequest,
+    ChallengeResponse,
+    RegistrationRequest,
+    RegistrationResponse,
+)
+from uagents_core.types import AgentEndpoint
+
+logger = get_logger("uagents_core.utils.registration")
+
+
+def register_in_almanac(
+    request: AgentverseConnectRequest,
+    identity: Identity,
+    *,
+    protocol_digests: List[str],
+    agentverse_config: Optional[AgentverseConfig] = None,
+):
+    """
+    Register the agent with the Almanac API.
+
+    Args:
+        request (AgentverseConnectRequest): The request containing the agent details.
+        identity (Identity): The identity of the agent.
+        protocol_digest (List[str]): The digest of the protocol that the agent supports
+        agentverse_config (AgentverseConfig): The configuration for the agentverse API
+    """
+
+    # get the almanac API endpoint
+    agentverse_config = agentverse_config or AgentverseConfig()
+    almanac_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_ALMANAC_API_PATH)
+
+    # get the agent address
+    agent_address = identity.address
+
+    registration_metadata = {
+        "almanac_endpoint": almanac_api,
+        "agent_address": agent_address,
+        "agent_endpoint": request.endpoint or "",
+        "protocol_digest": ",".join(protocol_digests),
+    }
+    if request.endpoint is None:
+        if request.agent_type == "mailbox":
+            request.endpoint = f"{agentverse_config.url}/v1/submit"
+        elif request.agent_type == "proxy":
+            request.endpoint = f"{agentverse_config.url}/v1/proxy/submit"
+
+    if request.endpoint is None:
+        logger.warning(
+            "No endpoint provided for agent registration",
+            extra=registration_metadata,
+        )
+        return
+
+    logger.info(
+        "Registering with Almanac API",
+        extra=registration_metadata,
+    )
+
+    # create the attestation
+    attestation = AgentRegistrationAttestation(
+        agent_identifier=agent_address,
+        protocols=protocol_digests,
+        endpoints=[
+            AgentEndpoint(url=request.endpoint, weight=1),
+        ],
+        metadata=None,
+    )
+
+    # sign the attestation
+    attestation.sign(identity)
+
+    # submit the attestation to the API
+    r = requests.post(
+        f"{almanac_api}/agents",
+        headers={"content-type": "application/json"},
+        data=attestation.model_dump_json(),
+    )
+    r.raise_for_status()
+    logger.debug(
+        "Agent attestation submitted",
+        extra=registration_metadata,
+    )
+
+
+def register_in_agentverse(
+    request: AgentverseConnectRequest,
+    identity: Identity,
+    agent_details: Optional[AgentUpdates] = None,
+    *,
+    agentverse_config: Optional[AgentverseConfig] = None,
+):
+    """
+    Register the agent with the Agentverse API.
+
+    Args:
+        request (AgentverseConnectRequest): The request containing the agent details.
+        identity (Identity): The identity of the agent.
+        agent_details (Optional[AgentUpdates]): The agent details to update.
+        agentverse_config (AgentverseConfig): The configuration for the agentverse API
+    Returns:
+        None
+    """
+
+    # API endpoints
+    agentverse_config = agentverse_config or AgentverseConfig()
+    registration_api = urllib.parse.urljoin(
+        agentverse_config.url, DEFAULT_REGISTRATION_PATH
+    )
+    challenge_api = urllib.parse.urljoin(agentverse_config.url, DEFAULT_CHALLENGE_PATH)
+
+    # get the agent address
+    agent_address = identity.address
+
+    registration_metadata = {
+        "registration_api": registration_api,
+        "challenge_api": challenge_api,
+        "agent_address": agent_address,
+        "agent_endpoint": request.endpoint or "",
+        "agent_type": request.agent_type,
+        "agent_name": agent_details.name if agent_details else "",
+    }
+
+    # check to see if the agent exists
+    r = requests.get(
+        f"{registration_api}/{agent_address}",
+        headers={
+            "content-type": "application/json",
+            "authorization": f"Bearer {request.user_token}",
+        },
+    )
+
+    # if it doesn't then create it
+    if r.status_code == 404:
+        logger.debug(
+            "Agent did not exist on agentverse; registering it",
+            extra=registration_metadata,
+        )
+
+        challenge_request = ChallengeRequest(address=identity.address)
+        logger.debug(
+            "Requesting mailbox access challenge",
+            extra=registration_metadata,
+        )
+        r = requests.post(
+            challenge_api,
+            data=challenge_request.model_dump_json(),
+            headers={
+                "content-type": "application/json",
+                "Authorization": f"Bearer {request.user_token}",
+            },
+        )
+        r.raise_for_status()
+        challenge = ChallengeResponse.model_validate_json(r.text)
+        registration_payload = RegistrationRequest(
+            address=identity.address,
+            challenge=challenge.challenge,
+            challenge_response=identity.sign(challenge.challenge.encode()),
+            endpoint=request.endpoint,
+            agent_type=request.agent_type,
+        ).model_dump_json()
+        r = requests.post(
+            registration_api,
+            headers={
+                "content-type": "application/json",
+                "authorization": f"Bearer {request.user_token}",
+            },
+            data=registration_payload,
+        )
+        if r.status_code == 409:
+            logger.info(
+                "Agent already registered with Agentverse",
+                extra=registration_metadata,
+            )
+        else:
+            r.raise_for_status()
+            registration_response = RegistrationResponse.model_validate_json(r.text)
+            if registration_response.success:
+                logger.info(
+                    f"Successfully registered as {request.agent_type} agent in Agentverse",
+                    extra=registration_metadata,
+                )
+    if not agent_details:
+        logger.debug(
+            "No agent details provided; skipping agent update",
+            extra=registration_metadata,
+        )
+        return
+
+    # update the readme and the title of the agent to make it easier to find
+    logger.debug(
+        "Registering agent title and readme with Agentverse",
+        extra=registration_metadata,
+    )
+    update = AgentUpdates(name=agent_details.name, readme=agent_details.readme)
+    r = requests.put(
+        f"{registration_api}/{agent_address}",
+        headers={
+            "content-type": "application/json",
+            "authorization": f"Bearer {request.user_token}",
+        },
+        data=update.model_dump_json(),
+    )
+    r.raise_for_status()
+    logger.info(
+        "Completed registering agent with Agentverse",
+        extra=registration_metadata,
+    )