Agents API Endpoints

Die Agents API verwaltet deine MaxiCore-Agents. Alle Requests erfordern Bearer-Token Authentifizierung.

Agents auflisten

GET /v2/agents

Query Parameter:

• workspace_id — Filter nach Workspace
• status — "online", "offline", "error"
• limit — Pagination (default: 20, max: 100)
• offset — Pagination Offset

Beispiel:

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.maxicore.ch/v2/agents?status=online&limit=10"

Response (200):

{
  "success": true,
  "data": {
    "items": [
      {
        "id": "agent-123",
        "name": "Python Dev Agent",
        "status": "online",
        "workspace_id": "ws-456",
        "mode": "computer",
        "last_activity": "2026-03-27T10:30:00Z",
        "credits_used": 5420
      }
    ],
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

Agent-Details abrufen

GET /v2/agents/{agent_id}

Beispiel:

curl -H "Authorization: Bearer $TOKEN" \
  https://api.maxicore.ch/v2/agents/agent-123

Response (200):

{
  "success": true,
  "data": {
    "id": "agent-123",
    "name": "Python Dev Agent",
    "status": "online",
    "mode": "computer",
    "workspace_id": "ws-456",
    "created_at": "2026-03-01T08:00:00Z",
    "last_activity": "2026-03-27T10:30:00Z",
    "soul": {
      "name": "Alpha",
      "role": "Software Developer",
      "capabilities": ["python", "bash", "git"]
    },
    "shield": {
      "version": "2.0",
      "filesystem": { /* ... */ },
      "commands": { /* ... */ }
    }
  }
}

Agent erstellen

POST /v2/agents

Body:

{
  "name": "Data Pipeline Agent",
  "workspace_id": "ws-456",
  "mode": "computer",
  "soul": {
    "name": "DataBot",
    "role": "Data Engineer",
    "capabilities": ["python", "sql", "bash"],
    "memory": {
      "long_term_enabled": true,
      "max_history": 5000
    }
  },
  "shield": {
    "filesystem": {
      "allowed_paths": ["/data", "/tmp"],
      "blocked_paths": ["/root", "/etc"]
    }
  }
}

Response (201):

{
  "success": true,
  "data": {
    "id": "agent-789",
    "name": "Data Pipeline Agent",
    "pairing_key": "MC-DATA-789XXXX-YYYYYY"
  }
}

Agent aktualisieren

PUT /v2/agents/{agent_id}

Body (Felder optional):

{
  "name": "Production Data Pipeline",
  "soul": {
    "tone": "professional",
    "verbosity": "brief"
  }
}

Response (200): Aktualisiertes Agent-Objekt

Agent löschen

DELETE /v2/agents/{agent_id}

Query:

• purge=true — Auch alle Tasks und Logs löschen (default: false)

Response (204): Kein Content (erfolgreich gelöscht)

Soul-Dokument aktualisieren

POST /v2/agents/{agent_id}/soul

Body (YAML oder JSON):

{
  "name": "DataBot v2",
  "personality": {
    "tone": "technical",
    "proactivity": "medium"
  },
  "constraints": {
    "max_concurrent_tasks": 5,
    "timeout_seconds": 1800
  }
}

Response (200): Aktualisierte Soul

Shield-Policies abrufen

GET /v2/agents/{agent_id}/shield

Response (200):

{
  "success": true,
  "data": {
    "version": "2.0",
    "filesystem": { /* ... */ },
    "commands": { /* ... */ },
    "network": { /* ... */ }
  }
}

Shield-Policies aktualisieren

PUT /v2/agents/{agent_id}/shield

Body:

{
  "filesystem": {
    "allowed_paths": ["/project/**"],
    "blocked_paths": ["/root", "~/.ssh"]
  },
  "commands": {
    "allowed_patterns": ["^python .*", "^git .*"],
    "blocked_patterns": ["rm -rf"]
  }
}

Validation: Shield wird vor Speicherung validiert. Response (200): Aktualisierte Shield

Error Responses

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_AGENT_NAME",
    "message": "Agent name must be 1-255 characters"
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "Token expired or invalid"
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "AGENT_NOT_FOUND",
    "message": "Agent does not exist"
  }
}

429 Too Many Requests

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Try again in 60 seconds"
  }
}

Siehe auch

• Tasks API — Task-Management
• WebSocket — Echtzeit Events
• Authentication — Auth-Methoden