Package Exports

@agentorc/sdk

Readme

AgentOrc SDK

The official SDK for AgentOrc - AI agent orchestration platform. Build, deploy, and manage intelligent agents with powerful tool integration capabilities.

📚 Documentation

For LLMs and AI Assistants:

📄 llms.txt - Documentation index for AI systems
📖 llms-full.txt - Complete documentation text
📂 docs/ - Full documentation in Markdown format

For Developers:

🚀 Getting Started - Installation and first agent
🔐 Authentication - API keys and credentials
🛠️ Setting Up Agents & Tools - Configuration guide
💻 Execution & Client Usage - Runtime operations
📝 Code Examples - Real-world examples
📋 SDK Reference - Complete API reference
🗺️ Documentation Map - Navigation guide

✨ Features

🤖 Agent Management: Create, update, and deploy AI agents with custom configurations
🛠️ Tool Integration: Connect agents to external APIs, databases, and services
📊 Execution Tracking: Monitor agent performance with detailed execution traces
🔄 Real-time SSE: Server-Sent Events for live execution updates (step tracking, progress, clarifications)
💬 Runtime Variables: Dynamic variable resolution with automatic SSE communication
🎯 Type Safety: Full TypeScript support with auto-generated types
🔧 CLI Tools: Comprehensive command-line interface for agent management
📈 Debug & Analytics: Built-in debugging and performance monitoring
🔐 Secure: Enterprise-grade security with API key authentication

🚀 Quick Start

Installation

npm install agentorc

After installation, initialize your first project:

npx agentorc init

Basic Usage

const { AgentOrc } = require('agentorc');

const agentorc = new AgentOrc({
  apiKey: process.env.AGENTORC_API_KEY,
  agentId: process.env.AGENTORC_AGENT_ID
});

// Execute a query
const result = await agentorc.execute({
  query: "What's the weather like today?",
  sessionId: "user-123"
});

console.log(result.result);

Real-Time Execution Tracking with SSE

Track your agent's execution in real-time with automatic Server-Sent Events:

const { AgentOrc } = require('agentorc');

const client = new AgentOrc({
  apiKey: process.env.AGENTORC_API_KEY,
  debug: true // Enable to see all SSE events
});

// Subscribe to execution events
client.events.onExecutionStart((event) => {
  console.log('Execution started:', event.executionId);
});

client.events.onStepStart((event) => {
  console.log('Tool started:', event.toolName);
});

client.events.onStepComplete((event) => {
  console.log('Tool completed:', event.toolName);
});

client.events.onProgress((event) => {
  console.log(`Progress: ${event.message} (${event.percentage}%)`);
});

client.events.onClarificationNeeded(async (event) => {
  console.log('Agent needs clarification:', event.question);
  // Provide clarification to continue execution
  const answer = await getUserInput(event.question);
  await client.processClarification(event.executionId, answer);
});

// Execute with runtime variable support
const result = await client.execute({
  agentId: 'agent-123',
  query: 'Send email to team@example.com',
  onVariableRequest: async (request) => {
    // Provide runtime variables when requested
    return {
      smtp_password: process.env.SMTP_PASSWORD,
      from_email: 'notifications@myapp.com'
    };
  }
});

Features:

✅ Automatic SSE connection for real-time updates
✅ Track each tool execution (started, completed, failed)
✅ Monitor progress with percentage and step counts
✅ Handle and respond to clarification requests mid-execution
✅ Automatic fallback to polling if SSE unavailable
✅ Event-based API for clean code organization

Available Methods:

client.execute() - Execute an agent query
client.processClarification(executionId, response) - Respond to clarification requests
client.getConnectionInfo() - Get current connection status

👉 Complete SSE Guide - Learn about all available events and advanced features

📋 Prerequisites

Node.js 14.0.0 or higher
AgentOrc API key (get one at agentorc.com)

🛠️ CLI Commands

The AgentOrc SDK comes with a powerful CLI for managing agents and tools:

Project Setup

# Initialize a new project with guided setup
npx agentorc init

# Initialize without the wizard (basic setup)
npx agentorc init --no-wizard

# Login with your API key
npx agentorc login

# Create an agent from configuration
npx agentorc create-agent

