Core definitions and functionalities for building agents that interact with the Fetch.ai ecosystem and Agentverse marketplace.
pip install uagents-corefrom 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}")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
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")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| 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()andregister_agent()raiseAgentverseRequestErroron failure. Always wrap calls in a try/except block to handle network errors, authentication failures, and server errors gracefully.
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_excattribute 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| 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 |
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-handleSee UPGRADING.md for migration guides between versions.
- uagents - Full agent framework with decorators and runtime
- uagents-adapter - Adapters for LangChain, CrewAI, MCP
Apache 2.0 - See LICENSE for details.