user-agent-sdk 0.2.0

A secure SDK for building custom user agents (workers) that run in your environment and connect safely with the akaBot 2.0 platform.

User Agent SDK

A Python SDK for building and running user agents that interact with the Conductor service.

Overview

The User Agent SDK empowers developers to build secure, customizable worker agents that operate within their own environment while integrating seamlessly with the akaBot 2.0 platform. Each user agent extends workflow capabilities by executing custom node logic locally, ensuring sensitive operations and data remain under the user’s control while maintaining trusted communication and coordination with the central platform.

Prerequisites

• Python 3.12 or higher
• uv package manager installed
• An akaBot 2.0 account with access to the Workflow Builder

Installation

uv add user-agent-sdk

Quick Start

1. Create a credentials.json file

This file contains the authentication details for your user agent. You can download this file from the akaBot 2.0 Workflow Builder when creating a new user agent.

Place this file in the same directory as your user agent code.

{
  "clientId": "your-client-id",
  "clientSecret": "your-client-secret",
  "agentId": "00000000-0000-0000-0000-000000000000#user-agent"
}

2. Create your user agent

The user agent code defines the logic that will be executed when the agent receives a task such as processing data or performing actions.

from logging import Logger
from user_agent_sdk import user_agent


@user_agent()
def sum_agent(input_data: dict, logger: Logger):
    # These logs will be visible in the akaBot 2.0 platform for monitoring
    logger.info("Processing task input")

    # Do some work with the input data
    num1 = input_data.get("num1", 0)
    num2 = input_data.get("num2", 0)
    total = num1 + num2

    return total

3. Run your user agent

Use built-in CLI to run your user agent locally:

uvx useragent run your_agent.py

Alternatively, you can run it without uvx by installing the SDK and executing the script directly:

useragent run your_agent.py

Folder structure:

your_project/
├── .venv/
├── credentials.json
├── pyproject.toml
└── your_agent.py

Advanced Usage

Custom Error Handling

The SDK automatically handles exceptions during task execution:

• Agent can be retried (max attempts are 3) on failure by regular exceptions
• NonRetryableException indicates that the task should not be retried

from user_agent_sdk import user_agent
from user_agent_sdk.utils.exception import NonRetryableException


@user_agent()
def my_agent(input_data):
    user_name = input_data.get("user_name")
    if not user_name:
        raise NonRetryableException("'user_name' is required")

    # Regular processing...

Async Support

The SDK supports asynchronous user agents using async functions.

from user_agent_sdk import user_agent


@user_agent()
async def sum_agent():
    # async processing logic here
    pass

High workload Handling

The SDK can handle high workloads by processing multiple tasks concurrently (vertical scaling), or by running multiple instances of the user agent (horizontal scaling) in different machines.

To increase concurrency workers, use the --workers or -w flag when running the user agent:

# Spawn 4 concurrent workers for handling tasks for a single user agent
useragent run your_agent.py --workers 4

Alternatively, set the workers parameter in the user_agent decorator:

from user_agent_sdk import user_agent


@user_agent(workers=4)
def sum_agent():
    # processing logic here
    pass

If both workers flag and parameter are set, the flag takes precedence.

Multiple User Agents

You can define multiple user agents in a single script by using the user_agent decorator multiple times with different agent_ids.

from user_agent_sdk import user_agent


@user_agent(agent_id="sum agent id")
def sum_agent():
    # processing logic here
    pass


@user_agent(agent_id="minus agent id")
def minus_agent():
    # processing logic here
    pass

Run multiple user agents in one script/project is possible but not recommended. You should keep one user agent per script/project for better maintainability.

Execution History

The SDK automatically records execution history for each task when enabled, allowing you to monitor and debug agent executions.

Enable Execution History Recording

Use the --record-execution-logs or -r flag when running your agent:

useragent run your_agent.py -r

This will create a local SQLite database (execution_history.db) that stores:

• Task ID
• Agent ID and User Agent ID
• Start and end timestamps
• Execution status (success/error)
• Input and output data
• Error messages (if any)

View Execution History

Display a summary of recent executions:

# Show last 50 executions
useragent history

# Filter by agent ID
useragent history --agent-id "your-agent-id"

# Filter by user agent ID
useragent history --user-agent-id "user123"

# Limit number of records
useragent history --limit 100

# Use custom database path
useragent history --db-path /path/to/custom.db

View Detailed Execution Information

To see detailed information about a specific execution, including formatted input/output JSON:

# Show details for execution ID 1
useragent history-detail 1

# Or use the short alias
useragent hd 1

# With custom database path
useragent hd 5 --db-path /path/to/custom.db

The detail view displays:

• Complete execution metadata (Task ID, Agent ID, timestamps, status)
• Error messages (if any)
• Input data - Pretty-printed JSON with syntax highlighting
• Output data - Pretty-printed JSON with syntax highlighting

This is particularly useful for:

• Debugging failed executions
• Analyzing task inputs and outputs
• Monitoring agent performance
• Auditing agent activities

License

Apache License 2.0