# Overview {% hint style="info" %} **Prototype Notice:** Somnia Agents is in prototype state and deployed on both **Somnia Mainnet** (chain ID `5031`) and **Somnia Testnet** (chain ID `50312`). Features and APIs may change as development progresses — see the [Quickstart](https://docs.somnia.network/agents/invoking-agents/quickstart) for current contract addresses and RPC URLs. {% endhint %} ## Overview ### Vision Smart contracts revolutionized trustless computation, but they operate in isolation. They cannot fetch external data, call APIs, or perform complex computation. Today's solutions require stitching together multiple systems—Chainlink for price feeds, separate oracle networks for weather data, centralized services for AI—each adding counterparty risk and integration complexity. What if smart contracts could natively access the internet, run AI models, and perform arbitrary computation—all while maintaining blockchain guarantees of decentralization and auditability? Somnia Agents extend the Somnia blockchain by enabling Smart Contracts and users to trigger decentralized, auditable compute jobs—including LLM-based tasks—executed across Somnia's decentralized network. By integrating with Somnia's native on-chain reactivity, Agents make it possible to build and run fully featured decentralized applications. ### What are Somnia Agents? Somnia Agents function as **decentralized, sandboxed compute containers**. This architecture makes them simple to develop, much like familiar serverless platforms such as AWS Lambda or Google Cloud Run, but with the advantages of blockchain auditability, reactivity, and security. #### Capabilities Somnia Agents unlock use cases not possible with traditional EVM Smart Contracts: * **Acting as Oracles:** Querying the internet and reliably bringing external data on-chain — see [JSON API Request](https://docs.somnia.network/agents/base-agents/json-api-request) * **Outbound Communication:** Triggering actions or sending messages to external internet services * **LLM Invocation:** Leveraging on-chain deterministic AI models for autonomous agents — see [LLM Inference](https://docs.somnia.network/agents/base-agents/llm-inference) and [LLM Parse Website](https://docs.somnia.network/agents/base-agents/llm-parse-website) ### How Somnia Agents Work {% @mermaid/diagram content="flowchart TB subgraph User\["User / Smart Contract"] A\[Invoke Agent] end ``` subgraph Network["Somnia Decentralized Network"] B[Node 1] C[Node 2] D[Node 3] E["Node N..."] end subgraph Consensus["Consensus Layer"] F{Majority Agreement?} end subgraph Result["Output"] G[Execution Receipt] H["Application Binary Interface (ABI) Response"] I[Invalid - Rejected] end A --> B A --> C A --> D A --> E B --> F C --> F D --> F E --> F F -->|Yes| G F -->|Yes| H F -->|No| I" %} ``` #### Execution When an Agent is invoked, it runs on a **decentralized subset of the Somnia network nodes**. Execution is considered valid only when a majority of nodes reach consensus on the result. Each invocation produces an audit receipt, allowing anyone to retrospectively inspect each step in an Agent execution. #### Deterministic LLMs Somnia Agents can invoke large language models (LLMs) that run as part of the validator network. Unlike traditional LLM APIs where outputs vary between calls, Somnia's LLMs use fixed random seeds and controlled temperature parameters to produce **deterministic outputs**—the same input always yields the same output across all validating nodes. This determinism enables consensus: when multiple nodes independently run the same LLM inference with identical parameters, they produce identical results, allowing the network to verify and agree on AI-generated outputs. See [LLM Inference](https://docs.somnia.network/agents/base-agents/llm-inference) for usage details. #### Receipts An execution receipt is a **signed manifest of intermediate computation steps** taken within the Agent. This is similar to the logs and manifests used by CI build systems. **Important:** The final **result** is what validators reach consensus on. Receipt steps are **subjective**—they show what one node did to compute the result, which may vary slightly between nodes. This provides transparency without requiring consensus on every intermediate step. {% @mermaid/diagram content="flowchart LR subgraph Receipt\["Execution Receipt"] A\[Step 1: Input Received] --> B\[Step 2: Processing] B --> C\[Step 3: External Call] C --> D\[Step 4: Result Computed] D --> E\[Step 5: Output Encoded] end ``` E --> F[Signed by Validators] F --> G[On-Chain Audit Trail]" %} ``` See [Receipts](https://docs.somnia.network/agents/invoking-agents/receipts) for viewing and understanding receipts. #### Payment and Gas Invoking an Agent requires **SOMI** (mainnet) or **STT** (testnet). Users send a deposit when creating a request. The contract splits it into two pots: an **operations reserve** (`minPerAgentDeposit × subcommitteeSize`) that funds runner gas refunds, callback gas, and keeper payments; and an **agent reward pot** (everything above the reserve) that's split equally and paid to every elected subcommittee member at finalisation. Whatever's left after everything settles is rebated to the requester. See [Gas Fees](https://docs.somnia.network/agents/invoking-agents/gas-fees) for the full fund-flow diagram and details on sizing deposits. ### EVM-Native Schema Somnia Agents are invoked via **HTTP POST requests**, where both the input data and returned result are ABI-encoded, just like traditional Ethereum smart contract calls. The interface and schema of each Agent closely follows the **standard Solidity contract ABI**. This means you can use familiar web3 tools—such as viem, Ethers.js, or Solidity's own ABI encoders/decoders—to interact with Agents in exactly the same way you would a smart contract. **Key Benefits:** * Code reuse with existing smart contract tooling * Seamless integration with developer workflows * Agents feel like native blockchain contracts * Enables richer off-chain compute and connectivity ### Roadmap {% @mermaid/diagram content="timeline title Somnia Agents Roadmap section Phase 1 Now : Core Agents Available : JSON API Selector : Idempotent Request : AI LLM Invocation : AI Parse Website : Find URL for Topic section Phase 2 2026 : Custom User-Defined Agents : Full Agent SDK : Advanced Tooling" %} Agents will roll out in phases: **Phase 1 (Current):** A curated set of core Agents is available to the ecosystem, covering common use cases like oracles, AI, and external communication. **Phase 2 (2026):** Support for fully custom, user-defined Agents will launch, further expanding Somnia's capabilities. ### Use Cases #### Oracles Build on-chain oracles using the [JSON API Request](https://docs.somnia.network/agents/base-agents/json-api-request) agent: * Price feeds from cryptocurrency APIs * Weather data for parametric insurance * Sports scores for prediction markets * Any external API data #### AI Services Leverage deterministic AI with [LLM Inference](https://docs.somnia.network/agents/base-agents/llm-inference) and [LLM Parse Website](https://docs.somnia.network/agents/base-agents/llm-parse-website): * Text generation and analysis * Content moderation decisions * Dynamic NFT descriptions * Intelligent automation #### Outbound Communication * Webhook triggers from smart contracts * Notifications to external systems * Off-chain workflow initiation * Database synchronization #### Data Processing * JSON extraction and transformation * Web scraping with AI — see [LLM Parse Website](https://docs.somnia.network/agents/base-agents/llm-parse-website) * Data validation and enrichment * Format conversion ### Key Features * **EVM-Native**: Standard Solidity ABI encoding for seamless integration * **Decentralized**: No central authority or single point of failure * **Auditable**: Every execution produces verifiable receipts * **Monetizable**: Agent Runners earn fees from usage * **Composable**: Agents can be chained together * **Permissionless**: Anyone can invoke agents * **Deterministic AI**: On-chain AI with consensus guarantees ### Next Steps #### Invoking Agents * [Quickstart](https://docs.somnia.network/agents/invoking-agents/quickstart) — Start invoking agents * [Gas Fees](https://docs.somnia.network/agents/invoking-agents/gas-fees) — Learn about invocation costs #### Base Agents * [JSON API Request](https://docs.somnia.network/agents/base-agents/json-api-request) — Fetch data from any JSON API * [LLM Inference](https://docs.somnia.network/agents/base-agents/llm-inference) — Generate text with on-chain AI * [LLM Parse Website](https://docs.somnia.network/agents/base-agents/llm-parse-website) — Extract structured data from websites --- # 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://docs.somnia.network/agents/readme.md?ask= ``` 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.