Agents API

Deploy, manage, and invoke AI agents programmatically using the REST API.

// Endpoints Overview

Method	Endpoint	Description
`GET`	`/v1/agents`	List all agents
`POST`	`/v1/agents`	Deploy a new agent
`GET`	`/v1/agents/:id`	Get agent details
`PATCH`	`/v1/agents/:id`	Update agent configuration
`DELETE`	`/v1/agents/:id`	Delete an agent
`POST`	`/v1/agents/:id/invoke`	Invoke (call) an agent
`POST`	`/v1/agents/:id/start`	Start a stopped agent
`POST`	`/v1/agents/:id/stop`	Stop a running agent
`POST`	`/v1/agents/:id/redeploy`	Redeploy with latest code
`GET`	`/v1/agents/:id/logs`	Stream agent logs
`GET`	`/v1/agents/:id/metrics`	Get agent metrics

// The Agent Object

{
  "id": "agent_abc123xyz",
  "name": "sentiment-analyzer",
  "display_name": "Sentiment Analyzer v2",
  "status": "running",
  "cloud_id": "cloud_def456",
  "version": "2.1.0",
  "created_at": "2024-01-10T08:00:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "deployed_at": "2024-01-15T14:30:00Z",

  "runtime": {
    "language": "python",
    "version": "3.11",
    "framework": "langchain"
  },

  "resources": {
    "cpu": 1,
    "memory_mb": 2048,
    "gpu": null
  },

  "scaling": {
    "min_instances": 1,
    "max_instances": 5,
    "current_instances": 2,
    "target_cpu_percent": 70
  },

  "endpoints": {
    "base_url": "https://my-cloud.shellhub.app/agents/sentiment-analyzer",
    "health": "/health",
    "invoke": "/invoke"
  },

  "health": {
    "status": "healthy",
    "last_check": "2024-01-15T15:00:00Z",
    "uptime_percent": 99.98
  },

  "metrics": {
    "requests_24h": 15234,
    "avg_latency_ms": 125,
    "error_rate_percent": 0.12
  },

  "source": {
    "type": "github",
    "repo": "user/sentiment-agent",
    "branch": "main",
    "commit": "a1b2c3d4"
  },

  "environment": {
    "OPENAI_API_KEY": "****",
    "LOG_LEVEL": "info"
  },

  "metadata": {
    "team": "nlp",
    "cost_center": "ai-001"
  }
}

Status Values

Status	Description
`created`	Agent created, awaiting deployment
`building`	Container image being built
`deploying`	Agent being deployed to infrastructure
`running`	Agent is live and accepting requests
`stopped`	Agent is stopped
`failed`	Deployment or runtime error

// Deploy Agent

POST/v1/agents

Deploys a new agent to a cloud. You can deploy from a GitHub repository, Docker image, or upload code directly.

Request Body

Field	Type	Required	Description
`name`	string	Yes	Unique name within the cloud
`cloud_id`	string	Yes	Cloud to deploy to
`source`	object	Yes	Deployment source (see below)
`runtime`	object	No	Runtime configuration
`resources`	object	No	CPU, memory, GPU allocation
`environment`	object	No	Environment variables
`scaling`	object	No	Auto-scaling configuration

Source Types

GitHub Repository

"source": {
  "type": "github",
  "repo": "username/repo-name",
  "branch": "main",
  "path": "agents/my-agent"  // optional subdirectory
}

Docker Image

"source": {
  "type": "docker",
  "image": "ghcr.io/user/my-agent:v1.0.0",
  "credentials": {
    "username": "user",
    "password": "${secrets.GITHUB_TOKEN}"
  }
}

Direct Upload

"source": {
  "type": "upload",
  "archive_url": "https://..."  // Pre-signed URL from /v1/uploads
}

Full Example

curl -X POST https://api.shellhub.app/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sentiment-analyzer",
    "cloud_id": "cloud_abc123",
    "source": {
      "type": "github",
      "repo": "myorg/sentiment-agent",
      "branch": "main"
    },
    "runtime": {
      "language": "python",
      "version": "3.11"
    },
    "resources": {
      "cpu": 2,
      "memory_mb": 4096
    },
    "environment": {
      "OPENAI_API_KEY": "${secrets.OPENAI_KEY}",
      "LOG_LEVEL": "info"
    },
    "scaling": {
      "min_instances": 1,
      "max_instances": 10,
      "target_cpu_percent": 70
    }
  }'

// Invoke Agent

POST/v1/agents/:id/invoke

Sends a request to your agent and returns the response. This is the primary way to interact with deployed agents.

Request Body

Field	Type	Description
`input`	any	Data to pass to the agent (format depends on agent)
`options`	object	Invocation options (timeout, headers, etc.)
`async`	boolean	Return immediately with job ID (default: false)

Synchronous Invocation

curl -X POST https://api.shellhub.app/v1/agents/agent_abc123/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "text": "I absolutely love this product! Best purchase ever.",
      "language": "en"
    }
  }'

Response

{
  "success": true,
  "data": {
    "output": {
      "sentiment": "positive",
      "confidence": 0.95,
      "emotions": {
        "joy": 0.85,
        "love": 0.72,
        "surprise": 0.15
      }
    },
    "usage": {
      "tokens_used": 125,
      "compute_ms": 234
    }
  },
  "meta": {
    "request_id": "req_xyz789",
    "latency_ms": 245,
    "instance_id": "inst_001"
  }
}

Async Invocation

For long-running operations, use async mode to avoid timeouts:

curl -X POST https://api.shellhub.app/v1/agents/agent_abc123/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "input": { "document": "..." },
    "async": true
  }'

# Response
{
  "success": true,
  "data": {
    "job_id": "job_xyz789",
    "status": "pending",
    "poll_url": "/v1/jobs/job_xyz789"
  }
}

// Streaming Responses

For agents that generate text (like LLM-based agents), you can stream the response as it's generated using Server-Sent Events (SSE):

curl -X POST https://api.shellhub.app/v1/agents/agent_abc123/invoke \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream" \
  -d '{ "input": { "prompt": "Write a poem about AI" } }'

# Response (SSE stream)
data: {"type":"start","request_id":"req_123"}

data: {"type":"chunk","content":"In"}
data: {"type":"chunk","content":" silicon"}
data: {"type":"chunk","content":" dreams"}
...
data: {"type":"done","usage":{"tokens":150}}

// Agent Logs

GET/v1/agents/:id/logs

Retrieve or stream logs from your agent. Supports both historical and real-time logs.

Query Parameters

Parameter	Type	Description
`since`	timestamp	Return logs after this time
`until`	timestamp	Return logs before this time
`tail`	integer	Number of recent lines to return
`follow`	boolean	Stream logs in real-time
`level`	string	Filter by level: debug, info, warn, error

# Get last 100 lines
curl "https://api.shellhub.app/v1/agents/agent_abc123/logs?tail=100" \
  -H "Authorization: Bearer YOUR_API_KEY"

# Stream logs in real-time
curl "https://api.shellhub.app/v1/agents/agent_abc123/logs?follow=true" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: text/event-stream"

// Agent Events

Configure webhooks to receive notifications about agent events:

Event	Description
`agent.deployed`	Agent successfully deployed
`agent.failed`	Deployment or runtime failure
`agent.scaled`	Auto-scaling event occurred
`agent.health_changed`	Health status changed