Integration Examples

Integration Examples

Example 1: Python with Requests

import requests
import json

# Configuration
API_URL = "https://agent.stactize.com/"
API_KEY = "YOUR_API_KEY_HERE"  # Obtain from andre.witte@1nebula.com
USER_ID = "user-12345"  # Your end-user identifier

def research_company(company_name: str, user_id: str) -> dict:
    """Research a SaaS company using the agent API."""

    headers = {
        "x-api-key": API_KEY,
        "x-user-id": user_id,
        "Content-Type": "application/json"
    }

    payload = {
        "jsonrpc": "2.0",
        "method": "message/send",
        "params": {
            "message": {
                "messageId": f"msg-{company_name}-{user_id}",
                "role": "user",
                "parts": [
                    {
                        "type": "text",
                        "text": f"Research {company_name} and provide comprehensive analysis"
                    }
                ]
            }
        },
        "id": 1
    }

    try:
        response = requests.post(
            API_URL,
            headers=headers,
            json=payload,
            timeout=300  # 5 minute timeout
        )
        response.raise_for_status()

        result = response.json()

        # Extract the research report from artifacts
        if "result" in result and "artifacts" in result["result"]:
            artifacts = result["result"]["artifacts"]
            for artifact in artifacts:
                if artifact.get("name") == "saas_research_report":
                    report = artifact["parts"][0]["text"]
                    return {
                        "success": True,
                        "company": company_name,
                        "report": report,
                        "task_id": result["result"]["id"]
                    }

        return {
            "success": False,
            "error": "No research report found in response"
        }

    except requests.exceptions.HTTPError as e:
        if e.response.status_code == 401:
            return {"success": False, "error": "Invalid API key"}
        elif e.response.status_code == 403:
            return {"success": False, "error": "API key forbidden or quota exceeded"}
        elif e.response.status_code == 429:
            return {"success": False, "error": "Rate limit exceeded"}
        else:
            return {"success": False, "error": f"HTTP error: {e}"}
    except requests.exceptions.Timeout:
        return {"success": False, "error": "Request timeout (>300s)"}
    except Exception as e:
        return {"success": False, "error": f"Unexpected error: {e}"}

# Usage
result = research_company("Salesforce", USER_ID)
if result["success"]:
    print(f"Research Report:\n{result['report']}")
else:
    print(f"Error: {result['error']}")

Example 2: Node.js/TypeScript

import axios, { AxiosError } from 'axios';

interface ResearchRequest {
  company: string;
  userId: string;
}

interface ResearchResponse {
  success: boolean;
  company?: string;
  report?: string;
  taskId?: string;
  error?: string;
}

const API_URL = 'https://agent.stactize.com/';
const API_KEY = process.env.SAAS_RESEARCH_API_KEY; // Store in env

async function researchCompany(
  company: string,
  userId: string
): Promise<ResearchResponse> {

  const headers = {
    'x-api-key': API_KEY,
    'x-user-id': userId,
    'Content-Type': 'application/json',
  };

  const payload = {
    jsonrpc: '2.0',
    method: 'message/send',
    params: {
      message: {
        messageId: `msg-${company}-${userId}`,
        role: 'user',
        parts: [
          {
            type: 'text',
            text: `Research ${company} and provide comprehensive analysis`,
          },
        ],
      },
    },
    id: 1,
  };

  try {
    const response = await axios.post(API_URL, payload, {
      headers,
      timeout: 300000, // 5 minutes
    });

    const result = response.data;

    // Extract research report from artifacts
    if (result.result?.artifacts) {
      const artifact = result.result.artifacts.find(
        (a: any) => a.name === 'saas_research_report'
      );

      if (artifact?.parts?.[0]?.text) {
        return {
          success: true,
          company,
          report: artifact.parts[0].text,
          taskId: result.result.id,
        };
      }
    }

    return {
      success: false,
      error: 'No research report found in response',
    };

  } catch (error) {
    if (axios.isAxiosError(error)) {
      const axiosError = error as AxiosError;

      switch (axiosError.response?.status) {
        case 401:
          return { success: false, error: 'Invalid API key' };
        case 403:
          return { success: false, error: 'API key forbidden or quota exceeded' };
        case 429:
          return { success: false, error: 'Rate limit exceeded' };
        default:
          return {
            success: false,
            error: `HTTP error: ${axiosError.message}`,
          };
      }
    }

    return {
      success: false,
      error: `Unexpected error: ${error}`,
    };
  }
}

// Usage
const result = await researchCompany('Salesforce', 'user-12345');
if (result.success) {
  console.log(`Research Report:\n${result.report}`);
} else {
  console.error(`Error: ${result.error}`);
}

Example 3: cURL (Testing)

#!/bin/bash

# Configuration
API_URL="https://agent.stactize.com/"
API_KEY="YOUR_API_KEY_HERE"
USER_ID="user-12345"
COMPANY="Salesforce"

# Make request
curl -X POST "$API_URL" \
  -H "x-api-key: $API_KEY" \
  -H "x-user-id: $USER_ID" \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"method\": \"message/send\",
    \"params\": {
      \"message\": {
        \"messageId\": \"msg-$COMPANY-$USER_ID\",
        \"role\": \"user\",
        \"parts\": [
          {
            \"type\": \"text\",
            \"text\": \"Research $COMPANY and provide comprehensive analysis\"
          }
        ]
      }
    },
    \"id\": 1
  }" \
  --max-time 300

Example 4: A2A Protocol (Agent-to-Agent)

from a2a import A2AClient

# Configuration
AGENT_URL = "https://saas-research-a2a-759220049011.europe-west4.run.app"
API_KEY = "YOUR_API_KEY_HERE"

async def research_via_a2a(company: str) -> str:
    """Research using A2A protocol."""

    # Create A2A client
    client = A2AClient(
        agent_url=AGENT_URL,
        api_key=API_KEY  # If using API Gateway
    )

    # Send message
    response = await client.send_message(
        f"Research {company} and provide competitive analysis"
    )

    # Extract report from artifacts
    if response.artifacts:
        report_artifact = next(
            (a for a in response.artifacts if a.name == "saas_research_report"),
            None
        )
        if report_artifact:
            return report_artifact.parts[0].text

    return "No report generated"

# Usage
report = await research_via_a2a("Salesforce")
print(report)