# Crypto.com Agent Client
**Crypto.com Agent Client** is a Python library designed to integrate advanced conversational AI capabilities with blockchain functionality. It provides tools, plugins, and utilities to build robust and extensible agent workflows with graphs and Crypto.com blockchain integrations.
---
## Features
1. **Conversational AI Integration**:
- Build conversational agents with state-of-the-art Large Language Models (LLMs) like OpenAI's GPT series.
- Customize the behavior using plugins for personality and instructions.
2. **Blockchain Integration**:
- Perform blockchain-specific operations with pre-built functions:
- Create wallets.
- Retrieve native and ERC20 token balances.
- Fetch transactions by hash.
- Transfer tokens.
3. **Extensible Tools**:
- Extend agent functionality with custom user-defined tools.
- Simple decorator-based implementation using `@tool`.
4. **Persistent Storage**:
- Use `SQLitePlugin` for local state persistence.
- Seamlessly store and retrieve agent states.
5. **LangFuse Monitoring**:
- Integrate with LangFuse for real-time telemetry and interaction monitoring.
- Enable detailed analytics for agent performance and usage.
6. **Plugin System**:
- Flexible plugin configuration for tools, storage, personality, and telemetry.
- Easily swap or extend functionality without modifying core logic.
7. **Custom Instructions**:
- Tailor agent responses using flexible instructions.
- Combine personality settings for tone, verbosity, and language.
8. **Easy Initialization**:
- Initialize with a few lines of code, including blockchain, LLM, and plugin configurations.
- Minimal setup for out-of-the-box functionality.
---
## Installation
Install the package from PyPI:
```bash
pip install cryptocom-agent-client
```
---
## Getting Started
### Importing the Library
The library exposes key components at the top level for ease of use.
```python
from cryptocom_agent_client import Agent, tool, SQLitePlugin
```
---
## Core Components
### Agent
The `Agent` class is the central component that orchestrates interactions, tools, and plugins. It is initialized with configurations for LLM, blockchain, and optional plugins.
#### Example Initialization
```python
from cryptocom_agent_client import Agent, tool
# Define a custom tool
@tool
def get_weather(location: str) -> str:
"""
Provide the current weather for a given location.
Args:
location (str): The name of the location for which to retrieve weather information.
Returns:
str: A message describing the weather in the specified location.
"""
return f"The weather in {location} is sunny."
openai_api_key = os.getenv("OPENAI_API_KEY")
explorer_api_key = os.getenv("EXPLORER_API_KEY")
private_key = os.getenv("PRIVATE_KEY")
# Initialize the agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": openai_api_key,
},
blockchain_config={
"chainId": "240",
"explorer-api-key": explorer_api_key,
"private-key": private_key,
},
plugins={
"personality": {
"tone": "friendly",
"language": "English",
"verbosity": "high",
},
"instructions": "You are a humorous assistant that always includes a joke in your responses.",
"tools": [get_weather],
"storage": SQLitePlugin(db_path="agent_state.db"), # (OPTIONAL)
"langfuse": {
"public-key": "user-public-key",
"secret-key": "user-secret-key",
"host": "https://langfuse.example.com",
}, # (OPTIONAL)
},
)
# Interaction
response = agent.interact("What's the weather in Berlin?")
print(response)
```
---
## Plugins
Plugins allow you to extend the functionality of the agent. Below are the available plugins and examples of their usage.
### Storage Plugin
The `SQLitePlugin` provides a mechanism for state persistence using SQLite.
#### Example Usage
```python
from cryptocom_agent_client import Agent, SQLitePlugin
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
plugins={
"storage": SQLitePlugin(db_path="agent_state.db")
},
)
```
### LangFuse Plugin
The `LangFusePlugin` integrates telemetry for monitoring interactions. Provide the required keys as a dictionary:
#### Example Usage
```python
from cryptocom_agent_client import Agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
plugins={
"langfuse": {
"public-key": "user-public-key",
"secret-key": "user-secret-key",
"host": "https://langfuse.example.com",
}
},
)
```
### Personality Plugin
Customize the agent's personality and instructions.
#### Example Usage
```python
from cryptocom_agent_client import Agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
plugins={
"personality": {
"tone": "friendly",
"language": "English",
"verbosity": "high",
},
},
)
```
---
## Tools
Tools are user-defined functions that extend the agent's capabilities. They must be decorated with `@tool`.
### Example Tools
#### 1. Weather Tool
```python
@tool
def get_weather(location: str) -> str:
"""
Provide the current weather for a given location.
Args:
location (str): The name of the location for which to retrieve weather information.
Returns:
str: A message describing the weather in the specified location.
"""
return f"The weather in {location} is sunny."
```
#### 2. Custom Greeting Tool
```python
@tool
def greet_user(name: str) -> str:
"""
Generate a personalized greeting message.
Args:
name (str): The name of the user to greet.
Returns:
str: A greeting message addressed to the user.
"""
return f"Hello, {name}! How can I assist you today?"
```
#### 3. Arithmetic Tool
```python
@tool
def calculate_sum(a: int, b: int) -> int:
"""
Calculate the sum of two integers.
Args:
a (int): The first number to add.
b (int): The second number to add.
Returns:
int: The sum of the two numbers.
"""
return a + b
```
### Using Tools in the Agent
```python
from cryptocom_agent_client import Agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
plugins={
"tools": [get_weather, greet_user, calculate_sum],
},
)
response = agent.interact("What's the weather in Berlin?")
print(response)
```
---
## Blockchain Functions
The library includes several pre-built blockchain-related functions:
### Pre-Built Functions
1. **Create Wallet**: `create_wallet()`
2. **Get Native Balance**: `get_native_balance(address: str)`
3. **Get ERC20 Balance**: `get_erc20_balance(address: str, token: str)`
4. **Get Transaction by Hash**: `get_transaction_by_hash(tx_hash: str)`
5. **Transfer Token**: `transfer_token(from_address: str, to_address: str, amount: int, token: str)`
### Example Usage
```python
from cryptocom_agent_client import Agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
)
response = agent.interact("Create 2 Wallets")
print(response)
```
---
## Advanced Usage
### Custom Instructions
Customize agent behavior by modifying instructions:
```python
from cryptocom_agent_client import Agent
agent = Agent.init(
llm_config={
"provider": "OpenAI",
"model": "gpt-4",
"provider-api-key": "sk-proj-example-key",
},
blockchain_config={
"chainId": "240",
"explorer-api-key": "blockchain-example-key",
},
plugins={
"instructions": "Be concise and professional."
},
)
```
---
## Contributing
We welcome contributions! Please follow the guidelines in the repository.
---
## License
This project is licensed under the MIT License. See the LICENSE file for details.
Raw data
{
"_id": null,
"home_page": null,
"name": "cryptocom-agent-client",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0.0,>=3.9",
"maintainer_email": null,
"keywords": "blockchain, crypto.com, AI, tool, SDK",
"author": "Ric Arcifa",
"author_email": "ricardo.arcifa@crypto.com",
"download_url": null,
"platform": null,
"description": "# Crypto.com Agent Client\n\n**Crypto.com Agent Client** is a Python library designed to integrate advanced conversational AI capabilities with blockchain functionality. It provides tools, plugins, and utilities to build robust and extensible agent workflows with graphs and Crypto.com blockchain integrations.\n\n---\n\n## Features\n\n1. **Conversational AI Integration**:\n\n - Build conversational agents with state-of-the-art Large Language Models (LLMs) like OpenAI's GPT series.\n - Customize the behavior using plugins for personality and instructions.\n\n2. **Blockchain Integration**:\n\n - Perform blockchain-specific operations with pre-built functions:\n - Create wallets.\n - Retrieve native and ERC20 token balances.\n - Fetch transactions by hash.\n - Transfer tokens.\n\n3. **Extensible Tools**:\n\n - Extend agent functionality with custom user-defined tools.\n - Simple decorator-based implementation using `@tool`.\n\n4. **Persistent Storage**:\n\n - Use `SQLitePlugin` for local state persistence.\n - Seamlessly store and retrieve agent states.\n\n5. **LangFuse Monitoring**:\n\n - Integrate with LangFuse for real-time telemetry and interaction monitoring.\n - Enable detailed analytics for agent performance and usage.\n\n6. **Plugin System**:\n\n - Flexible plugin configuration for tools, storage, personality, and telemetry.\n - Easily swap or extend functionality without modifying core logic.\n\n7. **Custom Instructions**:\n\n - Tailor agent responses using flexible instructions.\n - Combine personality settings for tone, verbosity, and language.\n\n8. **Easy Initialization**:\n - Initialize with a few lines of code, including blockchain, LLM, and plugin configurations.\n - Minimal setup for out-of-the-box functionality.\n\n---\n\n## Installation\n\nInstall the package from PyPI:\n\n```bash\npip install cryptocom-agent-client\n```\n\n---\n\n## Getting Started\n\n### Importing the Library\n\nThe library exposes key components at the top level for ease of use.\n\n```python\nfrom cryptocom_agent_client import Agent, tool, SQLitePlugin\n```\n\n---\n\n## Core Components\n\n### Agent\n\nThe `Agent` class is the central component that orchestrates interactions, tools, and plugins. It is initialized with configurations for LLM, blockchain, and optional plugins.\n\n#### Example Initialization\n\n```python\nfrom cryptocom_agent_client import Agent, tool\n\n# Define a custom tool\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"\n Provide the current weather for a given location.\n\n Args:\n location (str): The name of the location for which to retrieve weather information.\n\n Returns:\n str: A message describing the weather in the specified location.\n \"\"\"\n return f\"The weather in {location} is sunny.\"\n\nopenai_api_key = os.getenv(\"OPENAI_API_KEY\")\nexplorer_api_key = os.getenv(\"EXPLORER_API_KEY\")\nprivate_key = os.getenv(\"PRIVATE_KEY\")\n\n# Initialize the agent\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": openai_api_key,\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": explorer_api_key,\n \"private-key\": private_key,\n },\n plugins={\n \"personality\": {\n \"tone\": \"friendly\",\n \"language\": \"English\",\n \"verbosity\": \"high\",\n },\n \"instructions\": \"You are a humorous assistant that always includes a joke in your responses.\",\n \"tools\": [get_weather],\n \"storage\": SQLitePlugin(db_path=\"agent_state.db\"), # (OPTIONAL)\n \"langfuse\": {\n \"public-key\": \"user-public-key\",\n \"secret-key\": \"user-secret-key\",\n \"host\": \"https://langfuse.example.com\",\n }, # (OPTIONAL)\n },\n)\n\n# Interaction\nresponse = agent.interact(\"What's the weather in Berlin?\")\nprint(response)\n```\n\n---\n\n## Plugins\n\nPlugins allow you to extend the functionality of the agent. Below are the available plugins and examples of their usage.\n\n### Storage Plugin\n\nThe `SQLitePlugin` provides a mechanism for state persistence using SQLite.\n\n#### Example Usage\n\n```python\nfrom cryptocom_agent_client import Agent, SQLitePlugin\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n plugins={\n \"storage\": SQLitePlugin(db_path=\"agent_state.db\")\n },\n)\n```\n\n### LangFuse Plugin\n\nThe `LangFusePlugin` integrates telemetry for monitoring interactions. Provide the required keys as a dictionary:\n\n#### Example Usage\n\n```python\nfrom cryptocom_agent_client import Agent\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n plugins={\n \"langfuse\": {\n \"public-key\": \"user-public-key\",\n \"secret-key\": \"user-secret-key\",\n \"host\": \"https://langfuse.example.com\",\n }\n },\n)\n```\n\n### Personality Plugin\n\nCustomize the agent's personality and instructions.\n\n#### Example Usage\n\n```python\nfrom cryptocom_agent_client import Agent\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n plugins={\n \"personality\": {\n \"tone\": \"friendly\",\n \"language\": \"English\",\n \"verbosity\": \"high\",\n },\n },\n)\n```\n\n---\n\n## Tools\n\nTools are user-defined functions that extend the agent's capabilities. They must be decorated with `@tool`.\n\n### Example Tools\n\n#### 1. Weather Tool\n\n```python\n@tool\ndef get_weather(location: str) -> str:\n \"\"\"\n Provide the current weather for a given location.\n\n Args:\n location (str): The name of the location for which to retrieve weather information.\n\n Returns:\n str: A message describing the weather in the specified location.\n \"\"\"\n return f\"The weather in {location} is sunny.\"\n```\n\n#### 2. Custom Greeting Tool\n\n```python\n@tool\ndef greet_user(name: str) -> str:\n \"\"\"\n Generate a personalized greeting message.\n\n Args:\n name (str): The name of the user to greet.\n\n Returns:\n str: A greeting message addressed to the user.\n \"\"\"\n return f\"Hello, {name}! How can I assist you today?\"\n```\n\n#### 3. Arithmetic Tool\n\n```python\n@tool\ndef calculate_sum(a: int, b: int) -> int:\n \"\"\"\n Calculate the sum of two integers.\n\n Args:\n a (int): The first number to add.\n b (int): The second number to add.\n\n Returns:\n int: The sum of the two numbers.\n \"\"\"\n return a + b\n\n```\n\n### Using Tools in the Agent\n\n```python\nfrom cryptocom_agent_client import Agent\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n plugins={\n \"tools\": [get_weather, greet_user, calculate_sum],\n },\n)\n\nresponse = agent.interact(\"What's the weather in Berlin?\")\nprint(response)\n```\n\n---\n\n## Blockchain Functions\n\nThe library includes several pre-built blockchain-related functions:\n\n### Pre-Built Functions\n\n1. **Create Wallet**: `create_wallet()`\n2. **Get Native Balance**: `get_native_balance(address: str)`\n3. **Get ERC20 Balance**: `get_erc20_balance(address: str, token: str)`\n4. **Get Transaction by Hash**: `get_transaction_by_hash(tx_hash: str)`\n5. **Transfer Token**: `transfer_token(from_address: str, to_address: str, amount: int, token: str)`\n\n### Example Usage\n\n```python\nfrom cryptocom_agent_client import Agent\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n)\n\nresponse = agent.interact(\"Create 2 Wallets\")\nprint(response)\n```\n\n---\n\n## Advanced Usage\n\n### Custom Instructions\n\nCustomize agent behavior by modifying instructions:\n\n```python\nfrom cryptocom_agent_client import Agent\n\nagent = Agent.init(\n llm_config={\n \"provider\": \"OpenAI\",\n \"model\": \"gpt-4\",\n \"provider-api-key\": \"sk-proj-example-key\",\n },\n blockchain_config={\n \"chainId\": \"240\",\n \"explorer-api-key\": \"blockchain-example-key\",\n },\n plugins={\n \"instructions\": \"Be concise and professional.\"\n },\n)\n```\n\n---\n\n## Contributing\n\nWe welcome contributions! Please follow the guidelines in the repository.\n\n---\n\n## License\n\nThis project is licensed under the MIT License. See the LICENSE file for details.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Python client to interact with @cryptocom/agent",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/crypto-com/agent-client-py#readme",
"Homepage": "https://github.com/crypto-com/agent-client-py",
"Repository": "https://github.com/crypto-com/agent-client-py"
},
"split_keywords": [
"blockchain",
" crypto.com",
" ai",
" tool",
" sdk"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "b9ff2f44203dabadcdfd3e65e76378ed164ef3358e1685631e24cea69c58dff0",
"md5": "208be153b696f30ec3ae342581ec26e4",
"sha256": "034e828092f0762069bc088c8cea07649376c1cc033d54f173afdb53204360e7"
},
"downloads": -1,
"filename": "cryptocom_agent_client-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "208be153b696f30ec3ae342581ec26e4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0.0,>=3.9",
"size": 50940,
"upload_time": "2025-02-17T08:47:51",
"upload_time_iso_8601": "2025-02-17T08:47:51.767806Z",
"url": "https://files.pythonhosted.org/packages/b9/ff/2f44203dabadcdfd3e65e76378ed164ef3358e1685631e24cea69c58dff0/cryptocom_agent_client-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-17 08:47:51",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "crypto-com",
"github_project": "agent-client-py#readme",
"github_not_found": true,
"lcname": "cryptocom-agent-client"
}
JSON
