Agents API

The Agents API allows you to create, manage, and orchestrate AI agents within your Connix projects. Agents are autonomous entities that can execute tasks, process data, and interact with external services.

Base URL

All API requests should be made to:

https://api.connix.io/api/v1

Authentication

The Agents API requires authentication via API key or OAuth2 token:

# API Key
curl -H "X-API-Key: cx_your_api_key_here"

# OAuth2 Bearer Token
curl -H "Authorization: Bearer your_access_token_here"

Agent Object

{
  "id": "agent_1234567890abcdef",
  "name": "Data Analysis Agent",
  "description": "Processes customer data and generates insights",
  "project_id": "proj_1234567890abcdef",
  "status": "running",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 2048,
    "tools": ["web_search", "code_execution", "data_analysis"]
  },
  "metadata": {
    "created_by": "user_1234567890abcdef",
    "environment": "production",
    "version": "1.2.3"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:45:00Z",
  "last_activity": "2024-01-15T16:20:00Z"
}

Agent Status Values

Status	Description
creating	Agent is being initialized
running	Agent is active and available
paused	Agent is temporarily stopped
stopped	Agent has been stopped
error	Agent encountered an error
updating	Agent configuration is being updated

List Agents

Retrieve all agents in a project.

Request:

GET /projects/{project_id}/agents

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
status	string	No	Filter by agent status
limit	integer	No	Number of results (1-100, default: 20)
offset	integer	No	Offset for pagination (default: 0)
sort	string	No	Sort order: created_at, -created_at, name, -name

Example Request:

curl -X GET "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents?status=running&limit=10" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "agents": [
    {
      "id": "agent_1234567890abcdef",
      "name": "Data Analysis Agent",
      "description": "Processes customer data and generates insights",
      "project_id": "proj_1234567890abcdef",
      "status": "running",
      "config": {
        "model": "gpt-4",
        "temperature": 0.7,
        "max_tokens": 2048,
        "tools": ["web_search", "code_execution", "data_analysis"]
      },
      "metadata": {
        "created_by": "user_1234567890abcdef",
        "environment": "production",
        "version": "1.2.3"
      },
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T14:45:00Z",
      "last_activity": "2024-01-15T16:20:00Z"
    }
  ],
  "pagination": {
    "total": 45,
    "limit": 10,
    "offset": 0,
    "has_more": true
  }
}

Create Agent

Create a new agent in a project.

Request:

POST /projects/{project_id}/agents

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project

Request Body:

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries and support requests",
  "config": {
    "model": "gpt-4",
    "temperature": 0.3,
    "max_tokens": 1024,
    "tools": ["web_search", "knowledge_base"],
    "system_prompt": "You are a helpful customer support agent...",
    "environment_variables": {
      "SUPPORT_QUEUE": "high_priority",
      "ESCALATION_THRESHOLD": "3"
    }
  },
  "metadata": {
    "environment": "production",
    "team": "customer-success"
  }
}

Example Request:

curl -X POST "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents" \
  -H "X-API-Key: cx_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Handles customer inquiries and support requests",
    "config": {
      "model": "gpt-4",
      "temperature": 0.3,
      "max_tokens": 1024,
      "tools": ["web_search", "knowledge_base"],
      "system_prompt": "You are a helpful customer support agent for Connix. Always be polite and helpful."
    }
  }'

Response:

{
  "id": "agent_9876543210fedcba",
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries and support requests",
  "project_id": "proj_1234567890abcdef",
  "status": "creating",
  "config": {
    "model": "gpt-4",
    "temperature": 0.3,
    "max_tokens": 1024,
    "tools": ["web_search", "knowledge_base"],
    "system_prompt": "You are a helpful customer support agent for Connix. Always be polite and helpful.",
    "environment_variables": {
      "SUPPORT_QUEUE": "high_priority",
      "ESCALATION_THRESHOLD": "3"
    }
  },
  "metadata": {
    "created_by": "user_1234567890abcdef",
    "environment": "production",
    "team": "customer-success",
    "version": "1.0.0"
  },
  "created_at": "2024-01-15T16:45:00Z",
  "updated_at": "2024-01-15T16:45:00Z",
  "last_activity": null
}

Get Agent

Retrieve details of a specific agent.

Request:

GET /projects/{project_id}/agents/{agent_id}

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
agent_id	string	Yes	ID of the agent

Example Request:

