Agents Guide

What is an Agent?

A LyDos agent is an autonomous system that performs specialized tasks using AI, planning, and execution engines. Agents combine:

• Multi-step task planning and execution
• Tool invocation (file I/O, web search, API calls, etc.)
• Context awareness and memory
• Error recovery and retry strategies
• Human-in-the-loop feedback mechanisms

LyDos manages 100+ agents across 12 categories, each optimized for specific use cases. You can run any agent via the SDK, CLI, or API.

Agent Categories

Security & Vulnerability Detection (28 agents)

Security agents perform vulnerability scanning, dependency auditing, penetration testing, and compliance checks.

Deep Research & Analysis (24 agents)

Research agents gather information from web, academic sources, and trends to synthesize comprehensive reports.

Code Quality & Optimization (31 agents)

Code agents provide review, refactoring, testing, documentation, and performance optimization.

Data Science & Analytics (19 agents)

Data agents handle exploratory analysis, SQL optimization, pipeline design, and statistical modeling.

DevOps & Infrastructure (22 agents)

DevOps agents manage Kubernetes, Terraform, CI/CD pipelines, and container operations.

Running Agents

Via Python SDK

import asyncio
from lydos import LydosClient

async def main() -> None:
    async with LydosClient(
        base_url="http://localhost:8888",
        api_key="lyd_sk_your_key_here",
    ) as client:
        # Direct run — blocks until the agent finishes and returns the result
        # SPEC-001 = HARIKA Doruk (maps to /api/agents/SPEC-001/run)
        result = await client.run_agent(
            "SPEC-001",
            {
                "task": "Scan ./src for vulnerabilities",
                "path": "./src",
                "depth": "comprehensive",
                "include_deps": True,
            },
        )
        print(f"Status : {result.status}")
        print(f"Latency: {result.execution_time_ms} ms")
        if result.output:
            print("Output keys:", list(result.output.keys())[:5])

        # Q63 async task submission + polling for long-running work
        task = await client.submit_task(
            agent_type="SPEC-001",  # SPEC-001 = HARIKA Doruk
            payload={"task": "Deep scan", "path": "./src"},
        )
        while True:
            current = await client.get_task(task.task_id)
            if current.status in {"completed", "failed"}:
                print(f"Task {current.task_id}: {current.status}")
                break
            await asyncio.sleep(2)

asyncio.run(main())

Via TypeScript SDK

import { LydosClient, LydosClientError } from "@lydos/client";

const client = new LydosClient({
  baseURL: "http://localhost:8888",
  apiKey: process.env.LYDOS_API_KEY,
  timeout: 30_000,
  retry: {
    maxRetries: 3,
    baseDelayMs: 500,
    maxDelayMs: 5_000,
    retryableStatuses: [408, 429, 500, 502, 503, 504],
    jitter: true,
  },
});

try {
  // Kick off the agent asynchronously — returns taskId immediately
  // SPEC-001 = HARIKA Doruk (maps to /api/agents/SPEC-001/run)
  const queued = await client.runAgent("SPEC-001", {
    target: "./src",
    async: true,
  });
  console.log("queued:", queued.taskId, queued.status);

  // Or run it synchronously and block for the final output
  const result = await client.runAgent("SPEC-001", {
    target: "./src",
    async: false,
  });
  console.log("status:", result.status);
  console.log("output:", result.output);
} catch (err) {
  if (err instanceof LydosClientError) {
    console.error(`HTTP ${err.statusCode ?? "n/a"}: ${err.message}`);
  } else {
    throw err;
  }
}

Via CLI

# List every registered agent (Python + YAML)
lydos agent list

# Show details for a specific agent (id, status, capabilities)
lydos agent get SPEC-001

# Run an agent with a free-form task (SPEC-001 = HARIKA Doruk)
lydos agent run SPEC-001 "Scan ./src for vulnerabilities"

# Pass structured parameters (comma-separated key=value pairs)
lydos agent run SPEC-001 "Full audit" \
  --param depth=comprehensive,include_deps=true,path=./src

# Pin the LLM provider, model, or routing mode for this run
lydos agent run SPEC-001 "Refactor auth module" \
  --provider groq \
  --model nvidia/nemotron-super-49b-v1 \
  --mode deep

# Preview without executing, or auto-approve the run
lydos agent run SPEC-001 "Research AI trends" --dry-run
lydos agent run SPEC-001 "Research AI trends" --yes

Via API

# Real endpoint: POST /api/agents/{agent_type}/run
curl -X POST http://localhost:8888/api/agents/SPEC-001/run \
  -H "Authorization: Bearer lyd_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Scan ./src for vulnerabilities",
    "path": "./src",
    "depth": "comprehensive",
    "include_deps": true
  }'

Understanding Agent Parameters

Each agent has specific parameters that control its behavior. Parameters are passed when running the agent.

Common Parameters

Getting Agent Specifications

Before running an agent, check its parameter requirements:

# List every agent and inspect its capabilities
agents = await client.list_agents()

for info in agents:
    print(f"{info.agent_type:<24} status={info.status:<8} engine={info.engine or '-'}")
    print(f"  {info.description}")
    print(f"  capabilities: {info.capabilities}")

# Example record:
# AgentInfo(
#   agent_type='SPEC-001',
#   name='HARIKA Doruk',
#   description='Multi-stage project analysis agent',
#   status='idle',
#   capabilities=['scan', 'audit', 'refactor', 'security'],
#   engine='q29_agent_hub',
# )

Polling for Task Results

Agents run asynchronously. Use the task ID to poll for results.

Task Lifecycle

Polling Pattern

import asyncio
from lydos import LydosClient
from lydos.exceptions import LydosError

async def poll_agent() -> None:
    async with LydosClient(
        base_url="http://localhost:8888",
        api_key="lyd_sk_your_key_here",
    ) as client:
        # Q63 async task submission — returns immediately with a task_id
        task = await client.submit_task(
            agent_type="SPEC-001",  # SPEC-001 = HARIKA Doruk
            payload={"task": "Research the latest AI agent frameworks"},
        )

        max_wait = 600          # 10 minutes
        poll_interval = 2.0     # 2 seconds
        elapsed = 0.0

        while elapsed < max_wait:
            try:
                current = await client.get_task(task.task_id)
            except LydosError as exc:
                print(f"poll failed: {exc}")
                break

            if current.status == "completed":
                print(f"Done in {current.execution_time_ms} ms")
                print(f"Result : {current.result}")
                return
            if current.status == "failed":
                print(f"Failed : {current.error}")
                return

            print(f"status={current.status} elapsed={elapsed:.0f}s")
            await asyncio.sleep(poll_interval)
            elapsed += poll_interval

        print("Timeout waiting for task completion")

asyncio.run(poll_agent())

Best Practices