Quickstart

Get your first IrisOS agent up and running in just a few minutes using the API!

Prerequisites

• IrisOS server running (see Installation)

• API key from your IrisOS account

• HTTP client (curl, Postman, or your preferred programming language)

Step 1: Get Your API Key

1. Sign up at irisos.xyz

2. Navigate to Settings → API Keys

3. Generate a new API key

4. Save it securely as an environment variable:

export IRIS_API_KEY="your_api_key_here"

Step 2: Create Your First Agent

Use the API to create a new agent with a custom personality:

Using cURL

curl -X POST https://api.irisos.xyz/v1/agents \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Iris",
    "bio": [
      "I am Iris, an AI agent built on IrisOS.",
      "I help users with various tasks and conversations.",
      "I am friendly, helpful, and always learning."
    ],
    "personality": {
      "traits": ["helpful", "curious", "intelligent", "friendly"],
      "style": "conversational and engaging"
    },
    "knowledge": [
      "I know about AI and machine learning",
      "I understand blockchain technology",
      "I can help with coding and development"
    ],
    "goals": [
      "Help users accomplish their tasks",
      "Learn from every interaction",
      "Provide accurate and helpful information"
    ],
    "modelProvider": "openai",
    "model": "gpt-4"
  }'

Using JavaScript

const axios = require('axios');

const createAgent = async () => {
  const response = await axios.post(
    'https://api.irisos.xyz/v1/agents',
    {
      name: 'Iris',
      bio: [
        'I am Iris, an AI agent built on IrisOS.',
        'I help users with various tasks and conversations.',
        'I am friendly, helpful, and always learning.'
      ],
      personality: {
        traits: ['helpful', 'curious', 'intelligent', 'friendly'],
        style: 'conversational and engaging'
      },
      knowledge: [
        'I know about AI and machine learning',
        'I understand blockchain technology',
        'I can help with coding and development'
      ],
      goals: [
        'Help users accomplish their tasks',
        'Learn from every interaction',
        'Provide accurate and helpful information'
      ],
      modelProvider: 'openai',
      model: 'gpt-4'
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.IRIS_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Agent created:', response.data);
  return response.data.data;
};

createAgent();

Using Python

import requests
import os

def create_agent():
    url = "https://api.irisos.xyz/v1/agents"
    headers = {
        "Authorization": f"Bearer {os.getenv('IRIS_API_KEY')}",
        "Content-Type": "application/json"
    }
    data = {
        "name": "Iris",
        "bio": [
            "I am Iris, an AI agent built on IrisOS.",
            "I help users with various tasks and conversations.",
            "I am friendly, helpful, and always learning."
        ],
        "personality": {
            "traits": ["helpful", "curious", "intelligent", "friendly"],
            "style": "conversational and engaging"
        },
        "knowledge": [
            "I know about AI and machine learning",
            "I understand blockchain technology",
            "I can help with coding and development"
        ],
        "goals": [
            "Help users accomplish their tasks",
            "Learn from every interaction",
            "Provide accurate and helpful information"
        ],
        "modelProvider": "openai",
        "model": "gpt-4"
    }

    response = requests.post(url, json=data, headers=headers)
    response.raise_for_status()
    print("Agent created:", response.json())
    return response.json()['data']

create_agent()

Response

You'll receive a response like this:

{
  "success": true,
  "data": {
    "id": "agent_a1b2c3d4e5f6",
    "name": "Iris",
    "status": "active",
    "createdAt": "2025-01-15T10:30:00Z",
    "apiEndpoint": "https://api.irisos.xyz/v1/agents/agent_a1b2c3d4e5f6"
  }
}

Save the id value - you'll need it to interact with your agent!

Step 3: Send a Message to Your Agent

Now let's chat with your agent:

Using cURL

curl -X POST https://api.irisos.xyz/v1/agents/agent_a1b2c3d4e5f6/messages \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello! What can you help me with?",
    "userId": "user_123"
  }'

Using JavaScript

const sendMessage = async (agentId, message) => {
  const response = await axios.post(
    `https://api.irisos.xyz/v1/agents/${agentId}/messages`,
    {
      text: message,
      userId: 'user_123'
    },
    {
      headers: {
        'Authorization': `Bearer ${process.env.IRIS_API_KEY}`,
        'Content-Type': 'application/json'
      }
    }
  );

  console.log('Agent:', response.data.data.response);
  return response.data;
};

sendMessage('agent_a1b2c3d4e5f6', 'Hello! What can you help me with?');

Response

{
  "success": true,
  "data": {
    "messageId": "msg_xyz789",
    "response": "Hi there! I'm Iris. I can help you with many things including answering questions about AI and machine learning, explaining blockchain technology, and assisting with coding and development. What would you like to explore?",
    "agentId": "agent_a1b2c3d4e5f6",
    "userId": "user_123",
    "timestamp": "2025-01-15T10:35:00Z"
  }
}

Step 4: Add Platform Integrations

Discord Integration

Update your agent to connect to Discord:

curl -X PATCH https://api.irisos.xyz/v1/agents/agent_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": ["discord"],
    "settings": {
      "discord": {
        "channels": ["general", "bot-commands"],
        "respondToMentions": true
      }
    }
  }'

