Getting Started

Everything you need to begin working with Murphbeck AI systems. This guide covers initial setup, authentication, and your first API call.

Quick Start

Murphbeck AI systems are designed for rapid deployment. Follow these steps to get your first agent running:

Obtain API Credentials

Contact your account manager or request access through the dashboard to receive your API key and organization ID.
Install the SDK

Install our official SDK for your preferred language. We support Python, Node.js, and Go.
Configure Authentication

Set your API key as an environment variable or pass it directly to the client constructor.
Make Your First Request

Initialize an agent and send your first task to verify everything is working correctly.

Installation

Python

# Install via pip
pip install murphbeck-ai

# Or with poetry
poetry add murphbeck-ai
        

Node.js

# Install via npm
npm install @murphbeck/ai-sdk

# Or with yarn
yarn add @murphbeck/ai-sdk
        

Go

// Install via go get
go get github.com/murphbeck/ai-sdk-go
        

Authentication

All API requests require authentication using your API key. We recommend storing your key as an environment variable:

# Set environment variable
export MURPHBECK_API_KEY="your-api-key-here"
export MURPHBECK_ORG_ID="your-org-id"
        

Security Note

Never commit API keys to version control. Use environment variables or a secrets manager in production.

Hello World Example

Here's a minimal example to verify your setup is working:

from murphbeck import Client, Agent

# Initialize the client
client = Client()

# Create a simple agent
agent = Agent(
    name="HelloAgent",
    description="A simple greeting agent",
    capabilities=["text_generation"]
)

# Execute a task
response = agent.run("Say hello to the user")
print(response.output)
# Output: Hello! How can I assist you today?
        

Next Steps

Explore the Architecture section to understand system design
Check the API Reference for complete endpoint documentation
Review Integration Guide for connecting to your existing systems
Read Governance & Safety for compliance requirements

Architecture

Technical architecture documentation for Murphbeck AI systems, including system design, component interactions, and data flow.

System Overview

Murphbeck AI systems follow a modular, layered architecture designed for scalability, security, and maintainability. The core components are:

High-Level Architecture

Client

Your App

→

Gateway

API Layer

→

Core

Agent OS

→

Models

LLM Layer

Core Components

1. API Gateway

The API Gateway handles all incoming requests, providing:

Request authentication and authorization
Rate limiting and quota management
Request routing to appropriate services
Response caching where applicable
Request/response logging for audit trails

2. Agent Operating System (AgentOS)

The AgentOS is the central orchestration layer that manages agent lifecycles, task execution, and resource allocation.

// AgentOS Configuration Schema
{
  "agent_config": {
    "name": "AEGIS.EXE",
    "version": "2.1.0",
    "capabilities": [
      "code_analysis",
      "documentation",
      "security_review"
    ],
    "resource_limits": {
      "max_tokens": 8192,
      "timeout_seconds": 300,
      "max_concurrent_tasks": 5
    },
    "safety": {
      "requires_approval": false,
      "audit_log": true,
      "sandboxed": true
    }
  }
}
        

3. Model Layer

The Model Layer provides abstraction over multiple LLM providers, enabling:

Provider-agnostic agent development
Automatic fallback and load balancing
Cost optimization through intelligent routing
Consistent response formatting

4. Memory & Context Management

Agents maintain context through our proprietary memory system:

Memory Type	Scope	Persistence	Use Case
Working Memory	Single task	Ephemeral	Current task context
Session Memory	User session	Session-bound	Conversation history
Long-term Memory	Organization	Persistent	Knowledge base, preferences
Shared Memory	Multi-agent	Configurable	Cross-agent collaboration

Data Flow

A typical request flows through the system as follows:

Ingestion: Request received at API Gateway, authenticated and validated
Routing: Request routed to appropriate agent based on task type
Context Loading: Agent loads relevant memory and context
Execution: Agent processes task, potentially calling sub-agents or tools
Validation: Response validated against safety constraints
Response: Formatted response returned to client
Logging: Complete audit trail recorded

Performance Note

Average end-to-end latency for simple tasks is under 500ms. Complex multi-agent workflows typically complete within 5-15 seconds.

