📝AgentManager

Contract for managing agent tasks and lifecycle on the Somnia blockchain.

Overview

The AgentManager contract handles task creation, assignment, and completion for AI agents. It manages the full lifecycle of tasks from creation through completion or cancellation.

Contract Address

Testnet: 0x77F6dC5924652e32DBa0B4329De0a44a2C95691E

📊 Contract Architecture

contract AgentManager {
    enum TaskStatus {
        Pending,      // 0 - Task created, waiting to be accepted
        InProgress,   // 1 - Task accepted and being worked on
        Completed,    // 2 - Task completed successfully
        Cancelled     // 3 - Task cancelled
    }

    struct Task {
        uint256 agentId;        // ID of the agent assigned to the task
        address requester;      // Address that created the task
        string taskData;        // JSON string with task details
        uint256 payment;        // Payment amount for the task
        TaskStatus status;      // Current status
        uint256 createdAt;      // Creation timestamp
        uint256 completedAt;    // Completion timestamp (0 if not completed)
        string result;          // Task result (empty until completed)
    }
    
    mapping(uint256 => Task) private tasks;
    uint256 private taskCounter;
}

Task Management:

The struct uses reward for payment amount
Status enum: Pending (0), InProgress (1), Completed (2), Failed (3), Cancelled (4)
Task includes createdAt and completedAt timestamps
Use startTask() to begin execution
Use failTask() to mark as failed (with refund)
Use cancelTask() to cancel pending tasks (with refund)

Main Functions

Create Task

Create a new task for an agent:

import { ethers } from 'ethers';

const agentId = 1n;
const taskData = JSON.stringify({
  action: 'analyze',
  target: 'ETH/USD',
  params: {
    timeframe: '1h',
    indicators: ['RSI', 'MACD'],
  },
});

const tx = await kit.contracts.manager.createTask(
  agentId,
  taskData,
  { value: ethers.parseEther('0.001') } // Payment in STT
);

await tx.wait();
console.log('Task created');

Function Signature:

function createTask(
    uint256 _agentId,
    string memory _taskData
) external payable returns (uint256)

Parameters:

_agentId - ID of the agent to assign the task
_taskData - JSON string containing task details
Payment sent via msg.value (payable function)

Returns:

uint256 - Task ID

Events Emitted:

event TaskCreated(
    uint256 indexed taskId,
    uint256 indexed agentId,
    address indexed requester,
    uint256 payment
);

Note: The payment parameter is a regular function parameter, NOT sent as { value: payment } in the transaction options.

Get Task

Get task details:

const task = await kit.contracts.manager.getTask(taskId);

console.log({
  agentId: task.agentId.toString(),
  requester: task.requester,
  taskData: task.taskData,
  reward: ethers.formatEther(task.reward),
  status: task.status, // 0: Pending, 1: InProgress, 2: Completed, 3: Cancelled
  createdAt: new Date(Number(task.createdAt) * 1000),
  completedAt: task.completedAt > 0n ? new Date(Number(task.completedAt) * 1000) : null,
  result: task.result,
});

Function Signature:

function getTask(uint256 _taskId) 
    external 
    view 
    returns (
        uint256 agentId,
        address requester,
        string memory taskData,
        uint256 payment,
        TaskStatus status,
        uint256 createdAt,
        uint256 completedAt,
        string memory result
    )

Start Task

Start working on a task (agent owner only):

const tx = await kit.contracts.manager.startTask(taskId);
await tx.wait();
console.log('Task started and in progress!');

Function Signature:

function startTask(uint256 _taskId) external

Requirements:

Task must be in Pending status

Events Emitted:

event TaskStarted(
    uint256 indexed taskId,
    uint256 timestamp
);

Complete Task

Complete a task with result:

const result = JSON.stringify({
  status: 'success',
  analysis: 'ETH/USD showing bullish momentum',
  indicators: {
    RSI: 65,
    MACD: 'bullish_cross',
  },
  timestamp: Date.now(),
});

const tx = await kit.contracts.manager.completeTask(taskId, result);
await tx.wait();
console.log('Task completed!');

Function Signature:

function completeTask(
    uint256 _taskId,
    string memory _result
) external

Requirements:

Task must be in InProgress or Pending status

Events Emitted:

event TaskCompleted(
    uint256 indexed taskId,
    string result,
    uint256 timestamp
);

Fail Task

Mark a task as failed and refund the requester:

const tx = await kit.contracts.manager.failTask(taskId);
await tx.wait();
console.log('Task failed and refunded');

Function Signature:

function failTask(uint256 _taskId) external

Requirements:

Task must be in InProgress status

Events Emitted:

event TaskFailed(
    uint256 indexed taskId,
    uint256 timestamp
);

Cancel Task

Cancel a pending task and refund the requester:

const tx = await kit.contracts.manager.cancelTask(taskId);
await tx.wait();
console.log('Task cancelled');

Function Signature:

function cancelTask(uint256 _taskId) external

Requirements:

Caller must be the task requester
Task must be in Pending status

Events Emitted:

event TaskCancelled(
    uint256 indexed taskId,
    uint256 timestamp
);

Events

TaskCreated

kit.contracts.manager.on('TaskCreated', (taskId, agentId, requester, reward, timestamp) => {
  console.log(`New task ${taskId.toString()} for agent ${agentId.toString()}`);
  console.log(`Requested by: ${requester}`);
  console.log(`Reward: ${ethers.formatEther(reward)} STT`);
});

TaskStarted

kit.contracts.manager.on('TaskStarted', (taskId, timestamp) => {
  console.log(`Task ${taskId.toString()} started at ${new Date(Number(timestamp) * 1000)}`);
});