Agent Management

# List all agents
npx agentorc list-agents

# Update an existing agent
npx agentorc update-agent

# Delete an agent
npx agentorc delete-agent --id <agent-id>

Tool Configuration

# Configure tools for an agent
npx agentorc config-tool

# List tools for an agent
npx agentorc list-tools

# Import tools from OpenAPI specification
npx agentorc import-tools --file openapi.json

# Delete a tool
npx agentorc delete-tool --name <tool-name>

Configuration Management

# Show differences between local and remote configuration
npx agentorc diff

# Apply configuration changes
npx agentorc migrate

# Pull configuration from remote agent
npx agentorc migration --pull

# Push local configuration to remote
npx agentorc migration --push

Development Tools

# Generate TypeScript types from configuration
npx agentorc generate-types

# View execution traces for debugging
npx agentorc debug:trace <execution-id>

# List available execution traces
npx agentorc debug:list

📖 Configuration

Agent Configuration (`agentorc.config.js`)

module.exports = {
  agent: {
    name: "MyAgent",
    description: "A helpful AI assistant",
    capabilities: ["answer_questions", "process_data"],
    config: {
      llm_provider: "openai",
      openai: {
        model: "gpt-4",
        temperature: 0.7,
        max_tokens: 2000
      }
    },
    system_prompt: "You are a helpful AI assistant...",
    input_schema: {
      dataType: "object",
      metadata: {
        properties: {
          query: { type: "string", description: "User query" }
        },
        required: ["query"]
      }
    }
  },
  tools: [
    {
      name: "weather_api",
      type: "http",
      description: "Get weather information",
      parameters: {
        type: "object",
        properties: {
          location: { type: "string" },
          units: { type: "string", enum: ["metric", "imperial"] }
        },
        required: ["location"]
      },
      configuration: {
        baseUrl: "https://api.weather.com",
        endpoint: "/current"
      },
      authentication: {
        type: "apikey",
        headerName: "X-API-Key",
        envVar: "WEATHER_API_KEY"
      }
    }
  ]
};

Environment Variables

Create a .env file in your project root:

AGENTORC_API_KEY=your_api_key_here
AGENTORC_AGENT_ID=your_agent_id_here
WEATHER_API_KEY=your_weather_api_key

💻 SDK Usage

Initialize the Client

const { AgentOrc } = require('agentorc');

const agentorc = new AgentOrc({
  apiKey: process.env.AGENTORC_API_KEY,
  agentId: process.env.AGENTORC_AGENT_ID,
  baseUrl: 'https://api.agentorc.com/v1', // optional
  debug: true, // enable debugging
  timeout: 30000, // request timeout in ms
  maxRetries: 3 // max retry attempts
});

Execute Queries

// Simple execution
const result = await agentorc.execute({
  query: "What's the capital of France?",
  sessionId: "session-123",
  metadata: { source: "web-app" }
});

// With streaming
const stream = agentorc.executeStream({
  query: "Tell me a story",
  sessionId: "session-123"
}, {
  onUpdate: (content) => console.log('Streaming:', content),
  onComplete: (result) => console.log('Complete:', result),
  onError: (error) => console.error('Error:', error)
});

Tool Execution

// Execute a specific tool
const toolResult = await agentorc.executeTool(
  executionId,
  'weather_api',
  { location: 'New York', units: 'metric' }
);

Debugging and Monitoring

// Initialize with debug options
const agentorc = new AgentOrc({
  apiKey: process.env.AGENTORC_API_KEY,
  debug: {
    enabled: true,
    level: 'debug',
    logToFile: true,
    traceDirectory: './traces',
    performance: {
      enabled: true,
      includeMemoryMetrics: true
    }
  }
});

// Get execution traces
const trace = agentorc.getTrace(executionId);
const metrics = agentorc.getPerformanceMetrics(executionId);

🔧 TypeScript Support

Generate TypeScript definitions from your configuration:

npx agentorc generate-types --output ./src/types

Then use typed interfaces in your code:

import { AgentOrc } from 'agentorc';
import { AgentInput, AgentOutput, ToolParams } from './types';

const agentorc = new AgentOrc({ /* ... */ });

