Build your AI agents in three lines of code!
- Three lines of code setup
- Simple Agent Definition
- Fast Responses
- Solana Ecosystem Integration
- Multi-Agent Swarm
- Multi-Modal (Images & Audio & Text)
- Conversational Memory & History
- Internet Search
- Intelligent Routing
- Business Alignment
- Extensible Tooling
- Automatic Tool Workflows
- Autonomous Operation
- Knowledge Base
- MCP Support
- Guardrails
- Pydantic Logfire
- Tested & Secure
- Built in Python
- Powers CometHeart
- Easy three lines of code setup
- Simple agent definition using JSON
- Fast AI responses
- Solana Ecosystem Integration via AgentiPy
- MCP tool usage with first-class support for Zapier
- Integrated observability and tracing via Pydantic Logfire
- Designed for a multi-agent swarm
- Seamless streaming with real-time multi-modal processing of text, audio, and images
- Persistent memory that preserves context across all agent interactions
- Quick Internet search to answer users' queries
- Streamlined message history for all agent interactions
- Intelligent query routing to agents with optimal domain expertise or your own custom routing
- Unified value system ensuring brand-aligned agent responses
- Powerful tool integration using standard Python packages and/or inline tools
- Assigned tools are utilized by agents automatically and effectively
- Integrated Knowledge Base with semantic search and automatic PDF chunking
- Input and output guardrails for content filtering, safety, and data sanitization
- Automatic sequential tool workflows allowing agents to chain multiple tools
- Combine with event-driven systems to create autonomous agents
- Python - Programming Language
- OpenAI - AI Model Provider
- MongoDB - Conversational History (optional)
- Zep Cloud - Conversational Memory (optional)
- Pinecone - Knowledge Base (optional)
- AgentiPy - Solana Ecosystem (optional)
- Zapier - App Integrations (optional)
- Pydantic Logfire - Observability and Tracing (optional)
- gpt-4.1 (agent)
- gpt-4.1-nano (router)
- text-embedding-3-large or text-embedding-3-small (embedding)
- tts-1 (audio TTS)
- gpt-4o-mini-transcribe (audio transcription)
You can install Solana Agent using pip:
pip install solana-agent
In both flows of single and multiple agents - it is one user query to one agent using one or many tools (if needed).
An agent can have multiple tools and will choose the best ones to fulfill the user's query.
Routing is determined by optimal domain expertise of the agent for the user's query.
When the agent uses tools it feeds the tools output back to itself to generate the final response.
This is important as tools generally output unstructured and unformatted data that the agent needs to prepare for the user.
Keep this in mind while designing your agentic systems using Solana Agent.
Single Agent
┌────────┐ ┌─────────┐ ┌────────-┐
│ │ │ │ │ │
│ │ │ │ │ │
│ User │◄──────►│ Agent │◄──────►│ Tools │
│ │ │ │ │ │
│ │ │ │ │ │
└────────┘ └─────────┘ └────────-┘
Multiple Agents
┌────────┐ ┌──────────┐ ┌─────────┐ ┌────────-┐
│ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │
┌───►│ User ├───────►│ Router ├───────►│ Agent │◄──────►│ Tools │
│ │ │ │ │ │ │ │ │
│ │ │ │ │ │ │ │ │
│ └────────┘ └──────────┘ └────┬────┘ └────────-┘
│ │
│ │
│ │
│ │
└───────────────────────────────────────────────┘
from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "What are the latest AI developments?"):
print(response, end="")from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
audio_content = await audio_file.read()
async for response in solana_agent.process("user123", audio_content, output_format="audio", audio_voice="nova", audio_input_format="webm", audio_output_format="aac"):
print(response, end="")from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "What is the latest news on Elon Musk?", output_format="audio", audio_voice="nova", audio_output_format="aac"):
print(response, end="")from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
audio_content = await audio_file.read()
async for response in solana_agent.process("user123", audio_content, audio_input_format="aac"):
print(response, end="")from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "vision_expert",
"instructions": "You are an expert at analyzing images and answering questions about them.",
"specialization": "Image analysis",
}
],
}
solana_agent = SolanaAgent(config=config)
# Example with an image URL
image_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg"
# Example reading image bytes from a file
image_bytes = await image_file.read()
# You can mix URLs and bytes in the list
images_to_process = [
image_url,
image_bytes,
]
async for response in solana_agent.process("user123", "What is in this image? Describe the scene.", images=images_to_process):
print(response, end="")Solana Agent includes a command-line interface (CLI) for text-based chat using a configuration file.
Ensure you have a valid configuration file (e.g., config.json) containing at least your OpenAI API key and agent definitions.
./config.json
{
"openai": {
"api_key": "your-openai-api-key"
},
"agents": [
{
"name": "default_agent",
"instructions": "You are a helpful AI assistant.",
"specialization": "general"
}
]
}Also ensure that you have pip install uv to call uvx.
uvx solana-agent [OPTIONS]
Options:
--user-id TEXT: The user ID for the conversation (default: cli_user).
--config TEXT: Path to the configuration JSON file (default: config.json).
--prompt TEXT: Optional system prompt override for the agent.
--help: Show help message and exit.
# Using default config.json and user_id
uvx solana-agent
# Specifying user ID and config path
uvx solana-agent --user-id my_cli_session --config ./my_agent_config.jsonconfig = {
"business": {
"mission": "To provide users with a one-stop shop for their queries.",
"values": {
"Friendliness": "Users must be treated fairly, openly, and with friendliness.",
"Ethical": "Agents must use a strong ethical framework in their interactions with users.",
},
"goals": [
"Empower users with great answers to their queries.",
],
"voice": "The voice of the brand is that of a research business."
},
}config = {
"mongo": {
"connection_string": "your-mongo-connection-string",
"database": "your-database-name"
},
}config = {
"zep": {
"api_key": "your-zep-cloud-api-key",
},
}config = {
"logfire": {
"api_key": "your-logfire-write-token",
},
}The Knowledge Base (KB) is meant to store text values and/or small PDFs.
config = {
"knowledge_base": {
"pinecone": {
"api_key": "your-pinecone-api-key",
"index_name": "your-pinecone-index-name",
}
},
"mongo": {
"connection_string": "your-mongo-connection-string",
"database": "your-database-name"
},
}from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"knowledge_base": {
"pinecone": {
"api_key": "your-pinecone-api-key",
"index_name": "your-pinecone-index-name",
}
},
"mongo": {
"connection_string": "your-mongo-connection-string",
"database": "your-database-name"
},
"agents": [
{
"name": "kb_expert",
"instructions": "You answer questions based on the provided knowledge base documents.",
"specialization": "Company Knowledge",
}
]
}
solana_agent = SolanaAgent(config=config)
doc_text = "Solana Agent is a Python framework for building multi-agent AI systems."
doc_metadata = {
"source": "internal_docs",
"version": "1.0",
"tags": ["framework", "python", "ai"]
}
await solana_agent.kb_add_document(text=doc_text, metadata=doc_metadata)
async for response in solana_agent.process("user123", "What is Solana Agent?"):
print(response, end="")from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"knowledge_base": {
"pinecone": {
"api_key": "your-pinecone-api-key",
"index_name": "your-pinecone-index-name",
}
},
"mongo": {
"connection_string": "your-mongo-connection-string",
"database": "your-database-name"
},
"agents": [
{
"name": "kb_expert",
"instructions": "You answer questions based on the provided knowledge base documents.",
"specialization": "Company Knowledge",
}
]
}
solana_agent = SolanaAgent(config=config)
pdf_bytes = await pdf_file.read()
pdf_metadata = {
"source": "annual_report_2024.pdf",
"year": 2024,
"tags": ["finance", "report"]
}
await solana_agent.kb_add_pdf_document(
pdf_data=pdf_bytes,
metadata=pdf_metadata,
)
async for response in solana_agent.process("user123", "Summarize the annual report for 2024."):
print(response, end="")Guardrails allow you to process and potentially modify user input before it reaches the agent (Input Guardrails) and agent output before it's sent back to the user (Output Guardrails). This is useful for implementing safety checks, content moderation, data sanitization, or custom transformations.
Solana Agent provides a built-in PII scrubber based on scrubadub.
from solana_agent import SolanaAgent
config = {
"guardrails": {
"input": [
# Example using a custom input guardrail
{
"class": "MyInputGuardrail",
"config": {"setting1": "value1"}
},
# Example using the built-in PII guardrail for input
{
"class": "solana_agent.guardrails.pii.PII",
"config": {
"locale": "en_GB", # Optional: Specify locale (default: en_US)
"replacement": "[REDACTED]" # Optional: Custom replacement format
}
}
],
"output": [
# Example using a custom output guardrail
{
"class": "MyOutputGuardrail",
"config": {"filter_level": "high"}
},
# Example using the built-in PII guardrail for output (with defaults)
{
"class": "solana_agent.guardrails.pii.PII"
# No config needed to use defaults
}
]
},
}from solana_agent import InputGuardrail, OutputGuardrail
import logging
logger = logging.getLogger(__name__)
class MyInputGuardrail(InputGuardrail):
def __init__(self, config=None):
super().__init__(config)
self.setting1 = self.config.get("setting1", "default_value")
logger.info(f"MyInputGuardrail initialized with setting1: {self.setting1}")
async def process(self, text: str) -> str:
# Example: Convert input to lowercase
processed_text = text.lower()
logger.debug(f"Input Guardrail processed: {text} -> {processed_text}")
return processed_text
class MyOutputGuardrail(OutputGuardrail):
def __init__(self, config=None):
super().__init__(config)
self.filter_level = self.config.get("filter_level", "low")
logger.info(f"MyOutputGuardrail initialized with filter_level: {self.filter_level}")
async def process(self, text: str) -> str:
# Example: Basic profanity filtering (replace with a real library)
if self.filter_level == "high" and "badword" in text:
processed_text = text.replace("badword", "*******")
logger.warning(f"Output Guardrail filtered content.")
return processed_text
logger.debug("Output Guardrail passed text through.")
return textTools empower agents to interact with external systems, fetch data, or perform actions. They can be used reactively within a user conversation or proactively when an agent is triggered autonomously.
Tools can be used from plugins like Solana Agent Kit (sakit) or via inline tools. Tools available via plugins integrate automatically with Solana Agent.
- Agents can use multiple tools per response and should apply the right sequential order (like send an email to [email protected] with the latest news on Solana)
- Agents choose the best tools for the job
- Solana Agent doesn't use OpenAI function calling (tools) as they don't support async functions
- Solana Agent tools are async functions
pip install sakit
config = {
"tools": {
"solana": {
"private_key": "your-solana-wallet-private-key", # base58 encoded string
"rpc_url": "your-solana-rpc-url",
},
},
"agents": [
{
"name": "solana_expert",
"instructions": "You are an expert Solana blockchain assistant. You always use the Solana tool to perform actions on the Solana blockchain.",
"specialization": "Solana blockchain interaction",
"tools": ["solana"], # Enable the tool for this agent
}
]
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "What is my SOL balance?"):
print(response, end="")pip install sakit
from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"tools": {
"search_internet": {
"api_key": "your-openai-api-key",
},
},
"agents": [
{
"name": "news_specialist",
"instructions": "You are an expert news agent. You use your search_internet tool to get the latest information.",
"specialization": "News researcher and specialist",
"tools": ["search_internet"], # Enable the tool for this agent
}
],
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "What is the latest news on Elon Musk?"):
print(response, end="")Zapier MCP has been tested, works, and is supported.
Zapier integrates over 7,000+ apps with 30,000+ actions that your Solana Agent can utilize.
Other MCP servers may work but are not supported.
pip install sakit
from solana_agent import SolanaAgent
config = {
"tools": {
"mcp": {
"urls": ["my-zapier-mcp-url"],
}
},
"agents": [
{
"name": "zapier_expert",
"instructions": "You are an expert in using Zapier integrations using MCP. You always use the mcp tool to perform Zapier AI like actions.",
"specialization": "Zapier service integration expert",
"tools": ["mcp"], # Enable the tool for this agent
}
]
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "Send an email to [email protected] to clean his room!"):
print(response, end="")from solana_agent import SolanaAgent
from solana_agent.interfaces.plugins.plugins import Tool
class TestTool(Tool):
def __init__(self):
# your tool initialization - delete the following pass
pass
@property
def name(self) -> str:
return "test_function"
@property
def description(self) -> str:
return "Test function for Solana Agent"
def configure(self, config: Dict[str, Any]) -> None:
"""Configure with all possible API key locations."""
super().configure(config)
# read your config values - delete the following pass
pass
def get_schema(self) -> Dict[str, Any]:
# this is an example schema
return {
"type": "object",
"properties": {
"query": {"type": "string", "description": "Search query text"},
"user_id": {"type": "string", "description": "User ID for the search session"}
},
"required": ["query", "user_id"]
}
async def execute(self, **params) -> Dict[str, Any]:
try:
# your tool logic
result = "Your tool results"
return {
"status": "success",
"result": result,
}
except Exception as e:
return {
"status": "error",
"message": f"Error: {str(e)}",
}
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
test_tool = TestTool()
solana_agent.register_tool("customer_support", test_tool)
async for response in solana_agent.process("user123", "What are the latest AI developments?"):
print(response, end="")While Solana Agent facilitates request-response interactions, the underlying architecture supports building autonomous agents. You can achieve autonomy by orchestrating calls based on external triggers rather than direct user input.
Key Concepts:
- External Triggers: Use schedulers like cron, message queues (RabbitMQ, Kafka), monitoring systems, webhooks, or other event sources to initiate agent actions.
- Programmatic Calls: Instead of a user typing a message, your triggering system calls with a specific message (acting as instructions or data for the task) and potentially a dedicated user representing the autonomous process.
- Tool-Centric Tasks: Autonomous agents often focus on executing specific tools. The prompt can instruct the agent to use a particular tool with given parameters derived from the triggering event.
- Example Scenario: An agent could be triggered hourly by a scheduler. The
messagecould be "Check the SOL balance for wallet X using thesolanatool." The agent executes the tool, and the result could be logged or trigger another tool (e.g., usingmcpto send an alert if the balance is low).
By combining Solana Agent's agent definitions, tool integration, and routing with external orchestration, you can create sophisticated autonomous systems.
from solana_agent import SolanaAgent
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "How do replace the latch on my dishwasher?", "This is my corporate appliance fixing FAQ"):
print(response, end="")In advanced cases like implementing a ticketing system on-top of Solana Agent - you can use your own router.
from solana_agent import SolanaAgent
from solana_agent.interfaces.services.routing import RoutingService as RoutingServiceInterface
config = {
"openai": {
"api_key": "your-openai-api-key",
},
"agents": [
{
"name": "research_specialist",
"instructions": "You are an expert researcher who synthesizes complex information clearly.",
"specialization": "Research and knowledge synthesis",
},
{
"name": "customer_support",
"instructions": "You provide friendly, helpful customer support responses.",
"specialization": "Customer inquiries",
}
],
}
class Router(RoutingServiceInterface)
def __init__(self):
# your router initialization - delete the following pass
pass
async def route_query(self, query: str) -> str:
# a simple example to route always to customer_support agent
return "customer_support"
router = Router()
solana_agent = SolanaAgent(config=config)
async for response in solana_agent.process("user123", "What are the latest AI developments?", router=router):
print(response, end="")The official up-to-date documentation site
Solana Agent Documentation Site
The official collection of tools in one plugin
The official example app written in FastAPI and Next.js
The official demo app written in FastAPI and Next.js
Compare Python Agent Frameworks
If you have a question, feedback, or feature request - please open a GitHub discussion.
If you find a bug - please open a GitHub issue.
We are currently accepting PRs if approved in discussions. Make sure all tests pass and the README & docs are updated.
To run the documentation site locally run make livehtml in the root directory.
To run the test suite locally run poetry run pytest --cov=solana_agent --cov-report=html in the root directory.
This project is licensed under the MIT License - see the LICENSE file for details.