curl -X GET "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "id": "agent_1234567890abcdef",
  "name": "Data Analysis Agent",
  "description": "Processes customer data and generates insights",
  "project_id": "proj_1234567890abcdef",
  "status": "running",
  "config": {
    "model": "gpt-4",
    "temperature": 0.7,
    "max_tokens": 2048,
    "tools": ["web_search", "code_execution", "data_analysis"],
    "system_prompt": "You are a data analysis expert...",
    "environment_variables": {
      "DATA_SOURCE": "postgres://...",
      "CACHE_TTL": "3600"
    }
  },
  "metadata": {
    "created_by": "user_1234567890abcdef",
    "environment": "production",
    "version": "1.2.3",
    "team": "analytics"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T14:45:00Z",
  "last_activity": "2024-01-15T16:20:00Z",
  "stats": {
    "total_tasks": 1247,
    "completed_tasks": 1198,
    "failed_tasks": 23,
    "success_rate": 0.961,
    "avg_response_time": 2.3
  }
}

Update Agent

Update an existing agent’s configuration.

Request:

PUT /projects/{project_id}/agents/{agent_id}

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
agent_id	string	Yes	ID of the agent

Request Body:

{
  "name": "Enhanced Data Analysis Agent",
  "description": "Advanced data processing with ML capabilities",
  "config": {
    "model": "gpt-4-turbo",
    "temperature": 0.5,
    "max_tokens": 4096,
    "tools": ["web_search", "code_execution", "data_analysis", "ml_training"],
    "system_prompt": "You are an advanced data scientist...",
    "environment_variables": {
      "DATA_SOURCE": "postgres://new-connection...",
      "CACHE_TTL": "7200",
      "ML_ENDPOINT": "https://ml.example.com/api"
    }
  },
  "metadata": {
    "environment": "production",
    "team": "ml-engineering",
    "version": "2.0.0"
  }
}

Example Request:

curl -X PUT "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef" \
  -H "X-API-Key: cx_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Enhanced Data Analysis Agent",
    "config": {
      "model": "gpt-4-turbo",
      "temperature": 0.5,
      "max_tokens": 4096
    }
  }'

Response:

{
  "id": "agent_1234567890abcdef",
  "name": "Enhanced Data Analysis Agent",
  "description": "Advanced data processing with ML capabilities",
  "project_id": "proj_1234567890abcdef",
  "status": "updating",
  "config": {
    "model": "gpt-4-turbo",
    "temperature": 0.5,
    "max_tokens": 4096,
    "tools": ["web_search", "code_execution", "data_analysis", "ml_training"],
    "system_prompt": "You are an advanced data scientist...",
    "environment_variables": {
      "DATA_SOURCE": "postgres://new-connection...",
      "CACHE_TTL": "7200",
      "ML_ENDPOINT": "https://ml.example.com/api"
    }
  },
  "metadata": {
    "created_by": "user_1234567890abcdef",
    "environment": "production",
    "team": "ml-engineering",
    "version": "2.0.0"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T17:15:00Z",
  "last_activity": "2024-01-15T16:20:00Z"
}

Delete Agent

Delete an agent and all associated data.

Request:

DELETE /projects/{project_id}/agents/{agent_id}

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
agent_id	string	Yes	ID of the agent

Example Request:

curl -X DELETE "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "message": "Agent deleted successfully",
  "agent_id": "agent_1234567890abcdef"
}

Agent Actions

Start Agent

Start a paused or stopped agent.

Request:

POST /projects/{project_id}/agents/{agent_id}/start

Example Request:

curl -X POST "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/start" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "message": "Agent started successfully",
  "agent_id": "agent_1234567890abcdef",
  "status": "running"
}

Pause Agent

Temporarily pause a running agent.

Request:

POST /projects/{project_id}/agents/{agent_id}/pause

Example Request:

curl -X POST "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/pause" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "message": "Agent paused successfully",
  "agent_id": "agent_1234567890abcdef",
  "status": "paused"
}

Stop Agent

Stop a running agent.

Request:

POST /projects/{project_id}/agents/{agent_id}/stop

Example Request:

curl -X POST "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/stop" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "message": "Agent stopped successfully",
  "agent_id": "agent_1234567890abcdef",
  "status": "stopped"
}

Restart Agent

Restart an agent (stop and start).

Request:

POST /projects/{project_id}/agents/{agent_id}/restart

Example Request:

curl -X POST "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/restart" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "message": "Agent restarted successfully",
  "agent_id": "agent_1234567890abcdef",
  "status": "running"
}