const result = await agentorc.execute<AgentInput, AgentOutput>({
  input: { query: "Hello world" }
});

// result.typedResult is now typed as AgentOutput

🏗️ Project Structure

When you initialize a new project, the following structure is created:

my-agent-project/
├── .agentorc/           # SDK state and configuration
│   ├── agent.json       # Agent state
│   ├── tools.json       # Tool states
│   └── traces/          # Execution traces
├── .env                 # Environment variables
├── .gitignore          # Git ignore file
├── agentorc.config.js  # Agent configuration
├── index.js            # Main application file
└── package.json        # Project dependencies

🔄 Migration and Versioning

The SDK supports configuration migration between environments:

# Compare local config with remote
npx agentorc diff

# Apply changes with dry-run
npx agentorc migrate --dry-run

# Apply changes
npx agentorc migrate

# Pull configuration from production
npx agentorc migration --pull --agent-id prod-agent-123

# Push configuration to staging
npx agentorc migration --push --comment "Updated system prompt"

🐛 Debugging

Execution Traces

View detailed execution traces:

# List recent traces
npx agentorc debug:list

# View specific trace
npx agentorc debug:trace <execution-id>

# Export trace to file
npx agentorc debug:trace <execution-id> --format json --output trace.json

Performance Monitoring

Monitor agent performance:

const agentorc = new AgentOrc({
  apiKey: process.env.AGENTORC_API_KEY,
  debug: {
    enabled: true,
    performance: {
      enabled: true,
      sampleRate: 1.0,
      includeHttpMetrics: true,
      includeMemoryMetrics: true
    }
  }
});

// Performance metrics are automatically collected
const metrics = agentorc.getPerformanceMetrics(executionId);
console.log('Total duration:', metrics.totalDuration);
console.log('Memory usage:', metrics.peakMemoryUsage);

📚 Examples

Basic Chat Agent

const { AgentOrc } = require('agentorc');

class ChatBot {
  constructor() {
    this.agentorc = new AgentOrc({
      apiKey: process.env.AGENTORC_API_KEY,
      agentId: process.env.AGENTORC_AGENT_ID
    });
  }

  async chat(message, sessionId) {
    const result = await this.agentorc.execute({
      query: message,
      sessionId,
      metadata: { timestamp: new Date().toISOString() }
    });

    return result.result;
  }
}

const bot = new ChatBot();
const response = await bot.chat("Hello!", "user-123");
console.log(response);

Streaming Response

const stream = agentorc.executeStream({
  query: "Write a detailed explanation of quantum computing"
}, {
  onUpdate: (chunk) => {
    process.stdout.write(chunk);
  },
  onComplete: (result) => {
    console.log('\n\nExecution completed!');
    console.log('Total duration:', result.durationMs + 'ms');
  },
  onError: (error) => {
    console.error('Stream error:', error);
  }
});

// Cancel stream if needed
setTimeout(() => stream.cancel(), 10000);

Tool Integration

// Configure a custom tool
const toolConfig = {
  name: "database_query",
  type: "http",
  description: "Query the database",
  parameters: {
    type: "object",
    properties: {
      query: { type: "string" },
      table: { type: "string" }
    },
    required: ["query"]
  },
  configuration: {
    baseUrl: "https://api.mydb.com",
    endpoint: "/query"
  },
  authentication: {
    type: "bearer",
    envVar: "DB_API_TOKEN"
  }
};

// Add tool via CLI
// npx agentorc config-tool --tool database_query

🔐 Security

Always store API keys in environment variables, never in code
Use .env files for local development
Set appropriate file permissions: chmod 600 .env
Regularly rotate API keys
Monitor usage and set up alerts for unusual activity

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

📖 Documentation - Complete SDK documentation
🤖 For AI/LLMs - AI-optimized documentation
💬 Discord Community
🐛 Issue Tracker
📧 Email Support
🌐 Website

🗺️ Roadmap

WebSocket support for real-time agent communication
Agent marketplace integration
Advanced workflow orchestration
Multi-agent collaboration features
Enhanced monitoring and analytics dashboard
GraphQL API support

Made with ❤️ by the AgentOrc team

@agentorc/sdk