Make sure you've set up your Discord bot token in the IrisOS server environment variables.

Twitter Integration

Add Twitter capabilities:

curl -X PATCH https://api.irisos.xyz/v1/agents/agent_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "clients": ["discord", "twitter"],
    "settings": {
      "twitter": {
        "enableReplies": true,
        "enableMentions": true,
        "postFrequency": "4h"
      }
    }
  }'

Step 5: Test Conversations

The agent remembers context when you use the same userId:

// First message
await sendMessage('agent_a1b2c3d4e5f6', 'What is blockchain?', 'user_123');
// Response: "Blockchain is a distributed ledger technology..."

// Follow-up message (agent remembers the context)
await sendMessage('agent_a1b2c3d4e5f6', 'How is it used in DeFi?', 'user_123');
// Response: "In DeFi, blockchain technology is used to..."

Example: Complete Workflow

Here's a complete example that creates an agent and has a conversation:

const axios = require('axios');

const API_BASE = 'https://api.irisos.xyz/v1';
const API_KEY = process.env.IRIS_API_KEY;

const client = axios.create({
  baseURL: API_BASE,
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

async function main() {
  // 1. Create agent
  const createResponse = await client.post('/agents', {
    name: 'DeFiHelper',
    bio: ['I help users understand DeFi protocols'],
    personality: {
      traits: ['knowledgeable', 'patient', 'helpful'],
      style: 'clear and educational'
    },
    modelProvider: 'openai',
    model: 'gpt-4'
  });

  const agentId = createResponse.data.data.id;
  console.log(`Created agent: ${agentId}`);

  // 2. Send messages
  const messages = [
    'What is DeFi?',
    'How do liquidity pools work?',
    'What are the risks?'
  ];

  for (const message of messages) {
    const response = await client.post(
      `/agents/${agentId}/messages`,
      {
        text: message,
        userId: 'user_123'
      }
    );

    console.log(`\nYou: ${message}`);
    console.log(`Agent: ${response.data.data.response}`);
  }

  // 3. Get agent details
  const agentDetails = await client.get(`/agents/${agentId}`);
  console.log(`\nAgent stats:`, agentDetails.data.data.metrics);
}

main().catch(console.error);

Add More Capabilities

Enable Plugins

Update your agent with blockchain capabilities:

curl -X PATCH https://api.irisos.xyz/v1/agents/agent_a1b2c3d4e5f6 \
  -H "Authorization: Bearer $IRIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": [
      {
        "name": "@irisos/plugin-evm",
        "enabled": true,
        "config": {
          "chains": ["ethereum", "polygon"]
        }
      }
    ]
  }'

Next Steps

• API Reference - Complete API documentation

• Customize Your Agent - Deep dive into character configuration

• Platform Integrations - Connect to Discord, Twitter, and more

• Plugin Reference - Browse available plugins

SDK Installation (Optional)

For easier development, install the official SDK:

JavaScript/TypeScript

npm install @irisos/sdk

const { IrisOS } = require('@irisos/sdk');

const iris = new IrisOS({
  apiKey: process.env.IRIS_API_KEY
});

// Create agent
const agent = await iris.agents.create({
  name: 'MyAgent',
  personality: { traits: ['helpful'] }
});

// Send message
const response = await iris.agents.sendMessage(agent.id, {
  text: 'Hello!',
  userId: 'user_123'
});

Python

pip install irisos

from irisos import IrisOS

iris = IrisOS(api_key=os.getenv('IRIS_API_KEY'))

# Create agent
agent = iris.agents.create(
    name='MyAgent',
    personality={'traits': ['helpful']}
)

# Send message
response = iris.agents.send_message(
    agent.id,
    text='Hello!',
    user_id='user_123'
)

Need Help?

• API Overview - API documentation

• Discord Community - Get help from the community

• GitHub Discussions - Ask questions

• GitHub Issues - Report bugs