Agent Logs

Get Agent Logs

Retrieve logs for an agent.

Request:

GET /projects/{project_id}/agents/{agent_id}/logs

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
agent_id	string	Yes	ID of the agent
level	string	No	Filter by log level: debug, info, warn, error
start_time	string	No	Start time (ISO 8601 format)
end_time	string	No	End time (ISO 8601 format)
limit	integer	No	Number of log entries (1-1000, default: 100)
offset	integer	No	Offset for pagination (default: 0)

Example Request:

curl -X GET "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/logs?level=error&limit=50" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "logs": [
    {
      "timestamp": "2024-01-15T16:20:00Z",
      "level": "info",
      "message": "Task completed successfully",
      "context": {
        "task_id": "task_1234567890abcdef",
        "duration": 2.34,
        "tokens_used": 156
      }
    },
    {
      "timestamp": "2024-01-15T16:18:30Z",
      "level": "error",
      "message": "Failed to connect to external API",
      "context": {
        "error": "Connection timeout",
        "endpoint": "https://api.example.com/data",
        "retry_count": 3
      }
    }
  ],
  "pagination": {
    "total": 1247,
    "limit": 50,
    "offset": 0,
    "has_more": true
  }
}

Agent Metrics

Get Agent Metrics

Retrieve performance metrics for an agent.

Request:

GET /projects/{project_id}/agents/{agent_id}/metrics

Parameters:

Parameter	Type	Required	Description
project_id	string	Yes	ID of the project
agent_id	string	Yes	ID of the agent
start_time	string	No	Start time for metrics (ISO 8601 format)
end_time	string	No	End time for metrics (ISO 8601 format)
interval	string	No	Aggregation interval: 1m, 5m, 15m, 1h, 1d

Example Request:

curl -X GET "https://api.connix.io/api/v1/projects/proj_1234567890abcdef/agents/agent_1234567890abcdef/metrics?interval=1h" \
  -H "X-API-Key: cx_your_api_key_here"

Response:

{
  "metrics": {
    "tasks": {
      "total": 1247,
      "completed": 1198,
      "failed": 23,
      "in_progress": 26,
      "success_rate": 0.961
    },
    "performance": {
      "avg_response_time": 2.34,
      "p95_response_time": 8.12,
      "p99_response_time": 15.67,
      "tokens_per_minute": 1245.6,
      "requests_per_minute": 24.3
    },
    "resource_usage": {
      "cpu_usage": 0.45,
      "memory_usage": 0.67,
      "disk_usage": 0.23,
      "network_in": 1234567,
      "network_out": 987654
    },
    "time_series": [
      {
        "timestamp": "2024-01-15T15:00:00Z",
        "tasks_completed": 12,
        "avg_response_time": 2.1,
        "cpu_usage": 0.42,
        "memory_usage": 0.65
      },
      {
        "timestamp": "2024-01-15T16:00:00Z",
        "tasks_completed": 15,
        "avg_response_time": 2.6,
        "cpu_usage": 0.48,
        "memory_usage": 0.69
      }
    ]
  },
  "period": {
    "start_time": "2024-01-15T15:00:00Z",
    "end_time": "2024-01-15T17:00:00Z",
    "interval": "1h"
  }
}

Error Responses

400 Bad Request

{
  "error": {
    "code": "validation_error",
    "message": "Invalid agent configuration",
    "details": [
      {
        "field": "config.temperature",
        "message": "Temperature must be between 0 and 2"
      },
      {
        "field": "config.max_tokens",
        "message": "Max tokens must be a positive integer"
      }
    ]
  }
}

401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key or expired token"
  }
}

403 Forbidden

{
  "error": {
    "code": "insufficient_permissions",
    "message": "You don't have permission to access this agent"
  }
}

404 Not Found

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent with ID 'agent_1234567890abcdef' not found"
  }
}

409 Conflict

{
  "error": {
    "code": "agent_conflict",
    "message": "Agent name already exists in this project"
  }
}

429 Too Many Requests

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 60 seconds.",
    "retry_after": 60
  }
}

500 Internal Server Error

{
  "error": {
    "code": "internal_error",
    "message": "An unexpected error occurred. Please try again later.",
    "request_id": "req_1234567890abcdef"
  }
}

SDK Examples

JavaScript/TypeScript

import { ConnixClient } from '@connix/sdk';

const client = new ConnixClient('cx_your_api_key_here');