Scalability

The architecture is designed for horizontal scaling:

Stateless API Gateway instances behind load balancer
Agent workers scale based on queue depth
Memory layer uses distributed caching (Redis cluster)
Model calls distributed across provider quotas

API Reference

Complete API documentation for all Murphbeck AI endpoints. All endpoints require authentication via API key.

Base URL

https://api.murphbecktechnologies.com/v1

Authentication

Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY
X-Organization-ID: YOUR_ORG_ID
        

Agents

POST /agents

Create a new agent with specified capabilities and configuration.

Request Body:

{
  "name": "CustomerSupportAgent",
  "description": "Handles customer inquiries",
  "capabilities": ["text_generation", "sentiment_analysis"],
  "model": "claude-3-opus",
  "temperature": 0.7,
  "max_tokens": 4096
}
            

Response:

{
  "id": "agent_abc123",
  "name": "CustomerSupportAgent",
  "status": "active",
  "created_at": "2025-01-15T10:30:00Z"
}
            

GET /agents/{agent_id}

Retrieve details about a specific agent.

Parameters:

Name	Type	Description
agent_id	string	Unique agent identifier

DELETE /agents/{agent_id}

Deactivate and archive an agent. This action cannot be undone.

Tasks

POST /agents/{agent_id}/tasks

Submit a task to an agent for execution.

Request Body:

{
  "input": "Analyze the sentiment of these customer reviews",
  "context": {
    "reviews": ["Great product!", "Not what I expected"]
  },
  "async": false,
  "callback_url": "https://your-app.com/webhook"
}
            

Response:

{
  "task_id": "task_xyz789",
  "status": "completed",
  "output": {
    "sentiment_summary": "Mixed - 1 positive, 1 negative",
    "details": [...]
  },
  "usage": {
    "tokens": 1250,
    "latency_ms": 842
  }
}
            

GET /tasks/{task_id}

Check the status of an async task.

Memory

POST /memory/store

Store information in the agent's long-term memory.

Request Body:

{
  "agent_id": "agent_abc123",
  "key": "company_policy",
  "value": "Return policy: 30 days full refund...",
  "ttl_days": 365
}
            

GET /memory/search

Search agent memory using semantic queries.

Query Parameters:

Name	Type	Description
agent_id	string	Agent to search
query	string	Semantic search query
limit	integer	Max results (default: 10)

Error Codes

Code	Description
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Insufficient permissions
404	Not Found - Resource doesn't exist
429	Rate Limited - Too many requests
500	Server Error - Contact support

Integration Guide

Step-by-step guides for integrating Murphbeck AI into your existing technology stack.

Supported Integrations

Murphbeck AI provides native integrations with popular platforms and frameworks:

Category	Platforms	Status
CRM	Salesforce, HubSpot, Pipedrive	GA
Communication	Slack, Microsoft Teams, Discord	GA
E-commerce	Shopify, WooCommerce, BigCommerce	GA
Helpdesk	Zendesk, Intercom, Freshdesk	GA
Database	PostgreSQL, MongoDB, Supabase	GA
Cloud	AWS, GCP, Azure	GA

Slack Integration

Deploy an AI agent directly into your Slack workspace:

Create Slack App

Go to api.slack.com/apps and create a new app. Enable Socket Mode for real-time messaging.
Configure Bot Permissions

Add OAuth scopes: app_mentions:read, chat:write, channels:history, im:history.
Set Up Webhook

Configure your Murphbeck webhook endpoint to receive Slack events.
Deploy Agent

Link your agent to the Slack integration in the Murphbeck dashboard.

# Slack integration configuration
from murphbeck.integrations import SlackIntegration

slack = SlackIntegration(
    bot_token="xoxb-your-token",
    signing_secret="your-signing-secret",
    agent_id="agent_abc123"
)

# Define trigger keywords
slack.configure(
    trigger_on_mention=True,
    trigger_keywords=["help", "question"],
    response_channels=["#support", "#general"]
)

slack.start()
        

Webhook Configuration

For custom integrations, configure webhooks to receive real-time updates:

