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()andregister_agent()raiseAgentverseRequestErroron 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_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
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, banner, starter prompts) |
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.
Metadata
Release files for uagents-core 0.4.12
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| uagents_core-0.4.12.tar.gz | 120.2 kB | Without provenance | Details for uagents_core-0.4.12.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uagents_core-0.4.12-py3-none-any.whl | Python 3 | none | any | Details for uagents_core-0.4.12-py3-none-any.whl |
Total release size: 173.9 kB
Release files / uagents_core-0.4.12.tar.gz
| Download URL | uagents_core-0.4.12.tar.gz |
|---|---|
| Size | 120.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
f2c1495cb93476455a70a4c8117d36c3d84b4c6b439e1e3f60fdc520ac110cf9
|
|
BLAKE2b-256 checksum How to use checksums |
b6d88da47337ef2c81a9a7f3d0eb55a4b6029e2d5086deaa1b9eb1507edc4534
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / uagents_core-0.4.12-py3-none-any.whl
| Download URL | uagents_core-0.4.12-py3-none-any.whl |
|---|---|
| Size | 53.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
345375122b5ed11cb17b50fd3787e70dc716e6d333b12aaf9563da910bf13a6a
|
|
BLAKE2b-256 checksum How to use checksums |
0d3fb2a2d130ba0d66cb61b61c1c86512903c913f9bbdb31e45c994f695d8a17
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.0 {"installer":{"name":"uv","version":"0.13.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for uagents-core 0.4.12
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.