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

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

av CLI

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

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.