// Webhook payload structure
{
  "event": "task.completed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "task_id": "task_xyz789",
    "agent_id": "agent_abc123",
    "status": "completed",
    "output": {...}
  },
  "signature": "sha256=..."
}
        

Security Requirement

Always verify webhook signatures before processing. Reject requests with invalid or missing signatures.

Database Connection

Connect agents to your database for context-aware responses:

from murphbeck.connectors import DatabaseConnector

# PostgreSQL connection
db = DatabaseConnector(
    type="postgresql",
    host="your-db-host.com",
    database="production",
    credentials_secret="db-creds-secret-id"
)

# Grant agent read-only access to specific tables
db.grant_access(
    agent_id="agent_abc123",
    tables=["customers", "orders", "products"],
    permissions=["SELECT"]  # Read-only
)
        

Custom Tools

Extend agent capabilities by registering custom tools:

from murphbeck import Tool, Agent

# Define a custom tool
@Tool(
    name="check_inventory",
    description="Check product inventory levels"
)
def check_inventory(product_id: str) -> dict:
    # Your inventory logic here
    return {
        "product_id": product_id,
        "in_stock": True,
        "quantity": 42
    }

# Register tool with agent
agent = Agent(id="agent_abc123")
agent.register_tool(check_inventory)
        

Governance & Safety

Policies, safety frameworks, and compliance documentation for responsible AI deployment.

Safety Framework

Murphbeck AI systems implement multiple layers of safety controls to ensure responsible operation:

1. Input Validation

All inputs are validated and sanitized before processing:

Content filtering for harmful requests
Injection attack prevention
Rate limiting per user/organization
Input length and complexity bounds

2. Output Guardrails

Agent outputs pass through safety checks before delivery:

PII detection and redaction
Harmful content filtering
Factuality verification (where applicable)
Compliance boundary enforcement

3. Capability Boundaries

Agents are restricted to explicitly granted capabilities:

// Safety configuration
{
  "safety": {
    "allowed_capabilities": [
      "text_generation",
      "data_analysis"
    ],
    "denied_capabilities": [
      "code_execution",
      "external_api_calls"
    ],
    "requires_human_approval": [
      "financial_transactions",
      "data_deletion"
    ],
    "max_autonomous_actions": 10,
    "escalation_threshold": 0.8
  }
}
        

Access Control

Role-based access control (RBAC) governs all system access:

Role	Permissions	Typical User
Viewer	Read agent outputs, view dashboards	Business user
Operator	Run tasks, manage sessions	Support team
Developer	Create/modify agents, integrations	Engineering
Admin	Full access, user management	IT/Security
Auditor	Read-only access to all logs	Compliance

Audit Logging

All agent actions are logged for compliance and debugging:

// Audit log entry structure
{
  "timestamp": "2025-01-15T10:30:00.000Z",
  "event_id": "evt_12345",
  "event_type": "task.executed",
  "agent_id": "agent_abc123",
  "user_id": "user_xyz",
  "organization_id": "org_456",
  "input_hash": "sha256:abc...",
  "output_hash": "sha256:def...",
  "tokens_used": 1250,
  "latency_ms": 842,
  "safety_checks_passed": true,
  "ip_address": "192.168.1.1"
}
        

Retention Policy

Audit logs are retained for 90 days by default. Enterprise customers can configure extended retention up to 7 years for compliance requirements.

Compliance

Murphbeck AI systems are designed to support compliance with:

SOC 2 Type II: Security, availability, and confidentiality controls
GDPR: Data protection and privacy for EU users
CCPA: California consumer privacy requirements
HIPAA: Healthcare data protection (Enterprise tier)
PCI DSS: Payment card data security (with configuration)

Incident Response

In case of security incidents or safety violations:

Automatic agent suspension for critical violations
Real-time alerts to designated security contacts
Full incident logging with forensic data capture
Documented remediation and post-mortem process

Reporting Issues

Report security vulnerabilities to security@murphbecktechnologies.com. Do not disclose publicly until resolved.

Operations

Runbooks and procedures for deploying, monitoring, and maintaining Murphbeck AI systems.

