Metadata-Version: 2.4
Name: uagents-core
Version: 0.4.5b1
Summary: Core components for agent based systems
Project-URL: homepage, https://fetch.ai
Project-URL: repository, https://github.com/fetchai/uAgents
Project-URL: documentation, https://fetch.ai/docs
Author-email: 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>, Devon Bleibtrey <devon.bleibtrey@flockx.io>
License: Apache 2.0
Requires-Python: <4.0,>=3.10
Requires-Dist: bech32<2.0,>=1.2.0
Requires-Dist: ecdsa<1.0,>=0.19.0
Requires-Dist: httpx<0.29.0,>=0.28.1
Requires-Dist: pydantic<3.0,>=2.8
Requires-Dist: requests<3.0,>=2.32.3
Provides-Extra: a2a
Requires-Dist: a2a-sdk<0.4.0,>=0.3.20; extra == 'a2a'
Provides-Extra: langgraph
Requires-Dist: httpx<0.29.0,>=0.28.1; (python_version >= '3.11') and extra == 'langgraph'
Requires-Dist: langgraph-api<1.0,>=0.2.0; (python_version >= '3.11') and extra == 'langgraph'
Requires-Dist: langgraph-cli<1.0,>=0.4.0; (python_version >= '3.11') and extra == 'langgraph'
Requires-Dist: python-dotenv<2.0,>=1.0.0; (python_version >= '3.11') and extra == 'langgraph'
Requires-Dist: starlette<1.0,>=0.37.0; (python_version >= '3.11') and extra == 'langgraph'
Description-Content-Type: text/markdown

# uAgents-Core

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

## Installation

```bash
pip install uagents-core
```

## Quick Start

### Register a Chat Agent with Agentverse

```python
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:

```python
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

```python
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

```python
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.

```bash
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](../docs/UPGRADING.md) for migration guides between versions.

## Related Packages

- **[uagents](https://pypi.org/project/uagents/)** - Full agent framework with decorators and runtime
- **[uagents-adapter](../uagents-adapter/)** - Adapters for LangChain, CrewAI, MCP

## License

Apache 2.0 - See [LICENSE](../../LICENSE) for details.