TaskCompleted

kit.contracts.manager.on('TaskCompleted', (taskId, result, timestamp) => {
  console.log(`Task ${taskId.toString()} completed`);
  console.log('Result:', result);
});

TaskFailed

kit.contracts.manager.on('TaskFailed', (taskId, timestamp) => {
  console.log(`Task ${taskId.toString()} failed at ${new Date(Number(timestamp) * 1000)}`);
});

TaskCancelled

kit.contracts.manager.on('TaskCancelled', (taskId, timestamp) => {
  console.log(`Task ${taskId.toString()} cancelled at ${new Date(Number(timestamp) * 1000)}`);
});

Task Status

const statusMap = {
  0: 'Pending',
  1: 'InProgress',
  2: 'Completed',
  3: 'Cancelled',
};

const task = await kit.contracts.manager.getTask(taskId);
console.log('Status:', statusMap[Number(task.status)]);

Complete Example

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

async function main() {
  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();

  // Create task
  const agentId = 1n;
  const taskData = JSON.stringify({
    action: 'analyze',
    target: 'ETH/USD',
  });

  const tx = await kit.contracts.manager.createTask(agentId, taskData, {
    value: ethers.parseEther('0.001'),
  });

  const receipt = await tx.wait();

  // Get task ID from event
  const event = receipt.logs.find(
    (log: any) =>
      log.topics[0] === kit.contracts.manager.interface.getEvent('TaskCreated').topicHash
  );

  if (event) {
    const parsed = kit.contracts.manager.interface.parseLog(event);
    const taskId = parsed?.args.taskId;

    console.log('Task created with ID:', taskId.toString());

    // Start task (as agent owner)
    console.log('Starting task...');
    const startTx = await kit.contracts.manager.startTask(taskId);
    await startTx.wait();

    // Simulate work
    await new Promise((resolve) => setTimeout(resolve, 2000));

    // Complete task
    const result = JSON.stringify({
      status: 'success',
      data: { price: 2500, trend: 'bullish' },
    });

    console.log('Completing task...');
    const completeTx = await kit.contracts.manager.completeTask(taskId, result);
    await completeTx.wait();

    console.log('Task completed!');

    // Get final status
    const finalTask = await kit.contracts.manager.getTask(taskId);
    console.log('Final result:', finalTask.result);
  }
}

main().catch(console.error);

Best Practices

1. Structure Task Data

interface TaskData {
  action: string;
  target: string;
  params?: Record<string, any>;
  timestamp?: number;
}

const taskData: TaskData = {
  action: 'analyze',
  target: 'ETH/USD',
  params: { timeframe: '1h' },
  timestamp: Date.now(),
};

await kit.contracts.manager.createTask(
  agentId,
  JSON.stringify(taskData),
  ethers.parseEther('0.001')
);

2. Handle Task Results

const task = await kit.contracts.manager.getTask(taskId);

if (task.status === 2n) {
  // Completed
  const result = JSON.parse(task.result);
  console.log('Task result:', result);
} else if (task.status === 3n) {
  // Cancelled
  console.error('Task was cancelled');
}

3. Monitor Task Progress

// Poll for status
async function waitForCompletion(taskId: bigint, maxWait = 60000) {
  const start = Date.now();

  while (Date.now() - start < maxWait) {
    const task = await kit.contracts.manager.getTask(taskId);

    if (task.status === 2n) {
      return JSON.parse(task.result);
    } else if (task.status === 3n) {
      throw new Error('Task failed');
    } else if (task.status === 4n) {
      throw new Error('Task was cancelled');
    }

    await new Promise((resolve) => setTimeout(resolve, 1000));
  }

  throw new Error('Task timeout');
}

const result = await waitForCompletion(taskId);

AgentRegistry Contract - Register agents
AgentVault Contract - Manage agent funds
Task Management Guide - SDK usage
Smart Contracts Overview - All contracts

⚠️ Important Notes

Payment via msg.value - Payment is sent as transaction value using { value }, not as a function parameter
Task Status - Tasks can be: Pending (0), InProgress (1), Completed (2), Failed (3), or Cancelled (4)
Start Before Complete - Must call startTask() before completeTask()
Failure Handling - Use failTask() to mark as failed with refund, or cancelTask() to cancel pending tasks

Next: Learn about AgentVault for managing agent funds.

PreviousAgentVault NextArchitecture

Last updated 5 months ago

Good night

hashtagOverview

hashtagContract Address

hashtag📊 Contract Architecture

hashtagMain Functions

hashtagCreate Task

hashtagGet Task

hashtagStart Task

hashtagComplete Task

hashtagFail Task

hashtagCancel Task

hashtagEvents

hashtagTaskCreated

hashtagTaskStarted

hashtagTaskCompleted

hashtagTaskFailed

hashtagTaskCancelled

hashtagTask Status

hashtagComplete Example

hashtagBest Practices

hashtag1. Structure Task Data

hashtag2. Handle Task Results

hashtag3. Monitor Task Progress

hashtag📚 Related Documentation

hashtag⚠️ Important Notes

Overview

Contract Address

📊 Contract Architecture

Main Functions

Create Task

Get Task

Start Task

Complete Task

Fail Task

Cancel Task

Events

TaskCreated

TaskStarted

TaskCompleted

TaskFailed

TaskCancelled

Task Status

Complete Example

Best Practices

1. Structure Task Data

2. Handle Task Results

3. Monitor Task Progress

📚 Related Documentation

⚠️ Important Notes