Deployment

Murphbeck AI can be deployed in multiple configurations:

Deployment Model	Description	Best For
Cloud (SaaS)	Fully managed on Murphbeck infrastructure	Most customers
VPC	Dedicated instance in your cloud VPC	Data residency needs
On-Premise	Self-hosted on your infrastructure	Air-gapped environments
Hybrid	Control plane cloud, agents on-prem	Edge deployments

Cloud Deployment

For standard cloud deployment, no infrastructure management is required. Simply:

Create your organization in the dashboard
Configure agents via API or UI
Integrate with your applications

VPC Deployment

For VPC deployment, provide:

AWS/GCP/Azure account access
VPC configuration and subnet details
Security group requirements
DNS and certificate requirements

Monitoring

Monitor system health through the dashboard or API:

Key Metrics

Metric	Description	Alert Threshold
Latency (p50/p95/p99)	Response time percentiles	p99 > 5s
Error Rate	Failed requests / total	> 1%
Token Usage	Tokens consumed per period	> 90% quota
Active Agents	Agents currently processing	Varies
Queue Depth	Pending tasks in queue	> 1000

Dashboard Widgets

// Fetch metrics via API
GET /metrics?agent_id=agent_abc123&period=24h

// Response
{
  "latency": {
    "p50": 245,
    "p95": 890,
    "p99": 1450
  },
  "requests": {
    "total": 15420,
    "success": 15312,
    "failed": 108
  },
  "tokens": {
    "input": 2450000,
    "output": 980000
  }
}
        

Alerting

Configure alerts for critical conditions:

# Alert configuration (YAML)
alerts:
  - name: high_error_rate
    condition: error_rate > 0.01
    window: 5m
    severity: critical
    channels:
      - slack:#ops-alerts
      - pagerduty:team-ai

  - name: quota_warning
    condition: token_usage > quota * 0.8
    window: 1h
    severity: warning
    channels:
      - email:billing@company.com
        

Maintenance Procedures

Agent Updates

Review Changes

Check release notes and breaking changes in the changelog.
Test in Staging

Deploy to staging environment and run integration tests.
Canary Deployment

Route 10% of traffic to new version, monitor for issues.
Full Rollout

Gradually increase traffic to 100% over 30 minutes.
Verify & Document

Confirm metrics are stable, update runbooks if needed.

Rollback Procedure

# Emergency rollback command
murphbeck agents rollback agent_abc123 --to-version 2.0.1

# Or via API
POST /agents/agent_abc123/rollback
{
  "target_version": "2.0.1",
  "reason": "Elevated error rate after 2.1.0 deployment"
}
        

Troubleshooting

Common Issues

Symptom	Possible Cause	Resolution
401 Unauthorized	Invalid or expired API key	Regenerate API key in dashboard
429 Rate Limited	Exceeded request quota	Implement backoff, upgrade plan
Slow responses	Complex tasks, high load	Optimize prompts, add caching
Unexpected outputs	Insufficient context	Improve prompts, add examples
Integration failures	Webhook misconfiguration	Verify URL, check signatures

Support

For issues not covered here, contact support@murphbecktechnologies.com or use the in-dashboard chat.

Developer Documentation

Getting Started

Quick Start

Installation

Python

Node.js

Go

Authentication

Hello World Example

Next Steps

Architecture

System Overview

Core Components

1. API Gateway

2. Agent Operating System (AgentOS)

3. Model Layer

4. Memory & Context Management

Data Flow

Scalability

API Reference

Base URL

Authentication

Agents

Tasks

Memory

Error Codes

Integration Guide

Supported Integrations

Slack Integration

Webhook Configuration

Database Connection

Custom Tools

Governance & Safety

Safety Framework

1. Input Validation

2. Output Guardrails

3. Capability Boundaries

Access Control

Audit Logging

Compliance

Incident Response

Operations

Deployment

Cloud Deployment

VPC Deployment

Monitoring

Key Metrics

Dashboard Widgets

Alerting

Maintenance Procedures

Agent Updates

Rollback Procedure

Troubleshooting

Common Issues

Need custom documentation?