# Welcome to Somnia Agent Kit

Welcome to **Somnia Agent Kit**, a production-ready SDK for building, deploying, and managing AI agents on Somnia blockchain.

## 🎯 What is Somnia Agent Kit?

Somnia Agent Kit is a comprehensive TypeScript SDK that combines:

* **🤖 Agent Runtime**: Autonomous agents with lifecycle management
* **⛓️ Blockchain Integration**: Smart contracts on Somnia network
* **🧠 LLM Integration**: OpenAI, DeepSeek, and Ollama (FREE local AI)
* **💰 Agent Vault System**: Secure fund management with daily limits
* **📊 Monitoring & Telemetry**: Built-in logging, metrics, and dashboard
* **🔧 Production-Ready**: Battle-tested on Somnia Testnet

## ✨ Key Features

### For Developers

* **Easy-to-use SDK**: Build agents with minimal code
* **TypeScript Support**: Full type safety and IntelliSense
* **Flexible Architecture**: Self-hosted or shared platform modes
* **Comprehensive Testing**: Extensive test coverage

### For AI Agents

* **On-chain Registry**: Decentralized agent discovery
* **Secure Execution**: Validated and monitored agent actions
* **Fund Management**: Built-in vault system for agent transactions
* **Performance Tracking**: Real-time metrics and monitoring

## 🚀 Quick Start

```bash
# Install
npm install somnia-agent-kit
```

```typescript
import { SomniaAgentKit, SOMNIA_NETWORKS } from 'somnia-agent-kit';

// Initialize SDK
const kit = new SomniaAgentKit({
  network: SOMNIA_NETWORKS.testnet,
  contracts: {
    agentRegistry: '0xC9f3452090EEB519467DEa4a390976D38C008347',
    agentManager: '0x77F6dC5924652e32DBa0B4329De0a44a2C95691E',
    agentExecutor: '0x157C56dEdbAB6caD541109daabA4663Fc016026e',
    agentVault: '0x7cEe3142A9c6d15529C322035041af697B2B5129',
  },
  privateKey: process.env.PRIVATE_KEY,
});

await kit.initialize();

// Query agents
const agent = await kit.contracts.registry.getAgent(1);
console.log('Agent:', agent);
```

## 📚 Documentation Structure

### Getting Started

* [**Quick Start**](/somnia-agent-kit/getting-started/quickstart.md) - Get up and running in 5 minutes
* [**Installation**](/somnia-agent-kit/getting-started/installation.md) - Install the SDK
* [**FAQ**](/somnia-agent-kit/getting-started/faq.md) - Common questions

### SDK Usage

* [**Basic Usage**](/somnia-agent-kit/sdk-usage/sdk-usage.md) - SDK initialization and configuration
* [**Working with Agents**](/somnia-agent-kit/sdk-usage/sdk-agents.md) - Register and manage agents
* [**Task Management**](/somnia-agent-kit/sdk-usage/sdk-tasks.md) - Create and execute tasks
* [**Vault Operations**](/somnia-agent-kit/sdk-usage/sdk-vault.md) - Manage agent funds
* [**LLM Integration**](/somnia-agent-kit/sdk-usage/sdk-llm.md) - Use AI with your agents
* [**Token Management**](/somnia-agent-kit/sdk-usage/sdk-tokens.md) - ERC20, ERC721, and native tokens
* [**Multicall Batching**](/somnia-agent-kit/sdk-usage/sdk-multicall.md) - Optimize gas with batched calls
* [**Monitoring**](/somnia-agent-kit/sdk-usage/sdk-monitoring.md) - Logging, metrics, and dashboard
* [**Autonomous Runtime**](/somnia-agent-kit/sdk-usage/sdk-runtime.md) - Build self-running agents
* [**Storage & IPFS**](/somnia-agent-kit/sdk-usage/sdk-storage.md) - Upload and retrieve data
* [**Real-time Events**](/somnia-agent-kit/sdk-usage/sdk-events.md) - WebSocket subscriptions
* [**Wallet Connectors**](/somnia-agent-kit/sdk-usage/sdk-wallets.md) - MetaMask and wallet integration
* [**Contract Deployment**](/somnia-agent-kit/sdk-usage/sdk-deployment.md) - Deploy and verify contracts
* [**RPC Load Balancer**](/somnia-agent-kit/sdk-usage/sdk-rpc-balancer.md) - High availability setup
* [**API Reference**](/somnia-agent-kit/sdk-usage/api_reference.md) - Complete API docs

### CLI Tools

* [**CLI Guide**](/somnia-agent-kit/cli-tools/cli-guide.md) - Command-line interface

### Examples

* [**Examples Overview**](/somnia-agent-kit/examples/examples.md) - 5 working examples

## 🛠️ Tech Stack

* **Language**: TypeScript 5.3+ with full type safety
* **Blockchain**: Ethers.js v6, Somnia Network (EVM-compatible)
* **Smart Contracts**: Solidity, deployed on Somnia Testnet
* **LLM**: OpenAI GPT-4, DeepSeek, Ollama (local)
* **Monitoring**: Pino logger, custom metrics, Express dashboard
* **Build**: tsup for dual ESM/CJS builds

## 🤝 Contributing

We welcome contributions! Please check our:

* **GitHub**: <https://github.com/xuanbach0212/somnia-agent-kit>
* **Issues**: <https://github.com/xuanbach0212/somnia-agent-kit/issues>
* **Pull Requests**: <https://github.com/xuanbach0212/somnia-agent-kit/pulls>

## 📄 License

MIT License - see [LICENSE](https://github.com/xuanbach0212/somnia-agent-kit/blob/main/LICENSE/README.md) file.

## 🔗 Links

### Package

* **npm**: <https://www.npmjs.com/package/somnia-agent-kit>
* **GitHub**: <https://github.com/xuanbach0212/somnia-agent-kit>
* **Documentation**: <https://github.com/xuanbach0212/somnia-agent-kit/tree/main/docs>

### Somnia Network

* **Website**: <https://somnia.network>
* **Explorer**: <https://explorer.somnia.network>
* **Discord**: <https://discord.gg/somnia>

### Deployed Contracts (Testnet)

* **AgentRegistry**: `0xC9f3452090EEB519467DEa4a390976D38C008347`
* **AgentManager**: `0x77F6dC5924652e32DBa0B4329De0a44a2C95691E`
* **AgentExecutor**: `0x157C56dEdbAB6caD541109daabA4663Fc016026e`
* **AgentVault**: `0x7cEe3142A9c6d15529C322035041af697B2B5129`

***

Ready to build your first AI agent? Head over to the [Quick Start Guide](/somnia-agent-kit/getting-started/quickstart.md)! 🚀


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://somnia-agent-kit.gitbook.io/somnia-agent-kit/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.