// Create an agent
const agent = await client.agents.create('proj_1234567890abcdef', {
  name: 'Customer Support Agent',
  description: 'Handles customer inquiries',
  config: {
    model: 'gpt-4',
    temperature: 0.3,
    max_tokens: 1024,
    tools: ['web_search', 'knowledge_base']
  }
});

// List agents
const agents = await client.agents.list('proj_1234567890abcdef', {
  status: 'running',
  limit: 10
});

// Get agent details
const agentDetails = await client.agents.get('proj_1234567890abcdef', 'agent_1234567890abcdef');

// Update agent
const updatedAgent = await client.agents.update('proj_1234567890abcdef', 'agent_1234567890abcdef', {
  config: {
    temperature: 0.5
  }
});

// Start agent
await client.agents.start('proj_1234567890abcdef', 'agent_1234567890abcdef');

// Get agent logs
const logs = await client.agents.logs('proj_1234567890abcdef', 'agent_1234567890abcdef', {
  level: 'error',
  limit: 50
});

// Get agent metrics
const metrics = await client.agents.metrics('proj_1234567890abcdef', 'agent_1234567890abcdef', {
  interval: '1h'
});

Python

import connix

client = connix.Client('cx_your_api_key_here')

# Create an agent
agent = client.agents.create('proj_1234567890abcdef', {
    'name': 'Customer Support Agent',
    'description': 'Handles customer inquiries',
    'config': {
        'model': 'gpt-4',
        'temperature': 0.3,
        'max_tokens': 1024,
        'tools': ['web_search', 'knowledge_base']
    }
})

# List agents
agents = client.agents.list('proj_1234567890abcdef', status='running', limit=10)

# Get agent details
agent_details = client.agents.get('proj_1234567890abcdef', 'agent_1234567890abcdef')

# Update agent
updated_agent = client.agents.update('proj_1234567890abcdef', 'agent_1234567890abcdef', {
    'config': {
        'temperature': 0.5
    }
})

# Start agent
client.agents.start('proj_1234567890abcdef', 'agent_1234567890abcdef')

# Get agent logs
logs = client.agents.logs('proj_1234567890abcdef', 'agent_1234567890abcdef', level='error', limit=50)

# Get agent metrics
metrics = client.agents.metrics('proj_1234567890abcdef', 'agent_1234567890abcdef', interval='1h')

Go

package main

import (
    "context"
    "log"

    "github.com/connix-io/connix-go"
)

func main() {
    client := connix.NewClient("cx_your_api_key_here")
    ctx := context.Background()

    // Create an agent
    agent, err := client.Agents.Create(ctx, "proj_1234567890abcdef", &connix.CreateAgentRequest{
        Name:        "Customer Support Agent",
        Description: "Handles customer inquiries",
        Config: &connix.AgentConfig{
            Model:       "gpt-4",
            Temperature: 0.3,
            MaxTokens:   1024,
            Tools:       []string{"web_search", "knowledge_base"},
        },
    })
    if err != nil {
        log.Fatal(err)
    }

    // List agents
    agents, err := client.Agents.List(ctx, "proj_1234567890abcdef", &connix.ListAgentsOptions{
        Status: "running",
        Limit:  10,
    })
    if err != nil {
        log.Fatal(err)
    }

    // Get agent details
    agentDetails, err := client.Agents.Get(ctx, "proj_1234567890abcdef", "agent_1234567890abcdef")
    if err != nil {
        log.Fatal(err)
    }

    // Start agent
    err = client.Agents.Start(ctx, "proj_1234567890abcdef", "agent_1234567890abcdef")
    if err != nil {
        log.Fatal(err)
    }

    // Get agent logs
    logs, err := client.Agents.Logs(ctx, "proj_1234567890abcdef", "agent_1234567890abcdef", &connix.LogsOptions{
        Level: "error",
        Limit: 50,
    })
    if err != nil {
        log.Fatal(err)
    }
}

Rate Limits

Endpoint	Limit	Window
List Agents	100 requests	1 minute
Create Agent	10 requests	1 minute
Get Agent	200 requests	1 minute
Update Agent	20 requests	1 minute
Delete Agent	10 requests	1 minute
Agent Actions	50 requests	1 minute
Agent Logs	100 requests	1 minute
Agent Metrics	50 requests	1 minute

Rate limits are per API key and reset at the beginning of each time window. Headers are included in responses to indicate current usage:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 1705334400

Next Steps

• Projects API - Manage projects and environments
• Authentication - API authentication methods
• Error Handling - Comprehensive error reference