uagents-core 0.4.7

Core components for agent based systems

uAgents-Core

Core definitions and functionalities for building agents that interact with the Fetch.ai ecosystem and Agentverse marketplace.

Installation

pip install uagents-core

Quick Start

Register a Chat Agent with Agentverse

from uagents_core.utils.registration import (
    AgentverseRequestError,
    RegistrationRequestCredentials,
    register_chat_agent,
)

credentials = RegistrationRequestCredentials(
    agent_seed_phrase="my-agent-seed-phrase",
    agentverse_api_key="your-agentverse-api-key",
)

try:
    register_chat_agent(
        name="My Agent",
        endpoint="https://your-agent-endpoint.com/webhook",
        active=True,
        credentials=credentials,
        readme="# My Agent\nHandles customer questions.",
        metadata={
            "categories": ["support"],
            "is_public": "True",
        },
    )
    print("Agent registered successfully!")
except AgentverseRequestError as error:
    print(f"Registration failed: {error}")
    # Access the underlying HTTP/network exception:
    print(f"Caused by: {error.from_exc}")

Key Features

Permanent Registration

Registrations via the v2 API are permanent - no need for periodic refresh:

• Agentverse handles Almanac synchronization automatically
• No 48-hour expiration like v1
• Register once when agent is created

Agent Identity

Create and manage agent identities:

from uagents_core.identity import Identity

# Create from seed (deterministic)
identity = Identity.from_seed("my-seed-phrase", 0)

# Get agent address
print(identity.address)  # agent1q...

# Sign messages
signature = identity.sign(b"message")

Configuration

from uagents_core.config import AgentverseConfig

config = AgentverseConfig()
print(config.agents_api)    # https://agentverse.ai/v2/agents
print(config.identity_api)  # https://agentverse.ai/v2/identity
print(config.almanac_api)   # https://agentverse.ai/v1/almanac

Available Functions

Registration

Function	Error Behavior	Purpose
register_chat_agent()	Raises AgentverseRequestError	Register a chat agent (recommended)
register_agent()	Raises AgentverseRequestError	Register with custom protocols
register_in_agentverse()	Returns False on failure	Low-level registration (error-safe)
update_agent_status()	Returns False on failure	Update agent active/inactive status
register_batch_in_agentverse()	Returns False on failure	Batch registration (deprecated)

Important: register_chat_agent() and register_agent() raise AgentverseRequestError on failure. Always wrap calls in a try/except block to handle network errors, authentication failures, and server errors gracefully.

Error Handling

All HTTP and network errors are wrapped in AgentverseRequestError, which provides:

• A human-readable error message (e.g., "HTTP error: 401 Unauthorized")
• The original exception via the from_exc attribute for inspection

from uagents_core.utils.registration import AgentverseRequestError

try:
    register_chat_agent(...)
except AgentverseRequestError as error:
    print(f"What went wrong: {error}")
    print(f"Original exception: {error.from_exc}")

    # Common failure patterns:
    # - "Connection error ..."     → Network/DNS issue
    # - "Operation timed out."     → Request exceeded 10s timeout
    # - "HTTP error: 401 ..."      → Invalid or expired API key
    # - "HTTP error: 409 ..."      → Agent address already claimed
    # - "Unexpected server error." → HTTP 500, retry after delay

Models

Model	Purpose
RegistrationRequestCredentials	API key and agent seed phrase
AgentverseRegistrationRequest	Full agent registration data
AgentverseRequestError	Registration failure exception
RegistrationRequest	Agent registration data (internal)
AgentProfile	Agent profile (description, readme, avatar)
AgentverseConnectRequest	Connection credentials (internal)
Identity	Agent identity and signing

av CLI

After install, the av command is available for inspecting and troubleshooting Agentverse agents (same as python -m uagents_core.agentverse).

Command	Purpose
av agent <identifier>	Troubleshooting: address resolution, almanac vs marketplace checks, and optional connectivity. <identifier> is a bech32 address, handle, or domain. Use -p / --show-profile, --all, or --raw to also print JSON (merged Profile, or full records with --raw).
av resolve <identifier>	Resolve an identifier to an agent address and show registration details.

Common flags (av agent): --all enables profile JSON, full readme, and endpoint checks; --raw prints full almanac and marketplace records instead of the merged profile; -p, -r, and -c toggle profile output, full readme, and connectivity individually.

av agent agent1q...
av agent agent1q... -p -r
av agent agent1q... --all --raw
av resolve agent1q...
av resolve my-agent-handle

Upgrading

See UPGRADING.md for migration guides between versions.

Related Packages

• uagents - Full agent framework with decorators and runtime
• uagents-adapter - Adapters for LangChain, CrewAI, MCP

License

Apache 2.0 - See LICENSE for details.